bun-publish-setup

First-time npm publish for bun libraries and GitHub Actions setup for automated publishing.

Prerequisites

• bun is installed
• Logged in to npm (npm whoami to verify)
• GitHub repository exists

Workflow

1. Pre-publish checks & fixes — Validate and fix package.json, tsconfig, build, README, etc.
2. First publish — Confirm with dry-run, then run bun publish
3. GitHub Actions setup — Create workflow for auto-publish on version tag push

Phase 1: Pre-publish Checks & Fixes

1-1: Validate & Fix package.json

Read package.json and validate the following fields. Suggest fixes for any missing or incorrect fields.

Required fields:

• name — Package name. Check if scoped (@scope/name)
• version — 0.1.0 or 1.0.0 is appropriate for first publish
• description — Brief description of the package
• license — e.g. MIT. Verify consistency with LICENSE file

Recommended fields:

• repository — GitHub repository URL. Can be inferred from git remote get-url origin
• keywords — Keywords for npm search
• author — Author info

Entry points (for TypeScript libraries):

• main — CJS entry point (e.g. ./dist/index.js)
• module — ESM entry point (e.g. ./dist/index.mjs)
• types — Type definitions (e.g. ./dist/index.d.ts)
• exports — Conditional exports. Recommended format:

{
	"exports": {
		".": {
			"types": "./dist/index.d.ts",
			"import": "./dist/index.mjs",
			"require": "./dist/index.js"
		}
	}
}

Published files:

• files — Files/directories to include in the npm package (e.g. ["dist", "README.md", "LICENSE"]). Ensure unnecessary files are excluded.

1-2: Check Package Name Availability

npm view <package-name>

• 404 means the name is available
• If already taken, suggest alternative names to the user

1-3: Validate tsconfig.json

For TypeScript projects, verify:

• declaration: true — Type definition generation is enabled
• outDir — Build output directory matches package.json entry points
• declarationDir — Type definition output directory (if configured)

1-4: Run Build (only if build script exists)

Only run if a build script is defined in package.json. Not needed for projects that publish TS source directly.

bun run build

• Verify build succeeds
• Verify expected files are generated in the output directory

1-5: Check README.md

• Verify README.md exists
• If missing, suggest creating one

1-6: Check LICENSE File

• Verify LICENSE file exists
• Verify consistency with license field in package.json
• If missing, suggest creating one based on the license field

Phase 2: First Publish

2-1: Dry-run Preview

bun publish --dry-run

Check the output for:

• Unnecessary files (source code, tests, config files, etc.) in the publish list
• Reasonable package size

If issues found, go back to Phase 1 to fix.

2-2: Publish

Present dry-run results to the user and get confirmation before publishing.

bun publish

For scoped packages on first publish, --access public is required:

bun publish --access public

2-3: Verify Publication

npm view <package-name>

Verify the package was published successfully.

Phase 3: GitHub Actions Setup

3-1: Create Workflow File

Create .github/workflows/publish.yml:

# yaml-language-server:$schema=https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/github-workflow.json
name: npm publish

on:
  push:
    tags:
      - "*"

jobs:
  publish:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          registry-url: "https://registry.npmjs.org"

      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile

      # Include this step only if a build script exists
      - run: bun run build

      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

For scoped packages, change to npm publish --access public. Remove the build step if no build script exists.

3-2: NPM_TOKEN Secret Setup

Guide the user through the following steps:

1. Generate an access token on npm: https://www.npmjs.com/settings/<username>/tokens → “Generate New Token” → Select “Automation” type
2. Go to GitHub repository Settings → Secrets and variables → Actions → “New repository secret”
3. Name: NPM_TOKEN, Value: paste the generated token

3-3: Release Flow

Explain the release process to the user:

# 1. Bump version (automatically creates commit & tag)
npm version patch  # or minor, major

# 2. Push with tags → GitHub Actions auto-publishes to npm
git push --follow-tags