This post first appeared on my personal blog

Offer to come, dig friends take it! I am participating in the 2022 Spring Recruit Punch card activity. Click here for details.

In NPM package development and distribution, there are more or less some problems. Here, I will share some of my experience with you.

Pre-development preparation

How do I choose an open source license?

To develop and distribute a public NPM package means to open source the relevant code, and the open source license of the code is the first step.

For common Open Source licenses and their constraints, refer to the various Open Source agreements and the Open Source Initiative.

In my experience, a more restrictive approach is the GPL and a less restrictive approach is MIT.

GPL stands for code and code derivatives must be open source. MIT stands for the fact that derivatives of code or the code itself can be sold and closed source.

I personally use the MIT protocol.

Setup of development and release directories

NPM development and release directories can be separate or shared.

Generally the two separate ones are developed using TS and compiled using TSC. Or use a compiler such as Webpack to obfuscate compilation or compression after development. There are two directories, the source code directory (typically SRC) and the compiled code directory (typically lib).

If one is shared, it means that the code does not need to compile and is directly distributed.

When setting up directories, pay attention to the main and types and files fields in package.json. Main represents the project entrance in JS environment, types represents the declaration file entrance in TS environment, files represents the files to be published.

In less formal projects, it doesn’t matter if these two fields are misconfigured. Because the startup is directly from the project entrance to start. However, if your project is an NPM package and needs to be referenced by others, there is a need to be careful here.

The two fields main and types represent project entries in your compiled directory if you are publishing. If you are publishing without compiling, these two fields represent the engineering entry to your source code.

If these three fields are not configured, the following problems may occur:

  • The NPM package was released and found to be empty after it was installed. (files not configured properly)
  • The NPM package was published and found to have files in it after installation, but could not be referenced. (Main and Typs not configured)
{
    "main": "lib/index.js"."types": "lib/index.d.ts"."files": [
        "lib/*"]}Copy the code

Version management

NPM version management has the following features:

  • The same version cannot be published repeatedly by default, but it can be set at publish time.
  • Use the Semver version specification.
  • After a release, a release can be revoked under the conditions specified by the NPM.

It is not recommended to specify the pre-release version by adding -alpha after the release number. You can specify the pre-release version by using preID.

When releasing a version, many people may have an initial version of the confusion. That is, what should my first version be?

My personal recommendation is 0.0.0. According to the Semver specification, I recommend using 0.1.0, but I think that 0.1.0 actually means that some features are already developed. If you start at 0.1.0, you build from some features that are already there. But there are already two versions. But at the beginning we had no money. 0.0.0 could not be considered a release number, and the first release after some features were developed could be 0.1.0 instead of the initial release being 0.1.0.

Including switching from 0. Y.z to 1. Y.z, the official version may not be 1.

Of course, this is just personal advice.

Script

The script of package.json is a very powerful tool field. You can configure the actions to be performed before each publish or commit, such as checking code, formatting code, running test cases, etc. Do this to ensure that you are submitting high quality code.

Refer to the NPM lifecycle for hooks before and after release, build, and change. If you need to perform automatic operations before commit, you can install pre-commit.

Private packages and scope packages

You can distribute private packages if you want to distribute a private package for use within your company or organization.

Private packages can be distributed in several ways:

  • Open a paid NPM account.
  • Build Intranet NPM private warehouse, recommend CNPMJS.
  • Use git private repository. Gitea is recommended for possible problems.

If you are a rich bank with a paid NPM account, you can publish scope packages as private packages by publishing them.

The development of

Once you’ve done the above, you can have fun typing code.

There is basically no pit in the development, and even if there is a pit, it is generally not fully understand the CHARACTERISTICS of JS.

After the development of

After development, it is necessary to do some painful things, such as:

compile

If you are using TS development and compiling with TSC, you need to note that if you have code that is not directly referenced, you need to specify it in tsconfig.json. If you are involved in the processing of custom template files, you need to manually copy the files after compiling by script or other means.

The document

As an external service package, you need to have a fairly detailed documentation. In terms of documents, my approach is as follows:

  • For each release, improve the relevant documents of the current version, including but not limited to:

    • Introduction to the whole package.
    • The name of the method or class of the package, how it is called, what it does, and so on.
    • Related code examples.

  • The format of the document is generally as follows:

    • For medium and large projects, such as a framework or a complex tool library, documents are provided in the form of a document website and README is used as a document access point. The document website does not need to purchase a special server or domain name, but can directly use github’s static website service. Vuepress is recommended and can be used with Github.
    • For small projects, such as a small library of tools, write directly using README.
    • If you can write with one README, use README. If you need to open multiple documents, use VuePress to create a document website.

  • README is the key to good documentation because it represents the face of a project and is the first thing you see on both Github and NPM. The README is non-canonical and probably not of interest. For standard README, see standard-readme.

    Of course, it is not necessary to copy completely, you can add some of your own understanding, according to the actual situation of the project to make some adjustments. For example, my projects @Eliassama/Regex, NPM-package-CLI, COMSvr-AST and COMSvr-Random.

test

A good project will spend nearly a third of its time in testing. But for individuals, although not necessarily so strict, but the basic test is still necessary, can not always release the code has problems, that others still use a Luo Yonghao?

Automatic testing is recommended. Jest is recommended and configured to perform automatic tests after compilation, before commit, and before publish to avoid submitting problematic code.

For some inconvenient test, such as CLI tools, also want to test after changing as far as possible.

Remember that when testing, if you have a compiled file, always reference the compiled file to test, so that you can find some problems, such as some files are not compiled, etc.

Play tag

When you’re done testing and documentation is complete, don’t forget to tag a stable or pre-release version of your project.

release

Before the official release, you need to check the following questions for yourself:

  • Is the latest code in the current code directory? (Because I switch between the dev branch and the main branch, I sometimes forget to pull when I switch to main.)
  • If you are sending a package for the first time, check whether the project entry, package name, private/public attributes, git URL, files in the compiled directory, and version number are correct. (Don’t ask me why I said this, can you believe I once sent three versions in a row without sending them correctly…)
  • If you have more than one account, please confirm that the account is the intended one.
  • Check the readme for typos or descriptions. It is not possible to get a readme again after the release.
  • Some documents cannot be released even if you specify them. If you want to use them as template files or if you have to publish them for other reasons, rename them. Refer to the files that NPM publish ignores.

When you go to this step, you have officially released a version, subsequent maintenance and release, just follow these steps again.

I used a cli tool I developed NPM package-cli to initialize a NPM packag template repository NPM -package-template. Interested can refer to, or put forward some suggestions.