WeChat gadget tool npm support

May 20, 2021 WeChat Mini Program Development Document

npm support

Starting with the base library version 2.2.1 or above, and developer tool 1.02.1808300 or above, the program supports the installation of third-party packages using npm.

This document requires developers to have some knowledge of npm, so the basic functionality of npm is no longer covered. If you have not previously been in contact with npm, please go through the official npm documentation to learn.

Use the npm package

To install the npm package by executing commands in a small program:

npm install --production

There is no mandatory requirement here node_modules the miniprogramRoot field must be in the small root (i.e. project.config.js ) or it can exist in each subdirection under the small root. However, node_modules is not allowed outside the root of the small program.

PS: Be sure to use the --production option here to reduce the size of the entire package by installing some business-independent npm packages.

Click on the menu bar in the developer's tool: Tools -- build npm
Check the "Use npm module" option:
Once the build is complete, you can use the npm package.

Introduce npm packages in js:

const package = require('packageName')
const packageOther = require('packageName/other')

Use custom components in the npm package:

{
  "usingComponents": {
    "package": "packageName",
    "package-other": "packageName/other"
  }
}

PS: If only the package name is introduced when using the npm package here, the index file or index component under the .js the package name is found by default.

Publish the npm package

Publish the constraints of the small program npm package

The npm package to be released here is specifically an npm package (here referred to as a small program npm package) tailored to a small program. Because of the particularity of the small program custom components, the original npm package mechanism can not meet our needs, so here you need to do some constraints on the small program npm package:

The small program npm package requires that there must be a build file generation directory (the default is the miniprogram_dist directory) under the root, which can be specified by adding a miniprogram field to the package.json file, such as:

{
  "name": "miniprogram-custom-component",
  "version": "1.0.0",
  "description": "",
  "miniprogram": "dist",
  "devDependencies": {},
  "dependencies": {}
}

Only the build file generation directory in the small program npm package is counted as the footprint of the small package, and only the code for the small program code is uploaded when it is uploaded. I f the small program npm package has some testing, build-related code, put it outside the build file generation directory. You can also use the .npmignore file to avoid publishing some non-business code files to npm.
Test, build related dependencies by putting them in the devDependencies field to avoid being packaged together into small packages.

Publish constraints for other npm packages

If you've already published some npm packages, you can also use them by fine-tuning them if you can't change the structure of the small program npm package for some reason, but make sure you follow these:

Only pure js packages are supported, and custom components are not supported.
There must be an entry file, i.e. you need to ensure that the main field in package.json points to the correct portal, and if there is no main field in package.json, the index.js under the npm package root is used as the portal file.
Test, build related dependencies in the devDependencies field to avoid being packaged together into small packages, as required by small program npm packages.
Built-in libraries that rely on nodejs are not supported:

const addon = require('./addon.node'); // 不支持！
const http = require('http'); // 不支持！

The following methods are not allowed when using require dependency:

// 不允许将 require 赋值给其他变量后再使用，以下代码不会去解析出具体依赖
let r;
r = require;
r('testa');

let r2 = require;
r2('testa');

// 不允许 require 一个变量，以下代码依赖运行时，无法解析出具体依赖
let m = 'testa';
require(m);

Small program environments are special, and some global variables, such as window objects, and constructors, such as Function constructors, are not available.

The publishing process

The process for publishing the npm package is as follows:

If you don't have an npm account yet, you can sign up for an npm account on the npm website.
Sign in to your npm account locally and do it locally:

npm adduser

npm login

Executed at the npm package root directory that has been written:

npm publish

At this end, the npm package was successfully released to the npm platform.

PS: Some developers may have modified the npm source during development, so be careful to cut the source back to the npm source when you log in or publish.

Introduction to the principle

To help you better understand the requirements mentioned in the release npm package, here's a quick look at the principles:

First of all, the node_modules directory will not participate in compilation, upload, and packaging, so the small program wants to use the npm package must go through the "build npm" process, in the outermost layer of the node_modules under the peer directory will generate a miniprogram_npm directory, which will hold the built package npm package, that is, the small program really use the npm package.
There are two types of build packages: the small program npm package copies all the files in the build file generation directory directly into miniprogram_npm, and the other npm packages go through the dependency analysis and packaging process (like webpack) starting with the portal js file.
The process of finding an npm package is similar to the implementation of npm, starting with the directory where the files that depend on the npm package start looking out layer by layer until you find an available npm package or a small root. Here's a brief introduction to building the catalog before and after packaging, and building the previous structure:

|--node_modules
|    |--testComp // 小程序 npm 包
|    |    |--package.json
|    |    |--src
|    |    |--miniprogram_dist
|    |         |-index.js
|    |         |-index.json
|    |         |-index.wxss
|    |         |-index.wxml
|    |--testa // 其他 npm 包
|         |--package.json
|         |--lib
|         |    |--entry.js
|         |--node_modules
|              |--testb
|                   |--package.json
|                   |--main.js
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js

Structure after construction:

|--node_modules
|--miniprogram_npm
|    |--testComp // 小程序 npm 包
|    |    |-index.js
|    |    |-index.json
|    |    |-index.wxss
|    |    |-index.wxml
|    |--testa // 其他 npm 包
|         |--index.js // 打包后的文件
|         |--miniprogram_npm
|              |--testb
|                   |--index.js // 打包后的文件
|                   |--index.js.map
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js

PS: Packaged generated code generates a source map file in the same directory for reverse debugging.

Example of a js module

The following are official js modules that can be referenced and used:

sm-crypto

Examples of custom components

Please refer to the documentation for developing third-party custom components.