The ts-package-template includes a comprehensive set of npm scripts to automate common development tasks. These scripts are defined in the package.json file and can be run using pnpm run <script> or npm run <script>.

Available Scripts

The template includes the following scripts in package.json:

{
  "scripts": {
    "dev": "tsdown --watch ./src",
    "build": "tsc && tsdown",
    "check": "ultracite check",
    "fix": "ultracite fix",
    "test": "vitest run",
    "test:watch": "vitest",
    "changelog": "git-cliff --config ./scripts/git-cliff.toml --output CHANGELOG.md",
    "postversion": "pnpm run changelog",
    "publish": "np --package-manager npm",
    "publish:all": "pnpm run build && pnpm run publish"
  }
}

Script Categories

Development Scripts

Code Quality Scripts

Testing Scripts

Documentation Scripts

Publishing Scripts

Script Details

Development Script (dev)

"dev": "tsdown --watch ./src"

Purpose: Start the development server with hot reload

What it does:

• Runs tsdown in watch mode
• Watches for changes in the ./src directory
• Automatically rebuilds when files change
• Outputs to the configured directory (usually dist)

Usage:

pnpm run dev

Use case: Use during development to automatically rebuild your package when you make changes to the source code.

Build Script (build)

"build": "tsc && tsdown"

Purpose: Build the package for production

What it does:

1. Runs TypeScript compiler (tsc) for type checking
2. Runs tsdown for bundling
3. Outputs files to the dist directory

Usage:

pnpm run build

Use case: Use when you need to create a production-ready build of your package.

Check Script (check)

"check": "ultracite check"

Purpose: Check code quality

What it does:

• Runs Biome to lint and format the code
• Reports linting and formatting issues
• Exits with non-zero code if issues are found

Usage:

pnpm run check

Use case: Use to check code quality before committing or pushing changes.

Fix Script (fix)

"fix": "ultracite fix"

Purpose: Automatically fix code quality issues

What it does:

• Runs Biome to automatically fix linting and formatting issues
• Formats all files according to the configuration
• Organizes imports in all files

Usage:

pnpm run fix

Use case: Use to automatically fix code quality issues. This is also run automatically by the pre-commit hook.

Test Script (test)

"test": "vitest run"

Purpose: Run all tests once

What it does:

• Discovers all test files matching the pattern (**/*.test.ts)
• Runs all tests
• Displays results and summary
• Exits with appropriate status code

Usage:

pnpm run test

Use case: Use to run all tests once, typically in CI/CD environments or when you want to verify all tests pass.

Test Watch Script (test:watch)

"test:watch": "vitest"

Purpose: Run tests in watch mode

What it does:

• Watches for changes in test files and source files
• Automatically re-runs affected tests when files change
• Provides interactive UI for running specific tests

Usage:

pnpm run test:watch

Use case: Use during development to automatically run tests when you make changes.

Changelog Script (changelog)

"changelog": "git-cliff --config ./scripts/git-cliff.toml --output CHANGELOG.md"

Purpose: Generate or update the changelog

What it does:

• Parses all commits since the last tag
• Generates changelog entries based on conventional commits
• Updates the CHANGELOG.md file

Usage:

pnpm run changelog

Use case: Use to generate or update the changelog before releasing a new version.

Postversion Script (postversion)

"postversion": "pnpm run changelog"

Purpose: Automatically update changelog after version bump

What it does:

• Runs the changelog script
• Updates the CHANGELOG.md file

Usage: This script runs automatically when you use npm version or similar commands.

Use case: This ensures the changelog is always up to date when you bump the version.

Publish Script (publish)

"publish": "np --package-manager npm"

Purpose: Publish the package to npm

What it does:

• Runs np to publish the package
• Guides you through the publishing process
• Handles version bumping and changelog generation

Usage:

pnpm run publish

Use case: Use to publish your package to the npm registry.

Publish All Script (publish:all)

"publish:all": "pnpm run build && pnpm run publish"

Purpose: Build and publish the package

What it does:

1. Runs pnpm run build to build the package
2. Runs pnpm run publish to publish to npm

Usage:

pnpm run publish:all

Use case: Use to build and publish the package in one command.

Script Combinations

Common Workflows

Development Workflow

# Start development server
pnpm run dev

# In another terminal, run tests in watch mode
pnpm run test:watch

Build and Test

# Build the package
pnpm run build

# Run tests
pnpm run test

Quality Check

# Check code quality
pnpm run check

# Fix issues automatically
pnpm run fix

Release Workflow

# Build the package
pnpm run build

# Run tests
pnpm run test

# Check code quality
pnpm run check

# Publish to npm
pnpm run publish

Or use the automated script:

# Build and publish
pnpm run publish:all

Customizing Scripts

Add New Scripts

Add new scripts to the scripts object in package.json:

{
  "scripts": {
    "lint": "biome lint",
    "format": "biome format",
    "typecheck": "tsc --noEmit"
  }
}

Modify Existing Scripts

Modify existing scripts to change their behavior:

{
  "scripts": {
    "build": "tsc --noEmit && tsdown --minify",
    "test": "vitest run --coverage"
  }
}

Chain Scripts

Chain multiple scripts together:

{
  "scripts": {
    "ci": "pnpm run check && pnpm run test && pnpm run build"
  }
}

Running Scripts

Basic Usage

Run a script:

pnpm run <script-name>

With Arguments

Pass arguments to scripts:

# Pass arguments to vitest
pnpm run test -- --watch

# Pass arguments to tsdown
pnpm run build -- --minify

Run Multiple Scripts

Run multiple scripts sequentially:

pnpm run build && pnpm run test

Run multiple scripts in parallel:

pnpm run build & pnpm run test

Environment Variables

Set environment variables for scripts:

NODE_ENV=production pnpm run build

Best Practices

Script Naming

• Use descriptive names for scripts
• Use colons for related scripts (e.g., test:watch, test:coverage)
• Keep script names short but meaningful

Script Organization

• Group related scripts together in package.json
• Use comments to organize scripts:

  {
    "scripts": {
      // Development
      "dev": "tsdown --watch ./src",
      "build": "tsc && tsdown",
      
      // Testing
      "test": "vitest run",
      "test:watch": "vitest",
      
      // Code Quality
      "check": "ultracite check",
      "fix": "ultracite fix"
    }
  }

Script Documentation

Document your scripts in the README.md:

## Available Scripts

- `pnpm run dev` - Start development server
- `pnpm run build` - Build for production
- `pnpm run test` - Run tests
- `pnpm run check` - Check code quality

CI/CD Integration

Use scripts in your CI/CD pipeline:

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Run tests
  run: pnpm run test

- name: Check code quality
  run: pnpm run check

- name: Build package
  run: pnpm run build

Troubleshooting

Script Not Found

If you get "script not found" error:

• Check that the script name is spelled correctly
• Ensure the script is defined in package.json
• Check that you're in the correct directory

Script Fails

If a script fails:

• Check the error message for details
• Run the script with --help to see available options
• Check that all dependencies are installed
• Verify that the script has the correct permissions

Slow Script Execution

If scripts are running slowly:

• Check for memory issues
• Limit the scope of the script (e.g., specific files instead of all files)
• Use caching where possible
• Check for circular dependencies

Resources

• npm Scripts Documentation
• pnpm Scripts Documentation
• Package.json Scripts Guide