1. Clarify goal and constraints
   • Confirm expected behavior, non-goals, and compatibility constraints (target backend, public API stability, performance limits).
2. Locate module/package boundaries
   • Find

     moon.mod.json

     (module root) and relevant

     moon.pkg

     files (package boundaries and imports).
3. Discover APIs before coding
   • Prefer

     moon ide doc

     queries to discover existing functions/types/methods before adding new code.
   • Use

     moon ide outline

     ,

     moon ide peek-def

     , and

     moon ide find-references

     for semantic navigation.
4. Reliable refactoring
   • Use

     moon ide rename

     for semantic refactoring. If multiple symbols share a name, add

     --loc filename:line:col

     .
   • If you want maintain backwards compatibility, use

     #alias(old_api, deprecated)

     .
5. Edit minimally and package-locally
   • Keep changes inside the correct package, use

     ///|

     top-level delimiters, and split code into cohesive files.
6. Validate in a tight loop
   • Run

     moon check

     after edits, adding

     --warn-list +unnecessary_annotation

     to enable warning 73 for redundant annotations and over-qualified constructors (

     --warn-list +73

     is equivalent).
   • Run targeted tests with

     moon test [dirname|filename] --filter 'glob'

     and use

     moon test --update

     for snapshot changes.
7. Finalize before handoff
   • Run

     moon fmt

     .
   • Run

     moon info

     to verify whether public APIs changed (

     pkg.generated.mbti

     diff).
   • Report changed files, validation commands, and any remaining risks.

1. Reproduce or identify the failing behavior.
2. Locate symbols with

   moon ide outline

   ,

   moon ide peek-def

   ,

   moon ide find-references

   .
3. Implement minimal fix in the current package.
4. Validate with:

   • moon check

   • moon test [dirname|filename] --filter 'glob'

     (or closest targeted test scope)

   • moon fmt

   • moon info

     (confirm

     pkg.generated.mbti

     unchanged)

1. Confirm behavior/API invariants first.
2. Prefer semantic rename/navigation tools:

   • moon ide rename

   • moon ide find-references

   • moon ide peek-def

   • If multiple symbols share a name, use

     moon ide rename <symbol> <new_name> --loc filename:line:col

     .
3. Keep edits package-local and file-organization-focused.
4. Validate with:

   • moon check

   • moon test [dirname|filename]

   • moon fmt

   • moon info

     (API should remain unchanged unless requested)

1. Discover existing idioms with

   moon ide doc

   before introducing new names.
2. Add implementation in cohesive files with

   ///|

   delimiters.
3. Add/extend black-box tests and docstring examples for public APIs.
4. Validate with:

   • moon check

   • moon test [dirname|filename]

     (use

     --update

     for snapshots when needed)

   • moon fmt

   • moon info

     (review and keep intended

     pkg.generated.mbti

     changes)

my_module
├── moon.mod.json             # Module metadata, source field (optional) specifies the source directory of the module
├── moon.pkg             # Package metadata (each directory is a package like Golang)
├── README.mbt.md             # Markdown with tested code blocks (`test "..." { ... }`)
├── README.md -> README.mbt.md
├── cmd                       # Command line directory
│   └── main
│       ├── main.mbt
│       └── moon.pkg     # executable package with `options("is-main": true)`
├── liba/                     # Library packages
│   └── moon.pkg         # Referenced by other packages as `@username/my_module/liba`
│   └── libb/                 # Library packages
│       └── moon.pkg     # Referenced by other packages as `@username/my_module/liba/libb`
├── user_pkg.mbt              # Root packages, referenced by other packages as `@username/my_module`
├── user_pkg_wbtest.mbt       # White-box tests (only needed for testing internal private members, similar to Golang's package mypackage)
└── user_pkg_test.mbt         # Black-box tests
└── ...                       # More package files, symbols visible to current package (like Golang)

• Module: characterized by a

  moon.mod.json

  file in the project root directory. A MoonBit module is like a Go module; it is a collection of packages in subdirectories, usually corresponding to a repository or project. Module boundaries matter for dependency management and import paths.
• Package: characterized by a

  moon.pkg

  file in each directory. All subcommands of

  moon

  will still be executed in the directory of the module (where

  moon.mod.json

  is located), not the current package. A MoonBit package is the actual compilation unit (like a Go package). All source files in the same package are concatenated into one unit and thereby share all definitions throughout that package. The

  name

  in the

  moon.mod.json

  file combined with the relative path to the package source directory defines the package name, not the file name. Imports refer to module + package paths, NEVER to file names.
