How to Slash Mini Program Package Size with Smart Sub‑Package Strategies

Why Use Subpackages?

The core idea of Mini Program subpackaging is simple: split a complete Mini Program project into a main package and multiple sub‑packages, thereby breaking the single‑package size restriction and improving loading performance.

During startup, only the core main package and Tab pages are downloaded; when a user accesses a specific feature module, the corresponding sub‑package is loaded dynamically, similar to on‑demand streaming services.

WeChat also offers an "independent subpackage" feature, which runs completely separate from the main package and starts even faster—ideal for isolated pages such as activity or tool modules.

Official Size Limits

The total size of all sub‑packages must not exceed 30 MB (20 MB for service‑provider‑developed Mini Programs).

Each individual sub‑package or the main package cannot exceed 2 MB.

Common Reasons the Main Package Bloats

UI component library imports : Even a few components can add hundreds of kilobytes to the bundle.

Improper static‑resource management : Large images or fonts placed directly in the project increase size, and high‑resolution images easily exceed the 200 KB single‑file limit.

npm dependency "spillover" : Third‑party packages installed via npm are ultimately bundled into the main package, regardless of which sub‑package uses them.

Business code growth : As features iterate, page and component code naturally increase, becoming the primary source of size growth.

Pre‑Slimming Strategies Before Subpackaging

Trim UI component imports : Review index.json and remove unused components; import only what is needed.

Move static resources to the cloud : Upload images, audio, etc., to a CDN to reduce bundle size and improve load speed. If local storage is required, compress assets first.

Extract common logic : Pull shared business logic into custom components or Behaviors to avoid duplicate code.

Trim third‑party packages : For large npm libraries used only partially, consider implementing the needed utilities yourself.

If the main package still exceeds 2 MB (or approaches the 1.5 MB warning line), it’s time to adopt subpackaging.

Subpackage Configuration

Add the subPackages field in app.json to declare subpackage structures:

{
  "pages": ["pages/index", "pages/logs"],
  "subPackages": [
    {
      "root": "packageA",
      "pages": ["pages/cat", "pages/dog"],
      "entry": "index.js"
    },
    {
      "root": "packageB",
      "name": "pack2",
      "pages": ["pages/apple", "pages/banana"]
    }
  ]
}

Basic Rules

Packaging scope : Only directories listed under subPackages are split; everything else stays in the main package.

Main‑package pages : Defined in the top‑level pages field of app.json.

Directory hierarchy : Subpackage root directories cannot be nested (e.g., packageA cannot reside inside packageB).

TabBar limitation : Pages referenced in the bottom navigation bar must reside in the main package.

Reference Restrictions Between Subpackages

JS file reference : Subpackage A cannot directly import JS files from subpackage B; it can only import files from the main package or its own directory. Asynchronous subpackage loading can work around this.

Template reference : Subpackage A cannot use template files from subpackage B.

Static resource reference : Subpackage A cannot use images or other static assets from subpackage B.

In short, subpackages are isolated; they may depend upward on the main package but not laterally on each other.

Practical Subpackage Process

In a real case the main package reached 2.32 MB, containing third‑party UI components, business code, custom components, and static assets.

Static resource migration : Move images and other assets to a CDN.

Functional module subpackaging : Split code by business function into separate subpackages.

Component sinking : Relocate non‑shared custom components and JS logic into their respective subpackages.

After these steps the main package shrank to 1.18 MB, leaving ample space for future feature expansion. New business features can now be added to their dedicated subpackages without inflating the main bundle.

Developer tools confirmed that the size warning disappeared and the Mini Program passed the upload check.

Limitations and Considerations

Size limit remains tight : The 2 MB single‑package cap can still be restrictive for complex projects, especially when subpackages themselves approach the limit, potentially requiring a second level of splitting.

npm dependencies concentrate in the main package : Regardless of which subpackage uses a UI library, npm‑installed dependencies are bundled into the main package. In the example, 856 KB of the 1.18 MB main bundle came from a UI component library.

Plugin restrictions : Certain WeChat plugins (e.g., live‑streaming) must reside in the main package and cannot be subpackaged, adding up to about 1 MB of space pressure.

Common code placement : Shared components and utilities must stay in the main package so all subpackages can access them; otherwise, code‑quality warnings appear.

Suggested Practices

Plan subpackage strategy early in the project to avoid heavy refactoring later; keep coupling low.

Choose lightweight third‑party libraries whenever possible.

When sharing logic, consider implementing a version inside a subpackage if it reduces main‑package size without sacrificing reuse.

Periodically audit and remove unnecessary dependencies and dead code.

Overall, subpackaging is an effective solution for Mini Program bundle‑size problems. While it introduces some constraints, a well‑planned subpackage architecture can support long‑term project growth and maintain a smooth user experience.