action-setup/.claude/commands/quick-build.md

Quick: Build

Build the GitHub Action for distribution.

What This Does

Compiles TypeScript and bundles the action into a single distributable file using ncc.

Build Process

1. TypeScript Compilation

pnpm exec tsc

Compiles:

• src/**/*.ts → dist/tsc/**/*.js
• Generates type declarations
• Outputs to dist/tsc/ directory

Configuration: tsconfig.json

• Target: ES2022
• Module: Node16
• Strict mode enabled
• Source maps generated

2. Bundle with ncc

pnpm exec ncc build --minify --no-source-map-register --no-cache dist/tsc/index.js --out dist/

Creates:

• Single bundled file: dist/index.js
• All dependencies included
• Minified for distribution
• No source maps (cleaner output)

3. Copy Required Files

If needed:

cp ./node_modules/pnpm/dist/pnpm.cjs ./dist/pnpm.cjs
cp ./node_modules/pnpm/dist/worker.js ./dist/worker.js

Usage

Just ask:

• "Build the action"
• "Compile and bundle"
• "Create distribution"

Output

=== Building Action ===

[1/3] TypeScript compilation...
✓ Compiled successfully

[2/3] Bundling with ncc...
✓ Bundle created: dist/index.js (512 KB)

[3/3] Copying assets...
✓ pnpm.cjs copied
✓ worker.js copied

Build complete! ✓

Build Artifacts

After successful build:

dist/
  ├── index.js          # Main entry point (bundled)
  ├── pnpm.cjs          # Bundled pnpm (if needed)
  ├── worker.js         # pnpm worker (if needed)
  └── tsc/              # TypeScript output
      ├── index.js
      ├── index.d.ts
      └── ...

Verification

After building, verify:

# Check file exists
ls -lh dist/index.js

# Check size
du -h dist/index.js

# Test execution (should not error immediately)
node dist/index.js 2>&1 | head -5

Build Scripts

From package.json:

{
  "scripts": {
    "build:ncc": "ncc build --minify --no-source-map-register --no-cache dist/tsc/index.js --out dist/",
    "build": "tsc && pnpm run build:ncc"
  }
}

Clean Build

For a completely fresh build:

# Remove previous build
rm -rf dist/

# Rebuild
pnpm run build

Common Issues

TypeScript Errors

Problem: Build fails with type errors

Solution:

# Check errors
pnpm exec tsc --noEmit

# Fix type issues
# Then rebuild

Missing Dependencies

Problem: Module not found errors

Solution:

# Install dependencies
pnpm install

# Rebuild
pnpm run build

ncc Bundle Errors

Problem: Bundle fails or is too large

Solution:

# Check ncc version
pnpm list @vercel/ncc

# Update if needed
pnpm update @vercel/ncc

# Try without minification
pnpm exec ncc build dist/tsc/index.js --out dist/

Large Bundle Size

Problem: dist/index.js is very large (>5MB)

Check:

• Unnecessary dependencies included
• Large data files bundled
• Unused code not tree-shaken

Solution:

• Review dependencies in package.json
• Use --external for runtime dependencies
• Remove unused imports

Build Optimization

Minimize Bundle Size

# Use minification
ncc build --minify ...

# External dependencies (if available at runtime)
ncc build --external dependency-name ...

# Analyze bundle
ncc build --stats-out stats.json ...

Faster Builds

# Skip TypeScript if no changes
pnpm run build:ncc

# Use incremental compilation (tsconfig.json)
"incremental": true

Distribution

After building:

1. Commit dist files

   git add dist/
   git commit -m "build: update distribution"
   

2. Verify in CI

   • Push changes
   • Ensure CI passes
   • Test action execution

3. Tag release

   git tag v1.2.3
   git push origin v1.2.3
   

GitHub Actions Runtime

The built action runs as:

runs:
  using: node20        # Node.js 20 runtime
  main: dist/index.js  # Entry point
  post: dist/index.js  # Post-action cleanup

Node.js 20 features available:

• Fetch API
• ES2022 features
• Native test runner
• Performance improvements

Build Checklist

Before considering build complete:

• TypeScript compiles without errors
• ncc bundle succeeds
• dist/index.js created
• Bundle size reasonable (<1MB preferred)
• Required assets copied
• No errors when loading bundle
• Git status clean (or dist committed)

Watch Mode

For development (if needed):

# Watch TypeScript files
pnpm exec tsc --watch

# In another terminal, rebuild when TS changes
# (requires file watcher script)

Integration with Other Commands

After Building

Run tests:

quick:test

Run quality checks:

quick:check

Before Building

Fix code issues:

quick:fix

Implementation

This command executes:

#!/bin/bash
set -e

echo "=== Building Action ==="
echo ""

echo "[1/3] TypeScript compilation..."
if pnpm exec tsc; then
  echo "✓ Compiled successfully"
else
  echo "✗ TypeScript compilation failed"
  exit 1
fi

echo ""
echo "[2/3] Bundling with ncc..."
if pnpm run build:ncc; then
  SIZE=$(du -h dist/index.js | cut -f1)
  echo "✓ Bundle created: dist/index.js ($SIZE)"
else
  echo "✗ Bundling failed"
  exit 1
fi

echo ""
echo "[3/3] Verifying build..."
if [ -f dist/index.js ]; then
  echo "✓ Build artifacts verified"
else
  echo "✗ dist/index.js not found"
  exit 1
fi

echo ""
echo "Build complete! ✓"