• Files: A

  .mbt

  file is just a chunk of source code inside a package. File names do NOT create modules, packages, or namespaces. You may freely split/merge/move declarations between files in the same package. Any declaration in a package can reference any other declaration in that package, regardless of file.

1. Prefer many small, cohesive files over one large file.
   • Group related types and functions into focused files (e.g. http_client.mbt, router.mbt).
   • If a file is getting large or unfocused, create a new file and move related declarations into it.
2. You MAY freely move declarations between files inside the same package.
   • Each block is separated by

     ///|

     . Moving a function/struct/trait between files does not change semantics, as long as its name and pub-ness stay the same. The order of each block is irrelevant too.
   • It is safe to refactor by splitting or merging files inside a package.
3. File names are purely organizational.
   • Do NOT assume file names define modules, and do NOT use file names in type paths.
   • Choose file names to describe a feature or responsibility, not to mirror type names rigidly.
4. When adding new code:
   • Prefer adding it to an existing file that matches the feature.
   • If no good file exists, create a new file under the same package with a descriptive name.
   • Avoid creating giant "impl", “misc”, or “util” files.
5. Tests:
   • Place tests in dedicated test files (e.g.

     *_test.mbt

     ) within the appropriate package. For a package (besides

     *_test.mbt

     files),

     *.mbt.md

     files are also blackbox test files in addition to Markdown files. The code blocks (separated by triple backticks)

     mbt check

     are treated as test cases and serve both purposes: documentation and tests. You may have

     README.mbt.md

     files with

     mbt check

     code examples. You can also symlink

     README.mbt.md

     to

     README.md

     to make it integrate better with GitHub.
   • It is fine — and encouraged — to have multiple small test files.
6. Interface files (

   pkg.generated.mbti

   )

   pkg.generated.mbti

   files are compiler-generated summaries of each package's public API surface. They provide a formal, concise overview of all exported types, functions, and traits without implementation details. They are generated using

   moon info

   and useful for code review. When you have a commit that does not change public APIs,

   pkg.generated.mbti

   files will remain unchanged, so it is recommended to put

   pkg.generated.mbti

   in version control when you are done.
   For IDE navigation and symbol lookup commands, see the dedicated

   moon ide

   section below.

• Don't use uppercase for variables/functions - compilation error
• Don't forget

  mut

  for mutable record fields - immutable by default (note that Arrays typically do NOT need

  mut

  unless completely reassigning to the variable - simple push operations, for example, do not need

  mut

  )
• Don't ignore error handling - errors must be explicitly handled
• Don't use

  return

  unnecessarily - the last expression is the return value
• Don't create methods without Type:: prefix - methods need explicit type prefix
• Don't forget to handle array bounds - use

  get()

  for safe access
• Don't forget @package prefix when calling functions from other packages
• Don't use ++ or -- (not supported) - use

  i = i + 1

  or

  i += 1

• Don't add explicit

  try

  for error-raising functions - errors propagate automatically (unlike Swift)
• Legacy syntax: Legacy code may use

  function_name!(...)

  or

  function_name(...)?

  - these are deprecated, use normal calls.
• Prefer range

  for

  loops over C-style -

  for i in 0..<(n-1) {...}

  and

  for j in 0..=6 {...}

  are more idiomatic in MoonBit
• Async - MoonBit has no

  await

  keyword; do not add it. Async functions and tests are characterized by those which call other async functions. To identify a function or test as async, simply add the

  async

  prefix (e.g.

  [pub] async fn ...

  ,

  async test ...

  ).

• moon new my_project

  - Create new project

• moon run cmd/main

  - Run main package

• moon run - < hello.mbt

  - Run code from stdin (useful for quick experiments)

• moon run -e "code snippet"

  - Run code from command line argument (good for one-liners) Example:
  bash

  cat hello.mbt | moon run -

  This allows you to quickly test small snippets of MoonBit code without creating a full project. It can also be used with heredoc syntax for multi-line snippets:
  bash

  moon run - <<'EOF'
  fn main {
    println("Hello, MoonBit!")
  }
  EOF

  moon run -e 'fn main { println("Hello, MoonBit!") }'

• moon build

  - Build project (

  moon run

  and

  moon build

  both support

  --target

  )

• moon check

  - Type check without building, use it REGULARLY, it is fast (

  moon check

  also supports

  --target

  )

• moon info

  - Type check and generate

  mbti

  files. Run it to see if any public interfaces changed. (

  moon info

  also supports

  --target

  .)

