cortex-engineering

bun-typescript-starter

Modern TypeScript starter template with enterprise-grade tooling.

Features

• Bun - Fast all-in-one JavaScript runtime and toolkit
• TypeScript 5.9+ - Strict mode, ESM only
• Biome - Lightning-fast linting and formatting (replaces ESLint + Prettier)
• Vitest - Fast unit testing with native Bun support
• Changesets - Automated versioning and changelog generation
• GitHub Actions - Comprehensive CI/CD with OIDC npm publishing
• Conventional Commits - Enforced via commitlint + Husky

Quick Start

Prerequisites

• Bun installed (curl -fsSL https://bun.sh/install | bash)
• GitHub CLI installed and authenticated (gh auth login)
• npm account with a granular access token (see NPM Token Setup)

Option A: GitHub CLI (Recommended)

Create a new repo from this template and set it up in one command:

# Create repo from template
gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone

# Run setup (interactive)
cd my-lib
bun run setup

Option B: CLI Mode (Non-Interactive)

For automated/scripted setups, pass all arguments via CLI flags:

# Create repo from template
gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
cd my-lib

# Run setup with all arguments (no prompts)
bun run setup -- \
  --name "@myusername/my-lib" \
  --description "My awesome library" \
  --author "Your Name" \
  --yes

Option C: degit

npx degit nathanvale/bun-typescript-starter my-lib
cd my-lib
bun run setup

Setup Script

The setup script configures your project and optionally creates the GitHub repository with all settings pre-configured.

Interactive Mode

bun run setup

Prompts for:

• Package name (e.g., @myusername/my-lib or my-lib)
• Repository name
• GitHub username/org
• Project description
• Author name

CLI Mode

bun run setup -- [options]

Flag	Short	Description
--name	-n	Package name (e.g., @myusername/my-lib)
--repo	-r	Repository name (defaults to package name)
--user	-u	GitHub username/org (auto-detected from gh)
--description	-d	Project description
--author	-a	Author name
--yes	-y	Skip confirmation prompts (auto-yes)
--no-github		Skip GitHub repo creation/configuration
--help	-h	Show help

What Setup Does

1. Configures files - Replaces placeholders in package.json and .changeset/config.json
2. Installs dependencies - Runs bun install
3. Creates initial commit - Commits all configured files
4. Creates GitHub repo (if it doesn't exist) - Uses gh repo create
5. Configures GitHub settings:
   • Enables workflow permissions for PR creation
   • Sets squash-only merging
   • Enables auto-delete branches
   • Enables auto-merge
   • Configures branch protection rules

Complete Setup Guide

This guide walks through the full process of creating a new package and publishing it to npm.

Step 1: Create Repository

# Create and clone from template
gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
cd my-lib

Step 2: Run Setup

# Interactive mode
bun run setup

# Or non-interactive mode
bun run setup -- \
  --name "@myusername/my-lib" \
  --description "My awesome library" \
  --author "Your Name" \
  --yes

Step 3: Install Changeset Bot

Install the Changeset Bot GitHub App on your repo. It comments on every PR with changeset status so you know at a glance whether version bumps are queued.

1. Visit https://github.com/apps/changeset-bot
2. Click Install and select your repository
3. Grant the requested permissions (pull request read/write, contents read-only)

The bot works alongside the autogenerate-changeset.yml workflow — the bot comments instantly, and the workflow auto-generates a changeset file if one is missing.

Step 4: Configure NPM Token

Before publishing, you need to add your npm token to GitHub secrets.

Create npm Granular Access Token

1. Go to npmjs.com → Access Tokens → Generate New Token → Granular Access Token

2. Configure the token:

   • Token name: github-actions-publish (or any name)
   • Expiration: 90 days (maximum for granular tokens)
   • Packages and scopes: Select "All packages" for new packages, or specific packages for existing ones
   • Permissions: Read and write
   • IMPORTANT: Check "Bypass two-factor authentication for automation"

   Without "Bypass 2FA", CI/CD publishing will fail with "Access token expired or revoked"

3. Copy the token (starts with npm_)

Add Token to GitHub Secrets