uni_modules.config.json

Expand All

# uni_modules

# What is uni_modules

uni_modules is the plug-in modular specification of uni-app (supported by HBuilderRX 3.1.0+), which is usually the encapsulation of a group of js sdk, components, pages, uniCloud cloud functions, public modules, etc. It is used for embedding in uni-app projects, and also supports direct encapsulation as project templates.

Plug-in developers can write a uni_modules plug-in just like developing a uni-app project, and upload it directly to the plug-in market (opens new window) in HBuilderX.

Plug-in users can find the uni_modules plugin that meets their needs in Plugin Market (opens new window), and use HBuilderX 3.1.0+ to directly import it into their uni-app project. You can also directly right-click in HBuilderX to upgrade the plug-in later.

Compared with ordinary plug-ins, the uni_modules plug-in has stronger independence and independent directory structure, and can be released, updated and uninstalled more conveniently (HBuilderX 3.1.0+ provides a right-click menu for the uni_modules plug-in, and supports publishing, updating, installation dependency, etc.)

Compared with node_modules (node.js module), the third party dependency of uni_modules defaults to the latest version during installation. Plug-ins are directly installed in the uni_modules directory without nesting. Of course, if developers want to fix a version of dependencies, they can include the third-party dependencies in their plug-in packages.

Why do we need to invent another uni_modules wheel after having node_modules?

node_modules does not meet the needs of cloud integration. UniCloud's cloud functions, public modules, schema and various js_sdk, components, pages and projects in the front end cannot be effectively integrated in the node_modules mode.
uni_modules is provided in the form of paid and commercial plug-ins, and the DCloud plug-in market provides copyright protection. But node_modules does not support payment and copyright protection.
node_modules is a developer-friendly mode that affects the performance of end users. To save trouble, developers nested node_modules layer by layer, resulting in an astonishing number of files. uni_modules Module nesting is not supported, and developers are encouraged to optimize package’s size
uni_modules encourages developers to always use the latest version. And tools for version content comparison are provided in HBuilderX
node_modules placing is also supported in uni_modules, without forced rejection.

What are the advantages of uni_modules compared with ordinary plugins in the plugin market?

Support direct release, update and deletion in HBuilderX
Support dependencies (configured in package.json)
If the location of the plug-in file is uniform, it will not cause the problem of downloading a plug-in but not knowing how many files are written to the number of directories under the project. When deleting the plug-in, you can delete it with one click

# Directory structure

If the uni_modules plugin is a project type plugin, you only need to put a package.json that conforms to the uni_modules specification in the root directory of the project.

If it is a plug-in of non-project type, such as component, js sdk, page template and cloud function, it needs to be placed in the uni_modules directory of the project.

At this time, the directory structure under the uni_modules directory is the same as the project structure of uni-app, as follows:

	
uni_modules                                ...
// ...
└── [plugin_id]
    ├── uniCloud                           ...
    ├── components                         ...
    ├── hybrid                             ...
    ├── pages                              ...
    ├── static                             ...
    ├── license.md                         ...
    ├── package.json                       ...
    ├── readme.md                          ...
    ├── changelog.md                       ...
    ├── menu.json                          ...

Tips

Files of pages.json, App.vue, main.js, manifest.json and uni.scss are not supported in the plug-in directory. If plug-in users need to modify the contents of these files, please elaborate in detail in the plug-in document (readme.md).
When referencing resources or jumping pages inside plug-ins, please use relative paths as much as possible.
The components directory in the plug-in also supports easycom specification. Plugin users can directly use the components meeting the easycom specification in the plug-in in the project. When there is an easycom component conflict in the project or plug-in, a prompt will be given during compilation and you can resolve the conflict by modifying the component directory and component file name.

# Configuration

# package.json

package.json must exist in every uni_modules plug-in and contains the basic information of plug-ins. The following is a detailed configuration description of package.json

