Documentation / Getting Started

Getting Started with moth

moth compiles and tools Moth projects. You use it from the command-line to create new projects, check them, build them and run the hot-reloading dev server.

Other tooling continues rapid development.

If you are running the compiler from the repository instead of an installed moth binary, use cargo run -- before the same commands:

    cargo run -- dev .
    cargo run -- check .
    cargo run -- build .
    

Commands

Current flags

Create a new HTML project

The scaffold creates a default project with config, a starter page, generated output folders, build manifests and an optional .gitignore. The HTML project builder itself has more rules than this page needs to cover. See the project structure guide for page layout, routing, assets, fragments and generated output details.

Start a new project:

    moth new html
    moth new html my-site
    moth new html ~/projects/my-site
    

If you omit the path, moth asks for confirmation in the current directory:

            No project path specified. Current directory: /your/path
            Create the new HTML project in this directory? y/N:
        

If the target directory already exists, you are given three choices:

            Target directory already exists:
            /path/to/target

            What do you want to do?
              1. Create the project inside this directory
              2. Create a new child folder for the project inside this directory
              3. Cancel

            Choose 1/2/3:
        

If the path contains directories that do not exist, moth asks before creating them:

    The project target contains directories that do not exist:
    /path/to/new/site

    Create the missing directories and scaffold the project there? y/N:
    

After the final directory is chosen, moth asks for the project name:

    Project name (press Enter to use project directory name):
    

Then it asks whether to add a .gitignore with Moth defaults:

    Add a .gitignore with Moth defaults? Y/n:
    

If .gitignore already exists, moth asks whether to append missing defaults instead of overwriting.

Generated project structure

A scaffolded project looks like this:

            project-root/
            ├── config.moth
            ├── src/
            │   └── @page.moth
            ├── lib/
            ├── dev/
            │   └── .moth_manifest
            ├── release/
            │   └── .moth_manifest
            └── .gitignore
        

• dev/ and release/ are output folders.
• .moth_manifest files are build-system metadata for safe stale-output cleanup.
• src/@page.moth is the conventional module root with a starter page. The filename is cosmetic.
• The current scaffold creates an empty legacy lib/ placeholder. It has no special package meaning. Use structural +*.moth packages under the source tree for project-local packages.

Using --force

--force allows replacing scaffold-owned files when they already exist:

    moth new html my-site --force
    

It still asks for a second confirmation and never overwrites .gitignore or unrelated files.

After creation, check and run the project:

    cd my-site
    moth check .
    moth dev .
    

Run the dev server

dev handles normal day-to-day Moth project work. It builds the project, serves the generated files locally, watches for source changes and sends reload events to the browser.

    moth dev .
    

By default, open:

            http://127.0.0.1:6342/
        

Useful dev-server options:

    moth dev . --port 8080
    moth dev . --host 0.0.0.0
    moth dev . --poll-interval-ms 100
    

When a build fails, fix the reported error and save again. The dev server is designed around fast feedback rather than a manual rebuild loop.

Build a project

Use build when you want files written to disk without running the dev server.

    moth build .
    

For a release build:

    moth build . --release
    

For HTML projects, generated files are written under the configured output folder. The default scaffold currently uses dev for development output and release for release output.

Check without building

check gives the fastest correctness signal for editor loops and CI-style validation. It doesn't write output artifacts, but it runs the shared frontend diagnostics that all backends use.

    moth check .
    

Use terse mode when another tool will read the output:

    moth check . --terse
    

Terse diagnostics have a stable compact shape:

            E|type|src/@page.moth|4:12|Expected Bool, found Int|help=Use a Bool expression here.
            W|identifier_naming_convention|src/button.moth|1:1|Import alias case mismatch
        

Reading compiler errors

Moth uses the same formatted diagnostic system across the compiler front end and backend builders. That means syntax errors, type errors, config errors, file errors, borrow-checker errors, dev-server errors and backend errors use the same basic shape.

A normal diagnostic contains:

• the error kind
• the main message
• the source file path, line, and column
• the source line when available
• a caret underline for the offending span
• guidance lines when the compiler has a useful suggestion

Example shape:

            Type Error (ಠ_ಠ) 🔥
            Declaration 'count' has incompatible initializer type. Expected 'Int', but found 'String'.

              --> src/@page.moth:6:17
                |
              6 | count Int = "wrong"
                |             ^^^^^^^
              Use an Int value here, or change the declaration type.
        

Read diagnostics from top to bottom:

1. The kind tells you which part of the compiler rejected the program.
2. The message tells you the actual rule that failed.
3. The file/line/column points to the primary source location.
4. The caret shows the token or expression the compiler is complaining about.
5. The guidance lines are suggestions, not a separate error.

Error kinds

Warnings and future suggestions

Warnings are for code that can still compile but deserves attention. Current warnings include things like malformed CSS/HTML template content, large tracked assets, naming convention issues and import alias case mismatches.

Moth separates correctness from style pressure. The future suggest command will become the pedantic style and cleanup pass: closer to a full Clippy-style assistant for Moth code. Noisy suggestions such as unused variables, unused imports, unused declarations and more specific style improvements belong there.

The intended workflow will be:

    moth check .
    moth suggest .
    moth fmt .
    

For now, use check and the compiler's normal warnings as the practical baseline.

Planned moth extensions

moth will become the main Moth project tool, not a thin compiler launcher. Planned additions include:

• a package manager for Moth packages and project dependencies
• a formatter for stable project-wide formatting
• suggest, a pedantic style and cleanup command to use alongside check
• richer new project options, including more complete config templates
• stronger project maintenance commands as the build system matures

The short-term rule is simple: dev for fast browser feedback, check for correctness and build when you want output files.