Packages

This repository hosts the following Node.js packages for API development at BYU OIT:

• @byu-oit/jwt
• @byu-oit/fastify-jwt

The documentation and source code for previous versions of the byu-jwt package are found on the v3 branch in this repository.

Note Requires Node.js >= v18 OR a fetch polyfill such as node-fetch.

Contributing

This project uses Lerna with Nx to build, test, and lint the source code. Please consult their documentation when making modifications to the maintenance process of this project.

There are a few commands that most of the packages share:

• build: Compile the distribution code
• lint: Lint the source code
• test: Test the source code with Ava

If you notice a problem, please submit an issue or create a PR with the fix!

Committing

Commit messages must adhere to the angular conventional commit standard. commitlint will enforce commit messages to follow this standard. Following a commit standard enables our distribution pipeline to publish new versions of each package automatically.

Building

This library exposes files in both CJS and ESM syntax in order to accommodate browser environments and legacy Node.js applications. CJS support may be dropped in the future but is supported for the time being.

There are two ways that we know of to support both CJS and ESM syntax:

1. Create a localized package.json file in each packages' cjs directory with the contents { type: 'commonjs' }. This effectively overwrites the package's own package.json which is set to module.

   Node Resolution Algorithm: See ESM_FILE_FORMAT

   ESM & CommonJS Module Tutorial: https://www.sensedeep.com/blog/posts/2021/how-to-create-single-source-npm-module.html

2. Use a tool such as unbuild which outputs files with the .cjs and .mjs extensions.

   Example of Using unbuild: https://github.com/unjs/radix3/blob/main/package.json

   MDN Docs: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules

This library uses the first method for two reasons:

1. Some tools may never support the .mjs extension
2. (package.json).type is more deterministic since the resolution algorithm is built into node and bundlers.

Testing

The choice to use Ava was made because it

1. supports TypeScript and ESM out of the box
2. parallelizes tests in separate environments making ava typically faster
3. does not mutate Node.js globals like Jest
4. follows a similar convention as the node test runner which we may eventually adopt

Running tests requires building the source code first, which should be handled for you by lerna.

From the root of the project you can run:

npm test

Note There is a bug in Node.js Worker threads which requires us to use the --no-worker-threads flag when running tests. Even with that flag enabled, some tests run into this bug. There isn't a bug report for the issue yet (See this discussion).

Publishing

Merging changes into the main branch will automatically update the version of each package, publish the package, and publish the changelog according to the commit messages.

Merging changes into the beta branch will trigger the same GitHub workflow but the beta prefix will be prepended to the new versions published.

The publish workflow was heavily inspired by the article "Automatic versioning in a Lerna monorepo using Github actions" by Xavier Canchal 👏.

Documentation & Linting

Writing SDKs with TypeScript and TSDocs provides consumers with the code and documentation all from their development environments. To that end, running the linter without documenting code with TSDocs style documentation (similar to JSDocs or JavaDocs), will return a non-zero exit code.