For this guide we will be publishing a simple NPM typescript package called "npm-package-template-changesets" by using PNPM and the changesets cli. This setup automates several key parts of the publishing process: when you make changes to the library, a bot automatically opens a pull request containing the updated changelog and the version bump. Once this pull request is merged, a new version of the package with the latest changes is created.
Features:
- TypeScript support
- Automated release management
- CJS and ESM support
Example repo: https://github.com/sebastianwd/npm-package-template-changesets
1. Install PNPM and create a new project
npm install -g pnpm
pnpm init
This will generate a single package.json file, change the name property to a package name that doesn't exist yet:
Also create a new repository on GitHub and add the url to the repository.url property, it's important for provenance:
{
"name": "npm-package-template-changesets",
"repository": {
"url": "https://github.com/sebastianwd/npm-package-template-changesets"
},
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"license": "ISC"
}
2. Install dependencies
pnpm add tsup typescript @changesets/cli -D
- tsup: used to build the typescript code, usage of this dep will depend on your use case
- typescript: necessary dependency
- @changesets/cli: used to for versioning and publishing
3. Generate tsconfig files
For this case we will use 2 tsconfig files: tsconfig.build.json and tsconfig.json. The difference between them is that tsconfig.build.json will use the properties composite: true and rootDir: "./src" so the build only looks at files in the src directory, while in development the tsconfig.json will override these settings and use rootDir": "." to enable typescript for config files at the root level.
tsconfig.build.json
{
"compilerOptions": {
/* Base Options: */
"rootDir": "./src",
"esModuleInterop": true,
"skipLibCheck": true,
"target": "es2022",
"allowJs": true,
"resolveJsonModule": true,
"moduleDetection": "force",
"isolatedModules": true,
"verbatimModuleSyntax": true,
/* Strictness */
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"module": "preserve",
"outDir": "dist",
"sourceMap": true,
"declaration": true,
"composite": true,
"noEmit": true,
/* If your code doesn't run in the DOM: */
"lib": [
"es2022"
],
},
"include": [
"src"
],
}
tsconfig.json:
{
"extends": "./tsconfig.build.json",
"compilerOptions": {
"composite": false,
"rootDir": "."
}
}
4. Add files to be published:
For this example, we will add a single index.ts file in the src directory:
index.ts
export const hello = () => "hello world";
5. Update package.json:
Add scripts:
"scripts": {
"build": "tsup src",
"release": "changeset",
"ci:publish": "pnpm build && changeset publish --access public"
}
Add NPM config:
"publishConfig": {
"provenance": true,
"access": "public"
}
Add entrypoints and type config in package.json:
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
},
"main": "dist/index.cjs",
"module": "dist/index.mjs",
"types": "dist/index.d.ts",
The require and main properties are for end users using CommonJS, which is older than ESM. ESM enables modern syntax and many benefits over CJS, but we will support both for this guide. For ESM the propeties module and import are the ones that apply.
To build files for both .cjs and .mjs extensions, we can use tsup:
tsup.config.ts
import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts"],
splitting: false,
clean: true,
dts: true,
format: ["cjs", "esm"],
outExtension({ format }) {
return {
js: format === "cjs" ? ".cjs" : ".mjs",
};
},
});
6. Adding Github workflow file
.github/workflows/publish.yml
name: Publish
on:
push:
branches:
- master
concurrency: ${{ github.workflow }}-${{ github.ref }}
permissions:
contents: write
pull-requests: write
packages: write
id-token: write
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20.x
cache: "pnpm"
registry-url: "https://registry.npmjs.org"
- run: pnpm install --frozen-lockfile
- name: Create Release Pull Request or Publish
id: changesets
uses: changesets/action@v1
with:
publish: pnpm run ci:publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
The GITHUB_TOKEN is already present in the Github's repository by default, the NPM_TOKEN value has to be generated in npm with publish permission:
Then, on your repo on Github, go to Settings and add it to the secrets:
Also go to Actions > General
and enable this option or changesets won't be able to open PRs:
7. Generate first changeset
- Init changesets:
pnpm changeset init
- Create a first commit:
git init
git add .
git commit -m "first release"
- Run changeset:
pnpm release
If you get an error about "Failed to find where HEAD diverged from main", configure your base branch in
.changeset/config.json
You will be prompted some options, for this example we will choose patch:
- New files were created in the
.changesetsfolder, for this first release we should amend them to the previous commit so we don't add another one:
git add .
git commit -m "first release" --amend
8. Push to the repository
git push origin master
After the CI is done, check the Pull Requests tab on the repo, there should be one open
Review it and merge it.
9. Check your package on NPM
Top comments (0)