# Support for npm

Installation of third-party packages using npm is supported in the Mini Program as of base library 2.2.1 and Weixin DevTools 1.02.1808300.

This documentation assumes that the developers have a good knowledge of npm, and will not cover the basic features of npm. If you are not familiar with it, please read npm official documentation.

# Using npm Package

1. Execute the following command in the Mini Program to install an npm package:

npm install

The node_modules is not necessarily located in the root directory of the Mini Program (i.e. the miniprogramRoot field in project.config.js). It can also be stored in a subdirectory under the root directory. However, residing outside the root directory is not allowed.

Notes: As of Weixin DevTools v1.02.1811150, npm packages are built based on the dependencies field of package.json, so the packages declared in devDependencies can also be installed and used during development, without getting involved in the building. For earlier versions, it is recommended to use the --production option to reduce the size of the Mini Program package by reducing the number of business-independent npm packages installed.

2. Click the menu bar in Weixin DevTools, and go to Tools > Build npm
   

3. Check the Use npm module option:
   

4. The npm package can be used once built.

Introduce the npm package in js:

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

Use the custom components in the npm package:

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

Notes: If only the package name is introduced when using an npm package, the index.js file or the index component under the package name is retrieved by default.

# Releasing npm package

# Limits on the release of the Mini Program npm package

The npm package to be released here refers to the npm package specially designed for the Mini Program (hereinafter referred to as the Mini Program npm package). Due to the particularity of the custom components in the Mini Program, the original npm package mechanism cannot meet our requirements, so the Mini Program npm package is subject to the following limits:

1. For Mini Program npm packages, a build file generation directory must exist in the root directory (miniprogram_dist by default). This directory can be specified by adding a miniprogram field in the package.json file, for example:

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

2. Only the build file generation directory in the Mini Program npm package is counted in the occupied space of the Mini Program package, and only the codes in this directory are uploaded with the Mini Program code. The test- and build-related codes in the package (if any) should not be put in the build file generation directory. You can also avoid releasing the business-independent code files into npm by using the .npmignore file.
3. Put the test- and build-related dependencies in the devDependencies field to avoid packaging them into the Mini Program package.

# Limits on the release of other npm packages

If some of the npm packages that have been released cannot be transformed into Mini Program npm packages for some reasons, they can still be used via fine-tuning. However, be sure to follow these guidelines:

1. Only pure js packages are supported, while custom components are not supported.
2. An entry file is required to make sure the main field in package.json points to a correct entry. If there is no main field in package.json, the index.js in the root directory of the npm package is used as the entry file.
3. Similar to the Mini Program npm package, the test- and build-related dependencies should be put in the devDependencies field to avoid packaging them into the Mini Program package.
4. The c++ addon dependency is not support, neither are the built-in libraries of the nodejs dependency:

const addon = require('./addon.node'); // Not supported.
const http = require('http'); // Not supported.

Notes: For the Node.js built-in modules (such as the path module) implemented using pure js, support can be added by installing the npm packages implemented by other developers.

5. Note the following when using the require dependency:

// Do not use require after assigning it to other variables because the dependency cannot be parsed by the following codes
let r;
r = require;
r('testa');

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

// Do not use the require variable alone because the dependency cannot be parsed when the following code dependencies are running
let m = 'testa';
require(m);

6. Certain global variables (such as the window object) and constructors (such as the Function constructor) are not available in the Mini Program due to specific runtime environment.

# Release process

The process of releasing npm packages is described below:

1. If you don't have an npm account, register one on the npm official website.
2. Log in to the npm account locally and execute the following command locally:

npm adduser

Or

npm login

3. Execute following command under the root directory of a compiled npm package:

npm publish

The npm package is released to the npm platform now.

Notes: Some developers may have modified the source of the npm during development, so use the original source for login or release.

# Principles

Here are some principles to help you better understand the requirements for the release of the npm packages:

1. The node_modules directory is not used in the processes of compiling, uploading and packaging, so the Mini Program needs to build the npm first to use the npm package. A miniprogram_npm directory will be generated in the same level directory as the outermost node_modules, which stores the built npm package, the one actually used by the Mini Program.
2. Building and packaging are performed in the following way: the Mini Program npm package copies all the files in the build file generation directory directly into miniprogram_npm, while other npm packages perform dependency analysis and packaging from the js entry file (similar to webpack).
3. Similar to npm implementation, the search for an npm package starts from the directory where the files that depend on the npm package are located and goes layer by layer from inside out, until the available npm package or the Mini Program root directory is found. The directory before and after the build and package is shown below. Structure before the build:

|--node_modules
|    |--testComp // Mini Program npm package
|    |    |--package.json
|    |    |--src
|    |    |--miniprogram_dist
|    |         |-index.js
|    |         |-index.json
|    |         |-index.wxss
|    |         |-index.wxml
|    |--testa // Other npm packages
|         |--package.json
|         |--lib
|         |    |--entry.js
|         |--node_modules
|              |--testb
|                   |--package.json
|                   |--main.js
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js

Structure after the build:

|--node_modules
|--miniprogram_npm
|    |--testComp // Mini Program npm package
|    |    |-index.js
|    |    |-index.json
|    |    |-index.wxss
|    |    |-index.wxml
|    |--testa // Other npm packages
|         |--index.js // Packaged file
|         |--miniprogram_npm
|              |--testb
|                   |--index.js // Packaged file
|                   |--index.js.map
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js

Notes: The code generated from packaging will generate a source map file in the same level directory for reverse debugging.

# Example of js Module

Here is an official js module for reference and use:

• sm-crypto

# Examples of Custom Components

See Developing Third-party Custom Component.