Run the MiniX H5 sample against a local API

Scope and baseline

This guide starts the existing H5 application rather than inventing a new host. The tested source is 1bef0cc6c453 ↗, using Node 22.23.2 and pnpm 10.6.1 on macOS arm64. The upstream package identifies itself as a v1.0.0 sample. Local sample authentication does not verify production identity providers.

WeChat DevTools, device behavior, provider credentials and production deployment were not tested. H5 success must not be read as a cross-platform certification.

Check out and install

git clone https://github.com/spcent/minix.git
cd minix
git checkout 1bef0cc6c453d827a80036ac121c7e02893bb29b
node --version
pnpm --version
pnpm install --frozen-lockfile

At this revision the last command fails with ERR_PNPM_OUTDATED_LOCKFILE: packages/tooling/package.json declares @minix/contracts, but its lockfile importer is empty. This is an upstream source/lock mismatch, not an H5 runtime error.

For this isolated learning checkout, run:

pnpm install --no-frozen-lockfile
git diff -- pnpm-lock.yaml
pnpm install --frozen-lockfile

The tested repair adds only this workspace dependency under packages/tooling; it does not update external dependency versions:

packages/tooling:
  dependencies:
    "@minix/contracts":
      specifier: workspace:*
      version: link:../contracts

Inspect the diff before proceeding. If it includes unrelated package updates, this guide's dependency baseline no longer matches. Do not apply a broad lockfile refresh to a production application based on this example. pnpm may report ignored optional dependency build scripts; the tested H5 build worked without enabling them globally.

Build and check types

pnpm build
pnpm typecheck

The H5 bundle is written to apps/host-h5/dist. A successful build alone does not prove that the host can communicate with its API.

Start the local API and H5 host

In the first terminal, from the checkout root:

MINIX_API_PORT=4300 MINIX_CORS_ALLOWED_ORIGINS=http://127.0.0.1:4273 pnpm dev:api

In a second terminal:

MINIX_API_BASE_URL=http://127.0.0.1:4300 pnpm preview 4273

These are POSIX shell commands. The API URL is embedded when preview builds the host; restart preview after changing it. Use the exact 127.0.0.1 origin in your browser, because localhost and 127.0.0.1 are different CORS origins.

Check the API:

curl http://127.0.0.1:4300/

Expected response:

{ "service": "minix-api", "status": "ok", "version": "1.0.0" }

Open http://127.0.0.1:4273/. The page title is Minute English. Choose Sign In To Continue, then Open Overview. The intended navigation continues to Today's Plan and Preferences, where the sample session can be ended. These operations use a local sample session, not a real WeChat login.

Troubleshooting and cleanup

If the page renders but login or data loading fails, check that the API is running and that the preview build uses port 4300. Inspect the browser network response; a CORS mismatch requires correcting the allowed origin, not disabling browser security. If either port is occupied, change the API URL, preview port and allowed origin together.

Stop both foreground processes with Ctrl+C. Clear site data for the local H5 origin to reset the browser session, or use a fresh browser profile. The temporary checkout contains the explicit workspace-lock repair; it need not be committed to upstream.

Follow the ownership path

Compare the host manifest and adapter with packages contracts and controllers. Continue to the [MiniX architecture review](/engineering/minix-multi-host-kernel-review) and [project entry](/projects/minix). The repository's WeChat hosts require their own DevTools and device checks; the local API and H5 exercise cover only one runtime.