• moon check --target all

  - Type check for all backends moon check --output-json can be used with

  jq

  to filter the output, e.g,

  moon check --output-json 2>&1 | jq -R 'fromjson? | select(.message |
      contains("unused"))'

  or, for richer post-processing, pipe into a small MoonBit program via

  moon run -e

  . Use

  --target native

  (the default

  wasm-gc

  does not support

  async fn main

  or

  @stdio.stdin

  ), a quoted heredoc (

  <<'EOF'

  ) so the shell does not expand

  $

  /backticks in the source, and a de-indented closing

  EOF

  :

  undefined

Get the diagnostics with "unused" in the message, which can be used to find unused code.
- `moon explain` - Show built-in documentation for compiler diagnostics.
- `moon explain --diagnostics` lists warning mnemonics and IDs.
- `moon explain --diagnostics 31` explains warning 31 (`unused_optional_argument`).
- `moon explain --diagnostics unused_optional_argument` explains the same warning by mnemonic.
- `moon add package` - Add dependency
- `moon remove package` - Remove dependency
- `moon fmt` - Format code - should be run periodically - note that the files may be rewritten
Note you can also use `moon -C dir check` to run commands in a specific directory.

• moon test

  - Run all tests (

  moon test

  also supports

  --target

  )

• moon test --update

  - Update snapshots

• moon test -v

  - Verbose output with test names

• moon test [dirname|filename]

  - Test specific directory or file

• moon coverage analyze

  - Analyze coverage

• moon test [dirname|filename] --filter 'glob'

  - Run tests matching filter

  moon test float/float_test.mbt --filter "Float::*"
  moon test float -F "Float::*" // shortcut syntax

• Output

  README.mbt.md

  in the package directory.

  *.mbt.md

  file and docstring contents treats

  mbt check

  specially.

  mbt check

  block will be included directly as code and also run by

  moon check

  and

  moon test

  . If you don't want the code snippets to be checked, explicit

  mbt nocheck

  is preferred. If you are only referencing types from the package, you should use

  mbt nocheck

  which will only be syntax highlighted. Symlink

  README.mbt.md

  to

  README.md

  to adapt to systems that expect

  README.md

  .

• Snapshot Tests:

  inspect(value, content="...")

  . If unknown, write

  inspect(value)

  and run

  moon test --update

  (or

  moon test -u

  ).
  • Use regular

    inspect()

    for simple values (uses

    Show

    trait)
  • Use

    @json.inspect()

    for complex nested structures (uses

    ToJson

    trait, produces more readable output)
  • It is encouraged to

    inspect

    or

    @json.inspect

    the whole return value of a function if the whole return value is not huge, this makes the test simple. You need

    impl (Show|ToJson) for YourType

    or

    derive (Show, ToJson)

    .
• Update workflow: After changing code that affects output, run

  moon test --update

  to regenerate snapshots, then review the diffs in your test files (the

  content=

  parameter will be updated automatically).
• Validation order: Follow the canonical sequence in

  Agent Workflow

  and

  Fast Task Playbooks

  .
• Black-box by default: Call only public APIs via

  @package.fn

  . Use white-box tests only when private members matter.
• Grouping: Combine related checks in one

  test "..." { ... }

  block for speed and clarity.
• Panics: Name tests with prefix

  test "panic ..." {...}

  ; if the call returns a value, wrap it with

  ignore(...)

  to silence warnings.
• Errors: Use

  try? f()

  to get

  Result[...]

  and

  inspect

  it when a function may raise.

• The spec can be written in a readonly

  spec.mbt

  file (name is conventional, not mandatory) with stub code marked as declarations:

///|
declare pub type Yaml

///|
declare pub fn Yaml::to_string(y : Yaml) -> String raise

///|
declare pub impl Eq for Yaml

///|
declare pub fn parse_yaml(s : String) -> Yaml raise

• Add

  spec_easy_test.mbt

  ,

  spec_difficult_test.mbt

  , etc. to test the spec functions; everything will be type-checked(

  moon check

  ).
• The AI or users can implement the

  declare

  functions in different files thanks to our package organization.
• Run

  moon test

  to check everything is correct.

• declare

  is supported for functions, methods, and types.
• The

  pub type Yaml

  line is an intentionally opaque placeholder; the implementer chooses its representation.
• Note the spec file can also contain normal code, not just declarations.

• moon ide doc <query>

  to discover available APIs, functions, types, and methods in MoonBit. Always prefer

  moon ide doc

  over other approaches when exploring what APIs are available, it is more powerful and accurate than

  grep_search

  or any regex-based searching tools.

• moon ide outline .

  to scan a package,

• moon ide find-references <symbol>

  to locate usages, and

• moon ide peek-def

  for inline definition context and to locate toplevel symbols.