{
    //Note that you cannot directly copy this code into the editor, and package.json currently does not support comments. The comments added in this paragraph are only used to explain the code.
    //Required, plug-in ID, in the format: 'Author ID - English name of plug-in', for example: 'xx-yy', where the author ID and plug-in name can only contain English and numbers. Author ID cannot use 'DCloud', 'uni' and other keywords
    "id": "Author ID - English name of plug-in",
    // Required, used to display the displayed name in the plug-in market
    "displayName": "Displayed name of plug-in",
    // Required, plug-in version
    "version": "1.0.0",
    // Required, plug-in description
    "description": "Plug-in description",
    //Required, keywords of plug-in tag, up to 5
    "keywords": [],
    // Repository address
    "repository": "github:user/repo",
    //HBuilderX/cli minimum compatible version
    "engines": {
        "HBuilderX": "^3.1.0"
    },
    //DCloud plug-in market configuration
    "dcloudext": {
      // Required, plug-in market classification
      "category": ["Front-end component", "Universal component "],
      //Sale (currently only uniCloud plug-ins)
      "sale": {
          //Price of ordinary authorized version, in yuan. If it is a free plug-in, set the price of ordinary authorized version to 0.
          "regular": {
              "price": "0.00"
          },
          //Price of source code authorized version, in yuan
          "sourcecode": {
              "price": "0.00"
          }
      },
      //QQ numbers of the plug-in author, which facilitates the communication between the administrator and the author when reviewing.
      "contact": {
          "qq": ""
      },
      //Privacy, permissions and commercialization statement
      "declaration": {
          //Required. Whether the plug-in contains advertisements. If so, please fill in the advertising expression and display frequency in detail; if not, please fill in "None
          "ads": "",
          //Required. Please truthfully fill in the data collected by this plug-in, the sent server address, and the description of the purpose of the data. If no data is collected, please fill in "The plug-in does not collect any data". If the third-party SDK used needs to collect data, please fill in "XX SDK used by the plug-in will collect data. For details, please refer to https://other-sdk.com/
          "data": "",
          //Required. The list of system permissions that this plug-in needs to apply for, please fill in truthfully. If you need no permission, please fill in "None
          "permissions": ""
      },
      //npm address
      "npmurl":"" 
    },
    //uni_modules configuration
    "uni_modules": {
        //List of dependent uni_modules plug-in ID
        "dependencies": [],
        //Configure cloud function, public module, clientDB Action encryption
        "encrypt": [
            // Note that this is the real file path. uniCloud under uni_modules does not have -aliyun or -tcb suffix, but unicloud under the root directory of the project has suffix
            "uniCloud/cloudfunctions/uni-admin/controller/permission.js" 
        ],
        //Platform compatibility: y means Yes, supported; n means No, not supported; u means Unknown, uncertain; The default is u.
        "platforms": {
            //Cloud platform compatibility
            "cloud": {
                "tcb": "y",
                "aliyun": "y"
            },
            //Front-end platform compatibility
            "client": {
                "App": {
                    "app-vue": "y",
                    "app-nvue": "n"
                },
                "H5-mobile": {
                    //Configure minVersion when you need to specify a minimum version to support it
                    "Safari": {
                        "minVersion": "14.0.2"
                    },
                    "Android Browser": "y",
                    "WeChat browser (Android)": "u",
                    "QQ browser (Android)": "u"
                },
                "H5-pc": {
                    "Chrome": "y",
                    "IE": "u",
                    "Edge": "u",
                    "Firefox": "u",
                    "Safari": "u"
                }
            }
        }
    }
}

Tips

The above configuration is based on the npm package.json (opens new window) specification extension, so the standard package.json attribute is also supported. For example, the plug-in package content to be uploaded can be controlled by files.

# uni_modules.config.json

uni_modules.config.json In the root directory of the project, you can configure the trigger script updated by the plug-in (usually used to perform customized automation tasks) and the service space supported by the plug-in uniCloud. The following is a detailed configuration description of uni_modules.config.json

{
	"scripts": {
		//Execute this script after updating the plug-in, and the currently updated plug-in ID can be acquired from process.env.UNI_MODULES_ID. If there are more than one ID, separate them by ","
		"postupdate": "node scripts/upgrade.js",
		// Execute this script before uploading the plug-in, and the currently updated plug-in ID can be acquired from process.env.UNI_MODULES_ID. If there are more than one ID, separate them by ","
		"preupload": "node scripts/preupload.js",
		//Execute this script after uploading the plug-in (no matter success or failed), and the currently updated plug-in ID can be acquired from process.env.UNI_MODULES_ID. If there are more than one ID, separate them by ","
		"postupload": "node scripts/postupload.js"
	},
	"uni_modules": {
		//Plug-in ID
		"uni-id": {
			//When both aliyun and tcb exist in the project, you can manually specify the service space to which the plugin belongs
			"uniCloud": ["aliyun", "tcb"]
		}
	}
}

Tips

When only one service space is associated with the project, the uniCloud-related resources in the uni_modules plugin will be automatically attributed to this service space, so there is no need to configure the service space to which uniCloud belongs in uni_modules.config.json
When there are two service spaces in the project (Alibaba Cloud and Tencent Cloud exist at the same time)
- If the platform is not configured in uni_modules.config.json, then when uploading the uniCloud resources of this plug-in, you will be prompted to select which service space to upload to
- If the platform has been configured in uni_modules.config.json, the configuration will prevail when uploading and it will be automatically attributed to the specified service space

# npmignore

When uni_modules plug-in is released to plug-in market, it is usually necessary to ignore some directories or files, such as unpackage, .hbuilderx, node_modules and so on, then the file can be ignored by npmignore file.

File name: .npmignore. Note that there is a dot at the beginning. Contents of a typical npmignore file are as follows:

.hbuilderx
unpackage
node_modules
package-lock.json

Notice

The .npmignore in the project root directory is effective for publishing projects and plug-in templates. uni_modules/Plug-in Id/.npmignore Effective for published plug-ins

# Develop uni_modules plug-in

# Create new uni_modules directory

In the root directory of the uni-app project, create the uni_modules directory, and you can click Create uni_modules directory on the right-click menu of the project.

Tips:

In case of vue-cli project, the uni_modules directory is located under src, which is src/uni_modules

