MiniProgram Build Tool

Common errors

• Error: Command 'miniprogram-build' not found

  cause The `miniprogram-build` command is not accessible in the current shell's PATH. This usually happens if it's installed locally but not run via `npx` or an npm script.
  fix If installed locally as a dev dependency, run commands using `npx miniprogram-build [command]` or define a script in `package.json` like `"dev": "miniprogram-build dev"` and then `npm run dev`.

• Error: Failed to connect to WeChat DevTools. Please ensure DevTools is running and port settings are enabled.

  cause The WeChat Developer Tools are either not running, or the 'Service Port' feature (required for CLI communication) is not enabled in its settings.
  fix Open your WeChat Developer Tools, navigate to 'Settings' -> 'Security Settings', and enable 'Service Port' (服务端口). Ensure the DevTools application remains open while using `autopreview` or `upload` commands.

• Error: Cannot find tsconfig.json in the current directory or its parents.

  cause The project uses TypeScript, but `miniprogram-build` cannot locate the `tsconfig.json` file to configure its TypeScript compilation.
  fix Create a `tsconfig.json` file in your project's root or specify its path using the `--tsconfig` option, e.g., `miniprogram-build build --tsconfig ./config/tsconfig.json`.

Warnings

• gotcha The automatic preview and upload functionalities require the WeChat Developer Tools to be installed and 'Port Settings' enabled within the IDE. Without this, `autopreview` and `upload` commands will fail.
  Fix: Ensure WeChat Developer Tools are installed (downloadable from official WeChat MiniProgram developer site) and enable 'Port Settings' in its preferences.
• gotcha The `--production` flag (or `NODE_ENV=production`) significantly alters the build output, often applying optimizations and compressions. Ensure you test your MiniProgram thoroughly in production mode before deployment, as subtle differences might arise.
  Fix: Always use `miniprogram-build build --production` (or `NODE_ENV=production npm run build`) for production builds and rigorously test the resulting MiniProgram package. Do not rely solely on development builds for deployment.
• breaking Upgrading to a new major version (e.g., from v6.x to v7.x) may introduce breaking changes to configuration options, CLI flags, or internal processing logic. Always consult the official Changelog (if available) or GitHub releases for specific migration steps.
  Fix: Before upgrading major versions, review the project's GitHub release notes and changelog for detailed migration guides. Test thoroughly in a staging environment.
• gotcha When defining custom variables using `--var.KEY=value`, ensure that the variables are correctly referenced in your source files (e.g., `{{__APP_ID__}}` in JavaScript/JSON). Incorrect syntax or missing definitions will lead to unresolved variables in the output.
  Fix: Double-check the variable naming and interpolation syntax in your source code against the `--var` CLI option. The example `miniprogram-build compile --var.APP_ID=1234567` implies `{{__APP_ID__}}` usage.

Install

• npm install miniprogram-build npm
• yarn add miniprogram-build yarn
• pnpm add miniprogram-build pnpm

Imports

• miniprogram-build
  wrong:

  const cli = require('miniprogram-build'); cli(process.argv.slice(2));

  correct:

  import cli from 'miniprogram-build'; cli(process.argv.slice(2));

  While primarily a CLI tool, for advanced programmatic execution (e.g., in CI/CD pipelines or custom scripts), its main entry point might be imported as a default export. Ensure your environment supports ESM.
• build
  wrong:

  import { Build } from 'miniprogram-build';

  correct:

  import { build } from 'miniprogram-build'; build({ src: 'src', dist: 'dist', production: true });

  This function is inferred as a potential programmatic API for triggering a build. The exact signature may vary or might not be officially exposed for public consumption. Always refer to source code or official types for precise usage.
• dev
  wrong:

  import { Dev } from 'miniprogram-build';

  correct:

  import { dev } from 'miniprogram-build'; dev({ src: 'src', dist: 'dist' });

  This function is inferred as a potential programmatic API for triggering development mode with watch capabilities. As with 'build', verify the exact API surface if attempting programmatic usage.

Quickstart

This quickstart demonstrates how to install, initialize, and run `miniprogram-build` for development and production builds within a MiniProgram project.

{
  "name": "my-miniprogram-project",
  "version": "1.0.0",
  "description": "A simple WeChat MiniProgram project",
  "scripts": {
    "dev": "miniprogram-build dev",
    "build": "miniprogram-build build --production",
    "init": "miniprogram-build init"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "miniprogram-build": "^7.0.0",
    "typescript": "^5.0.0",
    "tslib": "^2.0.0"
  }
}

// To get started, first install as a dev dependency:
npm install miniprogram-build typescript tslib -D

// Then, create a default configuration file:
npx miniprogram-build init

// Or view all available commands:
npx miniprogram-build -h

// To run in development mode (build and watch):
npm run dev

// To build for production:
npm run build