• moon ide hover sym --loc filename:line:col

  to get type information at a specific location.

• moon ide rename <symbol> <new_name> [--loc filename:line:col]

  to rename a symbol project-wide. Prefer

  --loc

  when symbol names are ambiguous.

• moon ide analyze [path]

  to inspect public API usage of a package or module when planning safe refactors. These tools save tokens and are more precise than grepping (

  grep

  displays results in both definitions and call sites including comments too).

moon ide doc

• Empty query:

  moon ide doc ''

  • In a module: shows all available packages in current module, including dependencies and moonbitlang/core
  • In a package: shows all symbols in current package
  • Outside package: shows all available packages
• Function/value lookup:

  moon ide doc "[@pkg.]value_or_function_name"

• Type lookup:

  moon ide doc "[@pkg.]Type_name"

  (builtin type does not need package prefix)
• Method/field lookup:

  moon ide doc "[@pkg.]Type_name::method_or_field_name"

• Package exploration:

  moon ide doc "@pkg"

  • Show package

    pkg

    and list all its exported symbols
  • Example:

    moon ide doc "@json"

    - explore entire

    @json

    package
  • Example:

    moon ide doc "@encoding/utf8"

    - explore nested package
• Multiple queries:

  moon ide doc "query1" "query2" ...

  • Run multiple queries in one invocation and combine results
  • Example:

    moon ide doc "String" "Array" "@json"

    to explore multiple types and a package at once
• Globbing: Use

  *

  wildcard for partial matches, e.g.

  moon ide doc "String::*rev*"

  to find all String methods with "rev" in their name

... more methods omitted ...

... more

**Best practice**: Treat this section as command reference; execution order is defined in `Agent Workflow`.

moon ide outline

• moon ide outline dir

  outlines the current package directory (per-file headers)

• moon ide outline parser.mbt

  outlines a single file This is useful when you need a quick inventory of a package, or to find the right file before

  peek-def

  .

• moon ide find-references TranslationUnit

  finds all references to a symbol in the current module

