diff --git a/.github/dependabot.yml b/.github/dependabot.yml index a21cb84..24c534b 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,6 +1,12 @@ version: 2 updates: - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + target-branch: dev + + - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml index ff27d10..e37b7b0 100644 --- a/.github/workflows/npm-publish.yml +++ b/.github/workflows/npm-publish.yml @@ -1,39 +1,40 @@ -# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created -# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages +# Publishes the package to npm when a GitHub release is created. +# Uses npm Trusted Publishing (OIDC) — no NPM_TOKEN secret required. +# See PUBLISHING.md for setup instructions. -name: Node.js Package - -permissions: - contents: read - packages: write +name: Publish to npm on: release: types: [created] jobs: - publish-npm: + publish: runs-on: ubuntu-latest + permissions: + contents: read + id-token: write # Required for npm Trusted Publishing (OIDC) steps: - name: Check out code - uses: actions/checkout@v4 + uses: actions/checkout@v6 + + - name: Install pnpm + uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0 + with: + version: 9 - name: Set up Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: - node-version-file: 'package.json' # Grabs node version from package.json + node-version-file: 'package.json' registry-url: https://registry.npmjs.org/ + cache: pnpm - - name: Install pnpm - run: npm install -g pnpm - - - name: Install deps - run: pnpm i + - name: Install dependencies + run: pnpm install --frozen-lockfile - name: Build package run: pnpm build - name: Publish package - run: pnpm publish --no-git-checks - env: - NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}} + run: npm publish --provenance --access public diff --git a/.github/workflows/prettier.yml b/.github/workflows/prettier.yml index c3aa6b0..a3885cc 100644 --- a/.github/workflows/prettier.yml +++ b/.github/workflows/prettier.yml @@ -20,22 +20,25 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out code - uses: actions/checkout@v4 + uses: actions/checkout@v6 with: ref: ${{ github.head_ref }} fetch-depth: 0 # Ensures history is checked out token: ${{ secrets.GITHUB_TOKEN }} # Use the GitHub token for authentication - - name: Set up Node.js - uses: actions/setup-node@v4 + - name: Install pnpm + uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0 with: - node-version-file: 'package.json' # Grabs node version from package.json + version: 9 - - name: Install pnpm - run: npm install -g pnpm + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version-file: 'package.json' + cache: pnpm - name: Install dependencies - run: pnpm install + run: pnpm install --frozen-lockfile - name: Run prettier run: pnpm prettier diff --git a/PUBLISHING.md b/PUBLISHING.md new file mode 100644 index 0000000..d4376d5 --- /dev/null +++ b/PUBLISHING.md @@ -0,0 +1,70 @@ +# Publishing to npm + +This project uses **npm Trusted Publishing** (OIDC) via GitHub Actions. +When a GitHub release is created, the [npm-publish workflow](.github/workflows/npm-publish.yml) automatically builds and publishes the package to npm — no long-lived tokens required. + +## One-time setup (npmjs.com) + +> You must have published at least one version of the package to npm before you can enable trusted publishing. + +1. Go to [npmjs.com](https://www.npmjs.com) and sign in to the account that owns your package. +2. Navigate to your **package settings** page: `https://www.npmjs.com/package//access` +3. Under **Publishing access**, find the **Trusted Publishers** section. +4. Click **Add a trusted publisher** and fill in: + - **Organization or user:** Your GitHub username or organization + - **Repository:** Your repository name + - **Workflow filename:** `npm-publish.yml` + - **Environment:** _(leave blank)_ +5. Save the configuration. + +Once this is done, the GitHub Actions workflow can publish to npm using OIDC without any stored secrets (`NPM_TOKEN` is no longer needed and can be removed from the repository secrets if it exists). + +## How to publish a new release + +1. **Update the version** in `package.json`: + + ```bash + # Bump the patch version (e.g., 0.10.2 → 0.10.3) + npm version patch + + # Or for a minor version bump (e.g., 0.10.2 → 0.11.0) + npm version minor + + # Or for a major version bump (e.g., 0.10.2 → 1.0.0) + npm version major + ``` + + This updates `package.json` and creates a git tag automatically. + +2. **Push the commit and tag** to GitHub: + + ```bash + git push origin master --follow-tags + ``` + +3. **Create a GitHub release** from the tag: + - Go to your repository's releases page and click **Draft a new release** + - Select the tag you just pushed (e.g., `v0.10.3` or `0.10.3`) + - Fill in the release title and notes + - Click **Publish release** + +4. The **npm-publish** workflow will trigger automatically, build the package, and publish it to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements) attached. + +## What the workflow does + +``` +checkout → install pnpm → setup node → pnpm install → pnpm build → npm publish --provenance +``` + +- Uses OIDC (`id-token: write` permission) so npm can verify the package was published from this repository. +- Runs `pnpm install --frozen-lockfile` for reproducible builds. +- Publishes with `--provenance` so consumers can verify the package origin on npmjs.com. + +## Troubleshooting + +| Problem | Fix | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| **"No matching trusted publisher"** error in CI | Ensure the workflow filename in npmjs.com settings matches exactly: `npm-publish.yml` | +| **403 Forbidden** during publish | Verify that trusted publishing is configured for the correct user/org and repo on npmjs.com | +| **Version already exists** | You need to bump the version in `package.json` before publishing. npm does not allow re-publishing the same version. | +| **Provenance error** | Make sure the workflow has `permissions: id-token: write` and is running in a public repository |