Stop using "npm publish"

Publishing your package to npm is not limited to a single command line "npm publish", there are other steps you have to do before release your product to other developers. But is there a way to optimize that in one single command line? Yes!

Aux4 is an open source CLI (command line interface) generator friendly to use in your project. It generates a CLI from a simple JSON file.

The JSON structure is simple, it's an object with a list of profiles. Each profile has a name and a list of commands. The main profile is where aux4 will start listing your commands.

Install aux4

Aux4 is a npm package, you can easily install by:

npm install -g aux4

Create the .aux4 file

You can create an .aux4 file in the root of your project.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "value": "release",
          "execute": [
            "echo 'npm publishing'"
          ]
        }
      ]
    }
  ]
}

Execute

To execute just use aux4 command from the root folder of your project or any sub-folder. The output will be npm publishing.

aux4 release

npm publishing

Add the real steps

Let's say the first step you want to do is execute your tests, change the version in the package.json file, after that build your package, create a tag on git, and finally publish to npm, and. pushing your changes to the repository. Here are the steps:

1. test
2. define npm version
3. build
4. git tag
5. npm publish
6. git push

In this post I am just demonstrating what you can do, but have to adapt to your project's reality and perform the steps you need.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "value": "release",
          "execute": [
            "npm test",
            "npm version patch",
            "npm run build",
            "json:cat package.json",
            "set:versionNumber=${response.version}",
            "git tag -a ${versionNumber} -m '${versionNumber}'",
            "git push --follow-tags",
            "npm publish ./build",
            "rm -rf build",
            "git push",
            "echo ${versionNumber} released successfully"
          ]
        }
      ]
    }
  ]
}

What are those lines?

I am going to describe what's every line to make it more clear.

npm test

execute the tests.

npm version patch

increment the patch of the current version defined in your package.json file. e.g.: if your current version is 1.0.1 it will increment to 1.0.2.

npm run build

it will build your project if you have it defined in the scripts. You can do that in different ways, this is just a demonstration.

json:cat package.json

cat package.json will print the content of the file to the output of the console. The prefix json: convert the JSON string to a JSON object.

set:versionNumber=${response.version}

In aux4 ${response} is the output of the previous line, in this case, how in the previous line we converted the JSON to an object, we can access its properties.
Here it's setting a variable versionNumber with the version of the package. The structure is set:variable=value.

git tag -a ${versionNumber} -m '${versionNumber}'

Create a tag in the repository with the same version.

git push --follow-tags

Push only the tags to your git repository.

npm publish ./build

Publish the package to npm.

rm -rf build (optional)

Deletes the build folder. It's not needed, but it might be useful.

git push

Pushes your changes to the git repository.

echo ${versionNumber} released successfully

Displays 1.0.2 released successfully to the output.

Add documentation to your command

Aux4 allows to document your commands, so the other people using that can easily understand what's the purpose of your commands. To do that you just need to add a help section to your command.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "value": "release",
          "execute": [
            "npm test",
            "npm version patch",
            "npm run build",
            "json:cat package.json",
            "set:versionNumber=${response.version}",
            "git tag -a ${versionNumber} -m '${versionNumber}'",
            "git push --follow-tags",
            "npm publish ./build",
            "rm -rf build",
            "git push",
            "echo ${versionNumber} released successfully"
          ],
          "help": {
            "description": "publish a new version of my package to npm"
          }
        }
      ]
    }
  ]
}

The documentation is displayed when you execute the command aux4.

aux4

     aux4   aux4 utilities
  release   publish a new version of my package to npm

Add a parameter

You can add a parameter in case you don't want to release a patch every time. So in the parameter you can specify which type of version you are releasing.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "value": "release",
          "execute": [
            "npm test",
            "npm version ${version}",
            "npm run build",
            "json:cat package.json",
            "set:versionNumber=${response.version}",
            "git tag -a ${versionNumber} -m '${versionNumber}'",
            "git push --follow-tags",
            "npm publish ./build",
            "rm -rf build",
            "git push",
            "echo ${versionNumber} released successfully"
          ],
          "help": {
            "description": "publish a new version of my package to npm"
            "variables": [
              {
                "name": "version",
                "text": "type of version release. e.g.: major, minor, patch",
                "default": "patch"
              }
            ]
          }
        }
      ]
    }
  ]
}

Variables have three attributes:

• name: the variable name
• text: the documentation of the variable
• default: the default value in case the variable is not defined.

npm version ${version}

Using the variable to specify the type of version.

Documentation

aux4

     aux4   aux4 utilities
  release   publish a new version of my package to npm
              - version [patch] type of version release. e.g.: major, minor, patch

Execution

aux4 release --version minor

1.1.0 released successfully

Conclusion

aux4 is a great tool to optimize your time, simplify and document your scripts and make it easier to share with your team.
The main benefit of using aux4 is allowing all your team to not forget any important step while performing some task by sharing your custom project tool with your team.

Comment

Your opinion matters, what do you think about aux4? Are you going to use it in your project? Please share your thoughts in the comment section.

Comments

[Edwin]

This seems to have some overlap with Lerna, which is focused on managing mono-repo packages, but I guess you could use aux4 for a wider range of tasks. Still, I would rather just hook into NPM lifecycle methods such as prepublish (or similar) to lint/build/test the source code and let my developers use the regular npm publish/lerna publish commands, instead of introducing a new tool.

What's the difference between aux4 profiles and task configurations in build tools like Grunt?

[David SG]

Hey Edwin, thanks for your comment. The aux4 goal is organizing and documenting your scripts, so you can simplify your daily activities by adding them to aux4.
There are multiple ways to make things done, as you mentioned Lerna, grunt, bash script into prebuild, could all produce the same result, so you could use the way the fits better to your project.
This particular post is focused on the aux4, just to show one possible application for that.
You can think of aux4 as an organizer for all command lines you are regularly executing during your day.