# MiniApp quickstart

Create your own two-page application, run it in WeChat Developer Tools, then
make a small source edit. You do not need to understand Minimoon's renderer or
release process first. [Back to README](../../README.md).

## Prerequisites

- MoonBit: `moon 0.1.20260920` with `moonc v0.10.14` or newer.
  Upgrade older installations before using core `0.2.5` or UI `0.1.3`.
- Global `vp 1.0.0`, managing Node `26.10.0` and Bun `1.4.2`.
  A separate Node or Bun installation is unnecessary; the supported Node range
  remains `>=24.20.0`.
- A writable development directory with enough free space, and WeChat
  Developer Tools with Skyline support.
- Git is needed only for the optional [source workflow](#create-from-the-current-source).
- A suitable WeChat MiniApp account/AppID for host preview. Automated CLI
  checks do not establish account or device-preview eligibility.

Install the pinned global CLI on macOS/Linux:

```bash
curl -fsSL https://vite.plus | VP_VERSION=1.0.0 bash
```

On Windows PowerShell, set `$env:VP_VERSION = "1.0.0"`, then run
`irm https://vite.plus/ps1 | iex`. See the
[official installer guide](https://viteplus.dev/guide/).
Open a new terminal, initialize its managed environment, and check the tools:

```bash
vp env setup
vp env on
vp env install node@26.10.0 bun@1.4.2
moon version --all
vp --version
vp env exec --node 26.10.0 --package-manager bun@1.4.2 node --version
```

`vp env on` enables managed Node/package-manager shims. Keep their directory on
PATH, as configured by the installer. The repository and new apps declare
`devEngines.runtime` Node `26.10.0` and `devEngines.packageManager` Bun `1.4.2`;
inside either directory, `vp node --version` should report `v26.10.0` and
`vp env current` shows both selected versions. No `.node-version` is needed.
CI explicitly checks Node `24.20.0` as well as `26.10.0`.

CI uses the official MoonBit installer pinned to reviewed prebuilt release
`0.10.14+7d59c7ec9` (`moon 0.1.20260920`); no Rust is required. Keep the
dependency versions and PostCSS override generated by `minimoon init`.
`vp install` selects Bun internally and retains `bun.lock`.

The global `vp` CLI is required by Minimoon `0.2.5` build/verification tools.
No local `vite-plus`, Vite or Vitest dependency is needed. A message that local
`vite-plus` is not installed is expected for this MoonBit project. Use
`vp run <task>` for repository scripts; `vp build`, `vp test` and `vp check`
are Vite+ built-ins, not Minimoon task aliases. Acceptance gates use
`vp run --no-cache <task>` so cached task results cannot replace verification.
If the CLI reports missing `vp`, reopen the terminal with its installer PATH.
If Bun management is disabled, run `vp env on bun`, then retry; the CLI requires
the managed Bun backend for reproducible process execution.

<a id="registry-installation-after-publication"></a>

## Registry installation

This source documents core `0.2.5` with optional UI `0.1.3`. The commands pin
the CLI to this version and create an independent app. First confirm registry
availability in [project status](https://github.com/lucavance/minimoon/blob/main/docs/project_status.md).
Before publication, use the [source workflow](#create-from-the-current-source).

Start in your chosen development directory, outside every existing Moon
workspace. `my-app/` must be new or empty:

<!-- minimoon:onboarding:start -->
```bash
moon install lampclaw/minimoon/cmd/minimoon@0.2.5
minimoon --version
minimoon init my-app
cd my-app
moon update
vp install
minimoon build .
minimoon verify . --candidate
```
<!-- minimoon:onboarding:end -->

After candidate verification passes, open WeChat Developer Tools and import
**`my-app/dist/`**. Configure the [host settings](#open-in-wechat-developer-tools)
before running the MiniApp.

If `minimoon` is not found after installation, open a terminal with MoonBit's
bin directory on PATH. Inspect `minimoon --version` to confirm the installed
release and check PATH if it resolves to a different CLI installation.

The CLI includes the Starter files and writes a core dependency in `moon.mod`
using its product version. Mooncakes resolves that dependency; no framework
checkout or generated `moon.work` is needed. Do not pass `--minimoon-root` in
registry mode. `vp install` installs the app's style build tools.

The starter uses only `lampclaw/minimoon`, with Home and Details pages.
It does not enable application-owned shared state or the optional UI module.
Source configuration is `miniapp.minimoon.json`, using App Contract v11.

The `0.2.5` CLI uses `vp` for all JavaScript tool launches, with managed Bun
`1.4.2` internally and Node for the stylesheet adapter. It retains the App-aware
helper fix and explicit package-qualified API calls needed by the new compiler. Enabling `application` no longer requires
a separate source-only compatibility fix with that CLI. Existing applications
must upgrade both the CLI and their module dependencies; see
[toolchain compatibility](../reference/compatibility_and_upgrades.md#toolchain-compatibility).

### Install a specific version

The onboarding command pins `0.2.5` so the CLI and generated dependency agree.
After its publication is recorded, install it with:

```bash
moon install lampclaw/minimoon/cmd/minimoon@0.2.5
```

Confirm `minimoon --version` prints `0.2.5`, then follow the initialization and
build steps above. Omitting `@version` selects the latest registry version,
which may differ from this guide. Check
[project status](https://github.com/lucavance/minimoon/blob/main/docs/project_status.md)
for unpublished changes and use the [source workflow](#create-from-the-current-source)
when those are needed.
Adding UI is optional; declare its matching published dependency as described
in the [UI guide](https://github.com/lucavance/minimoon/blob/main/ui/README.md).

## Open in WeChat Developer Tools

From `my-app/`, the candidate verification above creates release-mode files.
Import **`my-app/dist/`** unchanged, not `my-app/` or the framework repository.

Check the Developer Tools settings:

- Skyline renderer.
- ES6-to-ES5 transformation, enhanced compilation and minification enabled:
  `setting.es6=true`, `setting.enhance=true`, `setting.minified=true`.
- Online minimum base library **3.17.0** or newer.

For your AppID, copy `dist/project.private.config.example.json` to
`dist/project.private.config.json` **only if the private file does not already
exist**, then edit that private copy. Never overwrite existing local settings
or commit the AppID/private file. Rebuilds preserve it and exclude it from
artifact fingerprints. Do not change generated public files to store secrets.

On a cold launch, expect:

1. **Hello Minimoon**, counter **0**, a name input and **Open details**.
2. Tap **+1**; the counter becomes **1**.
3. Type a name; the greeting updates. Open Details, then return to Home.

Require a clean console. If the host cannot open the project, first check the
import directory, tool settings and your account/AppID. For parser errors or
blank screens, use the [host troubleshooting guide](../operations/miniapp_javascript_compatibility.md).

## Make your first change

Edit **your app's** `src/pages/home/page.mbt`, not the framework template.
Find this initial model inside `program()`:

<!-- minimoon:first-edit:start -->
```moonbit
{ count: 0, name: "Minimoon", visits: 0, }
```

Change only its initial name:

```moonbit
{ count: 0, name: "My App", visits: 0, }
```
<!-- minimoon:first-edit:end -->

From `my-app/`, rebuild and verify:

```bash
minimoon build .
minimoon verify . --candidate
moon test --target js
```

Cold-restart the MiniApp, rather than retaining the old page instance.
The title should now be **Hello My App**; count and navigation still work.
The existing tests remain valid because they set their own input name.

Maintain `src/`, `miniapp.minimoon.json` and `styles/tailwind.css`.
Treat `dist/`, `generated/` and `styles/app.wxss` as generated output.

## Continue developing

From the app directory, `minimoon dev .` watches source changes and rebuilds;
keep using Developer Tools for the preview. It does not start a browser server.
Stop the watcher before a separate manual build.

With the `0.2.5` CLI, an ordinary build failure keeps the previous `dist/` and
private project settings; inspect the current diagnostics before retrying.
A verification failure after a successful build keeps the new output for diagnosis.
For existing applications, upgrade [both the CLI and core dependency](../reference/compatibility_and_upgrades.md#upgrade-procedure).

```bash
minimoon add page activity_log --after home --title "Activity Log"
minimoon add component status_badge --page home
```

The [authoring guide](miniapp_authoring_example.md) explains ordinary page
builders and typed state. Use [typed HTTP](http.md), [native navigation](native_navigation.md),
[shared state](shared_state.md) and the
[UI guide](https://github.com/lucavance/minimoon/blob/main/ui/README.md) as needed.
No-App factories export `program() -> Page`; opting into `application`
changes them to `program(deps : @application.Deps) -> Page`.

Required route parameters use `page_with_input`. Its builder receives plain
input decoded before graph creation; previews are separate. Add explicit
`smokeInput` to required-input configuration entries, for example
`{ "package": "src/pages/details", "smokeInput": { "from": "smoke" } }`.
This is only synthetic input for automated verification, not a navigation
default. See [input and lifecycle](api_ergonomics.md#page-input-and-first-render).

## Create from the current source

Use this alternative to develop the framework or use the candidate before it
is available in Mooncakes. Use the same MoonBit minimum and pinned JavaScript
dependencies as the registry workflow. See
[project status](https://github.com/lucavance/minimoon/blob/main/docs/project_status.md).

With Git installed, start outside every existing Moon workspace. These
commands create sibling `minimoon/` and `my-app/` directories:

```bash
git clone https://github.com/lucavance/minimoon.git minimoon
cd minimoon
vp install --frozen-lockfile
moon update
moon install --path src/cmd/minimoon
minimoon --version
minimoon init ../my-app --minimoon-root "$PWD"
cd ../my-app
vp install
minimoon build .
minimoon verify . --candidate
```

If you already cloned the repository, start at `cd minimoon` from its parent.
`my-app/` must be new or empty. Ensure `minimoon` resolves to the locally
installed CLI; the source and registry CLI can share a product version while
containing different changes.

The generated `moon.work` binds your app to the framework checkout. Keep both
directories while developing in source mode. Removing that workspace switches
dependency resolution to published packages, which can lack source changes.
The Developer Tools and first-edit steps are the same as above. This Starter
still uses only core; UI requires a separate published dependency or an
explicit local workspace member.

## Automated checks and real-host acceptance

`minimoon verify . --candidate` performs automated checks. It does not operate
Developer Tools, test a physical device, or prove production request-domain
eligibility. Keep actual simulator preview, physical-device preview and device
debugging outcomes separate.

Formal release acceptance follows the [host checklist](../operations/miniapp_devtools_validation.md).
Only after the exact release passes should you use `minimoon devtools record`
and `minimoon verify . --release`. Evidence stays local and Git-ignored; never
copy another application's record. These release steps are not required to
make your first edit. The framework fixtures' validation does not mark your
application as host-validated and does not change `verify --release`.

The framework's [Draft Workbench](https://github.com/lucavance/minimoon/blob/main/examples/miniapp_draft_workbench/README.md)
has nine routes and four native Tabs; the independent
[UI Showcase](https://github.com/lucavance/minimoon/blob/main/ui/examples/showcase/README.md)
has six pages. They demonstrate and verify framework capabilities, not the
recommended starting contents for a business application.