# Create uni_modules plug-in

Right-click the uni_modules directory in HBuilderX Create uni_modules plug-in

Fill in the correct plug-in ID and select the plug-in classification

Plugin ID naming specification:

In the format of: 'Author ID - English name of plug-in'. For example, xx-yy, where the author ID and English name of plug-in can only contain English and numbers
Author ID is defined by the plug-in author, and cannot use 'DCloud', 'uni' and other keywords. Its length is required at least 2 characters
The plug-in name should visually express the function of the plug-in. For example: tag, button, etc.

Tips

The uni_modules plug-in can be configured with three-party dependencies in the uni_modules->dependencies node of package.json (the dependent plug-in must also be the uni_modules plug-in). If it is an npm plug-in that relies on three parties, you can use the standard dependencies node configuration.

# Release to plug-in market

When your plug-in is developed, you can publish it directly to the plug-in market (opens new window) for free or paid use by others. The plug-in market provides mechanisms such as realization and evaluation. Excellent plug-in authors can earn tens of thousands of dollars a month.

Release process:

Right-click the plug-in directory in HBuilderX Release to plug-in market
Fill in the plug-in information Tips

If you need to release it as a project template, please create package.json in the root directory of the project, and then right-click the menu to release to the plug-in market.
When releasing the plug-ins, you can choose to upload the current project as an example project. A complete example project helps users get started quickly.

# Modify plug-in basic information

When your plug-in is released to the plug-in market, if you need to adjust some basic information in the plug-in market, such as Chinese name, description, keywords, and readme.md, you can right-click the Modify the plug-in basic information directly in the plug-in directory.

Right-click the plug-in directory in HBuilderX Modify the plug-in basic information
Modify plug-in basic information

# Release new version

When your plug-in has added new functions or fixed bugs, and a new version needs to be released, the operation is the same as that of the first release, and you can right-click the Release to plug-in market directly in the plug-in directory.

Tips

The update log filled in the releasing window will automatically be synchronized with changelog.md in the root directory

# Use uni_modules plug-in

# Add uni_modules plug-in

Find the uni_modules plugin that meets your needs in the Plug-in market (opens new window)
On the plug-in details page, the right side will indicate whether the plug-in supports uni_modules, clickUse HBuilderX to import the plug-ins
Select the uni-app project to import

Tips

uni_modules supports the component easycom, and users can directly use the components meeting the easycom specification in the plug-in
Other resources, such as images and js, can be directly introduced and used according to the directory structure in the project. For example:

import {test} from '@/uni_modules/xx-yy/js_sdk/test.js'

To use the pages in uni_modules, you need to add the corresponding page configuration in pages.json in the root directory of your project

{
  "pages":[{
    //Introduce the corresponding pages according to the directory where the plug-in is located
    "path":"uni_modules/xx-yy/pages/demo/demo" 
  }]
}

# Install uni_modules plug-in dependencies

When importing a plug-in, HBuilderX will automatically install all third-party dependencies of the current plug-in.
You can also perform Dependency of third-party plug-in installation

# Update uni_modules plug-in

You can check and update the currently used plug-ins by right-clicking the Update from the plug-in market
Compare plug-ins and confirm the updated content

# Uninstall uni_modules plug-in

The uni_modules plug-in directory is standalone. If you no longer need the plug-in, you can delete it directly.

Tips

Importing the uni_modules specification plug-in requires HBuilderX 3.1.0+

# Guide to migrating existing plugins to uni_modules plug-ins

Migrate the plug-in content to the directory named after the plug-in ID under the root directory of your uni-app sample project uni_modules. For example, if your existing plug-in ID is xx-yy, the directory structure is: uni_modules/xx-yy
Run your own sample project to verify that if all functions are normal after the plug-in migrates to the directory

When migrating directories, you will usually encounter problems with resource reference paths. So all path references should be modified as relative paths as much as possible.
If the plug-in has a cloud function or database of uniCloud, please note that uniCloud in the plug-in directory cannot have suffixes of the vendor when migrating. You can specify the cloud service provider supported by the plug-in when releasing the plug-in.
Files of pages.json, App.vue, main.js, manifest.json and uni.scss are not supported in the plug-in directory. If plug-in users need to modify the contents of these files, please elaborate in detail in the plug-in document (readme.md).

When all the functions of the migrated plug-ins are normal, you can release a new version of the plug-in that supports uni_modules to the plug-in market (the plug-in market will keep your last version of the non-uni_modules plug-in at the same time)

Create package.json in the root directory of plug-in, you can simply fill in one plug-in ID temporarily, and fill in other information through the release window (it will be automatically synchronized back to package.json)

{
  "id": "Your plug-in ID"
}

Plug-in document, migrate to readme.md in the root directory of plug-in
Right-click package.json and click Release to plug-in market, select the classification, and fill in the plug-in information (consistent with the existing information in the plug-in market as much as possible)
After the publication is successful, you can check on the right side of the plug-in details page of the plug-in market that your plug-in has provided both uni_modules version and non-uni_modules version (only the last non-uni_modules version is kept).