$ moon ide outline .
spec.mbt:
 L003 | pub(all) enum CStandard {
        ...
 L013 | pub(all) struct Position {
        ...

$ moon ide find-references TranslationUnit

• Import format:

  "module_name/package_path"

• Usage:

  @alias.function()

  to call imported functions
• Default alias: Last part of path (e.g.,

  liba

  for

  username/hello/liba

  )
• Package reference: Use

  @packagename

  in test files to reference the tested package

• Import

  "username/hello/liba"

  → use

  @liba.function()

  (default alias is the last path segment)
• Import with custom alias

  import { "moonbitlang/x/encoding" @enc}

  → use

  @enc.function()

  (Note that this is unnecessary when the last path segment is identical to the alias name.)
• In

  _test.mbt

  or

  _wbtest.mbt

  files, the package being tested is auto-imported

///|
/// In main.mbt after importing "username/hello/liba" in `moon.pkg`
fn main {
  println(@liba.hello()) // Calls hello() from liba package
}

fib

.

1. Create directory:

   ./fib/

2. Add

   ./fib/moon.pkg

3. Add

   .mbt

   files with your code
4. Import in dependent packages:

     import {
      "username/hello/fib",
     }

conditional compilation

link configuration

warning control

pre-build commands

references/advanced-moonbit-build.md

moonbitlang/async

moon add moonbitlang/async@<version>

moon ide doc "@async"

@async

@async/aqueue

@async/fs, 

, 

, ..etc. Each must be imported separately in 

1. Add the dependency and pin the native target in

   moon.mod.json

   :
   json

   {
     "deps": { "moonbitlang/async": "0.18.1" },
     "preferred-target": "native"
   }

2. In the executable's

   moon.pkg

   , set

   is-main

   , restrict to native, and import what you need:

   import {
     "moonbitlang/async",
     "moonbitlang/async/stdio",
   }
   supported_targets = "+native"
   options("is-main": true)

3. Define

   async fn main

   (not

   fn main

   ). Spawn concurrent tasks via

   with_task_group

   for structured concurrency:
   mbt

   ///|
   async fn main {
     @async.with_task_group(group => {
       group.spawn_bg(() => {
         @async.sleep(50)
         @stdio.stdout.write("A\n")
       })
       group.spawn_bg(() => {
         @async.sleep(20)
         @stdio.stdout.write("B\n")
       })
     })
   }

with_task_group

• When

  with_task_group

  returns, every task spawned in the group is guaranteed to have terminated — no orphan tasks, no resource leaks.
• If any spawned task fails (and was spawned without

  allow_failure=true

  ), the whole group fails: every other task in the group is cancelled, and the error propagates out of

  with_task_group

  .
• Cancelled tasks are not considered failures; they raise a cancellation error but don't trigger peer cancellation.

spawn_bg

spawn

• ✅

  () => { ... }

  — idiomatic; async-ness is inferred from context.
• ✅

  async fn() { ... }

  — explicit annotation; equivalent to the arrow form.
• ⚠️

  fn() { ... }

  — triggers

  Warning [0027] deprecated_syntax

  : "this

  fn

  is asynchronous but not annotated with

  async

  ". Don't use.
• ❌

  async () => ...

  ,

  fn() async { ... }

  ,

  fn(args) async { ... }

  — all parse errors.

  async

  only goes before

  fn

  , never before an arrow lambda or after a parameter list.

async test

moonbitlang/async

for "test"

import {
  "moonbitlang/async",
  "moonbitlang/async/stdio",
} for "test"

///|
async test "sleep completes" {
  @async.sleep(1)
  inspect("done", content="done")
}

• There is no

  await

  keyword (similar to functions that raise errors). Inside an

  async test

  , call async functions normally.
• Async tests run in parallel by default. Avoid shared ports, files, environment variables, and global mutable state unless each test isolates its resources.
• Run with

  moon test --target native

  unless

  moon.mod.json

  sets

  "preferred-target": "native"

  . Use

  moon test -v

  when checking test names or async scheduling behavior.
• In

  README.mbt.md

  and docstrings,

  mbt check

  blocks may contain

  async test

  blocks; make sure the package imports

  moonbitlang/async

  for the relevant test mode.

• Expression‑oriented:

  if

  ,

  match

  , loops return values; the last expression is the return value.
• References by default: Arrays/Maps/structs mutate via reference; use

  Ref[T]

  for primitive mutability.
• Blocks: Separate top‑level items with

  ///|

  . Generate code block‑by‑block. If a blank line is desired within a block (enclosed by curly braces), add a comment line after the blank line (with or without comment text).
• Visibility:

  fn

  is private by default;

  pub

  exposes read/construct as allowed;

  pub(all)

  allows external construction.
• Naming convention: lower_snake for values/functions; UpperCamel for types/enums; enum variants start UpperCamel.
• Packages: No

  import

  in code files; call via

  @alias.fn

  . Configure imports in

  moon.pkg

  .
• Placeholders:

  ...

  is a valid placeholder in MoonBit code for incomplete implementations.
• Global values: immutable by default and generally require type annotations.
• Garbage collection: MoonBit has a GC, there is no lifetime annotation, there's no ownership system. Unlike Rust, like F#,

  let mut

  is only needed when you want to reassign a variable, not for mutating fields of a struct or elements of an array/map.

StringView

BytesView

ArrayView[T]

[:]

String

Bytes

Array

*View

• String

  →

  StringView

  via

  s[:]

  or

  s[start:end]

  or

  s[start:]

  or

  s[:end]

• Bytes

  →

  BytesView

  via

  b[:]

  or

  b[start:end]

  , etc.

• Array[T]

  ,

  FixedArray[T]

  ,

  ReadOnlyArray[T] → 

  ArrayView[T]

  via

  a[:]

  or

  a[start:end]`, etc.

s[a:b]

• Use

  try! s[a:b]

  if you're certain the boundaries are valid (crashes on invalid boundaries)
• Let the error propagate to the caller for proper handling

• Pattern matching with rest patterns (

  [first, .. rest]

  )
• Passing slices to functions without allocation overhead
• Avoiding unnecessary copies of large sequences

.to_string()

.to_bytes()

.to_array()

moon ide doc StringView

where

for

for .. in

for ... {
  ...
} where {
  invariant : <boolean_expr>,   // checked at runtime in debug builds
  invariant : <boolean_expr>,   // multiple invariants allowed
  reasoning : <string>         // documentation for proof sketch
}

1. Make invariants checkable: Invariants must be valid MoonBit boolean expressions using loop variables and captured values.
2. Use boundary witnesses: For properties over ranges (e.g., "all elements in arr[0..i) satisfy P"), check only boundary elements. For sorted arrays,

   arr[i-1] < value

   implies all

   arr[0..i) < value

   .
3. Handle edge cases with

   ||

   : Use patterns like

   i == 0 || arr[i-1] < value

   to handle boundary conditions where the check would be out of bounds.
4. Cover three aspects in reasoning:
   • Preservation: Why each

     continue

     maintains the invariants
   • Termination: Why the loop eventually exits (e.g., a decreasing measure)
   • Correctness: Why the invariants at exit imply the desired postcondition