WeChat Mini Program Bundler

Common errors

• Error: Cannot find module 'weapp-minipack'

  cause The package was not installed or installed incorrectly, or there's a CommonJS/ESM import mismatch.
  fix Ensure `weapp-minipack` is installed locally (`npm install weapp-minipack` or `yarn add weapp-minipack`) if using programmatic API, or globally (`npm install -g weapp-minipack`) for CLI. Verify `import` vs `require` usage matches your project type.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ECMAScript module context (.mjs file or `"type": "module"` in `package.json`).
  fix Refactor your imports to use `import { Entry } from 'weapp-minipack';` and `import path from 'path';`. If you need to read JSON or CJS modules, consider dynamic `import()` or `createRequire`.

• Error: configPath is required or config options must be provided directly.

  cause When creating a new `Entry` instance, neither a `configPath` pointing to a config file nor a direct `config` object was provided.
  fix Provide a `configPath` option like `{ configPath: path.resolve(__dirname, 'minipack.config.js') }` or pass the configuration object directly as `{ config: { /* your config here */ } }` to the `Entry` constructor.

Warnings

• gotcha The package is currently in version `0.1.x`. This indicates an early stage of development where the API might not be stable, and breaking changes could occur in minor or even patch releases.
  Fix: Always pin to exact versions (e.g., `"weapp-minipack": "0.1.20"`) and thoroughly review release notes before updating to avoid unexpected breakages.
• gotcha Configuration for `weapp-minipack` is primarily done via a separate JavaScript file (e.g., `minipack.config.js`) or passed directly as an object to the `Entry` constructor. It does not integrate with `package.json` for configuration.
  Fix: Ensure your configuration file path is correct when using the CLI (`weapp-minipack -c ./config.js`) or that the config object is correctly structured when using the programmatic API.
• gotcha While the library ships TypeScript types, its examples in the README predominantly use CommonJS `require` syntax. If integrating into a pure ESM project, you might encounter issues unless your build setup correctly handles CJS interop.
  Fix: For ESM projects, use `import` statements as shown in the `imports` section. For CJS projects, stick to `require`. Ensure your `tsconfig.json` `module` and `moduleResolution` are set appropriately (e.g., `"module": "NodeNext", "moduleResolution": "NodeNext"`).

Install

• npm install weapp-minipack npm
• yarn add weapp-minipack yarn
• pnpm add weapp-minipack pnpm

Imports

• Entry
  wrong:

  const { Entry } = require('weapp-minipack');

  correct:

  import { Entry } from 'weapp-minipack';

  The documentation primarily uses CommonJS `require`, but the library ships TypeScript types, implying ESM usage is expected in modern projects. Ensure your project is configured for ESM or use `require` for CJS.
• minifierStyle
  wrong:

  const { minifierStyle } = require('weapp_minipack');

  correct:

  import { minifierStyle } from 'weapp-minipack';

  The README incorrectly shows `require('weapp_minipack')` for the plugin; the correct import should be from the main `weapp-minipack` package.
• CLI usage

  weapp-minipack -c ./minipack.config.js

  The primary CLI usage involves globally installing the package and pointing to a configuration file. There's no direct import for the CLI itself.

Quickstart

Demonstrates programmatic usage to initialize and run the bundler with a custom configuration, including a basic plugin for WXSS processing.

import { Entry } from 'weapp-minipack';
import path from 'path';

// Define your minipack configuration
const minipackConfig = {
  watchEntry: path.resolve(__dirname, 'src'), // Source directory for mini-program files
  tsConfigPath: path.resolve(__dirname, 'tsconfig.json'), // Path to your TypeScript config
  outDir: path.resolve(__dirname, 'build'), // Output directory for compiled files
  isWatch: false, // Set to true to enable watch mode for development
  miniprogramProjectPath: path.resolve(__dirname, 'project.config.json'),
  plugins: [
    {
      test: /.*\.(wxss)$/,
      action: ({ data }) => {
        // Example: simple CSS minification or just passing through
        return data.replace(/\s+/g, ' ').trim();
      },
    },
  ],
};

// Create an instance of Entry with your configuration
// For a production build, ensure isWatch is false.
const bundler = new Entry({ 
  config: minipackConfig 
});

// Initialize and start the bundling process
bundler.init().start()
  .then(() => console.log('Mini-program build successful!'))
  .catch(error => console.error('Mini-program build failed:', error));