{"id":14705,"library":"miniprogram-build","title":"MiniProgram Build Tool","description":"miniprogram-build is a command-line interface (CLI) tool designed to streamline the development workflow for WeChat MiniPrograms. It handles common build tasks such as compiling TypeScript to JavaScript, SCSS/Sass/CSS to MiniProgram's WXSS, HTML/WXML to WXML, and JSON/JSONC to JSON, alongside image compression and file copying. The current stable version is 7.0.3, with frequent patch releases indicating active maintenance. Unlike a framework, it serves as an automation and enhancement tool for existing MiniProgram projects, emphasizing a build-and-watch approach. Its key differentiators include comprehensive support for modern web technologies (TypeScript, SCSS) within the MiniProgram ecosystem and direct integration with the WeChat Developer Tools for features like automatic preview and project upload.","status":"active","version":"7.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/NewFuture/miniprogram-build","tags":["javascript","MiniProgram","build","typescript","wechat","scss","tools","gulp","npm"],"install":[{"cmd":"npm install miniprogram-build","lang":"bash","label":"npm"},{"cmd":"yarn add miniprogram-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add miniprogram-build","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for TypeScript compilation features.","package":"typescript","optional":false},{"reason":"Peer dependency for TypeScript helper functions.","package":"tslib","optional":false}],"imports":[{"note":"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.","wrong":"const cli = require('miniprogram-build'); cli(process.argv.slice(2));","symbol":"miniprogram-build","correct":"import cli from 'miniprogram-build'; cli(process.argv.slice(2));"},{"note":"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.","wrong":"import { Build } from 'miniprogram-build';","symbol":"build","correct":"import { build } from 'miniprogram-build'; build({ src: 'src', dist: 'dist', production: true });"},{"note":"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.","wrong":"import { Dev } from 'miniprogram-build';","symbol":"dev","correct":"import { dev } from 'miniprogram-build'; dev({ src: 'src', dist: 'dist' });"}],"quickstart":{"code":"{\n  \"name\": \"my-miniprogram-project\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A simple WeChat MiniProgram project\",\n  \"scripts\": {\n    \"dev\": \"miniprogram-build dev\",\n    \"build\": \"miniprogram-build build --production\",\n    \"init\": \"miniprogram-build init\"\n  },\n  \"keywords\": [],\n  \"author\": \"\",\n  \"license\": \"ISC\",\n  \"devDependencies\": {\n    \"miniprogram-build\": \"^7.0.0\",\n    \"typescript\": \"^5.0.0\",\n    \"tslib\": \"^2.0.0\"\n  }\n}\n\n// To get started, first install as a dev dependency:\nnpm install miniprogram-build typescript tslib -D\n\n// Then, create a default configuration file:\nnpx miniprogram-build init\n\n// Or view all available commands:\nnpx miniprogram-build -h\n\n// To run in development mode (build and watch):\nnpm run dev\n\n// To build for production:\nnpm run build","lang":"typescript","description":"This quickstart demonstrates how to install, initialize, and run `miniprogram-build` for development and production builds within a MiniProgram project."},"warnings":[{"fix":"Ensure WeChat Developer Tools are installed (downloadable from official WeChat MiniProgram developer site) and enable 'Port Settings' in its preferences.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Before upgrading major versions, review the project's GitHub release notes and changelog for detailed migration guides. Test thoroughly in a staging environment.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: Command 'miniprogram-build' not found"},{"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.","cause":"The WeChat Developer Tools are either not running, or the 'Service Port' feature (required for CLI communication) is not enabled in its settings.","error":"Error: Failed to connect to WeChat DevTools. Please ensure DevTools is running and port settings are enabled."},{"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`.","cause":"The project uses TypeScript, but `miniprogram-build` cannot locate the `tsconfig.json` file to configure its TypeScript compilation.","error":"Error: Cannot find tsconfig.json in the current directory or its parents."}],"ecosystem":"npm"}