Packages

Generating package

---

To create a new JavaScript library using NX, follow these steps:

1. Open a terminal window and navigate to the root directory of your NX workspace.
2. Run the following command:

npx nx generate @nx/js:library <library-name> --directory=<directory-name> --unitTestRunner=vitest --publishable --importPath=<import-path>

Replace with the desired name for your library, with the directory where you want the library to be created, and with the import path for your library. Here's an explanation of the arguments:

• @nx/js:library is the schematic that will be used to generate the library. This is provided by the @nx/js package.
• <library-name> is the name of your library. This should be in kebab-case (lowercase with hyphens) and should describe the purpose of your library.
• --directory=\<directory-name> specifies the directory where your library will be created. This should be in camelCase (lowercase with no spaces, but with the first letter of each word capitalized).
• --publishable creates a library that can be published to an external registry (like npm), or in our case Github Packages.
• --importPath=\<import-path> is the import path for your library. This should be in the format @<scope>/<library-name>, where <scope> is your npm scope (if you have one) and <library-name> is the name of your library in kebab-case.
• unitTestRunner=vitest parameter in the provided NX command allows you to specify the test runner for the generated package. Since we want to use vitest as our main testing tool we will set it to "vitest".

For example, if you want to create a library called math-helpers in the nodejs directory that can be published to npm with an import path of @netspective-labs/math-helpers, you would run the following command:

npx nx generate @nx/js:library math-helpers --directory=nodejs --publishable --importPath=@netspective-labs/math-helpers

This will generate a new library in the nodejs directory of your workspace with the necessary files and configuration to get started building your library.

Test package options

To ensure that all packages have unit tests, we need to enforce failure when running the test target for packages without any tests. Additionally, we want to implement Code Coverage to track the percentage of code covered by unit tests.

To set this up, you need to add two parameters, namely passWithNoTests: false and coverage: true, in the test target within the project.json file. These settings will help maintain test coverage and identify packages lacking tests during the test execution process.

"options": {
  "passWithNoTests": false,
  "coverage": true,
},

Building package

---

To build the package run:

npx nx run <project>:build

Replace <project> with the name of the project you want to build. You can find the project name in the project.json file located at the root directory of the package you are trying to build.

Publishing package

---

In order to publish the package to Github Packages you'll need to change the package.json that's located at the root of it.

"repository": {
  "type": "git",
  "url": "git+https://github.com/<OWNER>/<REPO>/<PACKAGE_NAME>.git",
  "directory": "path/to/your/package"
},
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
}

• Add the repository property with an object with the properties seen above.

  An example of a valid url value would be:

git+https://github.com/netspective-labs/commons/math-helpers.git

• Set the directory property to the actual path to the package. A valid path for the math-helpers package that we created earlier as an example would be packages/nodejs/math-helpers

• Set the publishConfig in order to point to the Github Packages registry.

Note: <PACKAGE_NAME> doesn't have to be neccessarily the name in the project.json. Here you can name the package as you want.

Then we also need to change a little bit the project.json located at the root of the package.

The publish target should look like this:

"publish": {
  "executor": "nx:run-commands",
  "options": {
    "command": "node tools/scripts/publish.mjs <PACKAGE_NAME> {args.ver} {args.tag}",
    "args": "--ver='0.0.1' --tag='latest'"
  },
  "dependsOn": ["build"]
},

IMPORTANT: before publishing your package, run the build command for that package (see "Building" section above).

After these changes were made, we are ready to publish our package. Make sure you've created a Github repository before publishing, if you didn't this won't work.

npx nx run <PACKAGE_NAME>:publish

This will run the command specified in the publish.options.command.

Note: if it's not the first time the package is being published, it may need a version bump. To do this change the version in the package.json and also in the ver args in publish.options.args at the project.json file. Otherwise if you do not do this the publish command will throw an error arguing that you can't publish a package with a version that already exists.

Further help

Visit the Nx Documentation to learn more.