general-pnpm-scripts

name	general-pnpm-scripts
description	Use when running any PNPM custom script command to verify it exists first

PNPM Script Verification

This skill ensures you ALWAYS verify custom PNPM scripts exist in package.json before running them. This prevents "command not found" errors and ensures you understand what each script does.

When to Use This Skill

Use this skill BEFORE running ANY custom PNPM script. This includes:

• Development commands (dev, dev:f, dev:w, dev:ef)
• Build commands (build, build:f)
• Type checking (check, check:fe)
• Supabase commands (sb:dev:start, sb:dev:reset, sb:dev:types, etc.)
• Deployment commands (w:deploy:staging, w:deploy:production)
• Any other custom script in package.json

Note: This skill applies to custom scripts only, not native PNPM commands like pnpm install, pnpm add, etc.

Workspace Structure

This is a PNPM monorepo:

D:\Coding\lightcraft\lightcraft\
├── package.json                          # Root workspace
├── spark/frontend/my-vite-app/package.json   # Frontend workspace
└── spark/cloudflare/workers/file-delivery/package.json   # Worker workspace

Workspace filters:

• vite → spark/frontend/my-vite-app
• worker → spark/cloudflare/workers/file-delivery

Verification Workflow (CRITICAL)

ALWAYS follow these steps before running ANY custom PNPM script:

Step 1: Determine Which Package.json to Check

• Running from root directory: Check root package.json
• Running pnpm --filter vite [script]: Check frontend package.json
• Running pnpm --filter worker [script]: Check worker package.json
• Running from workspace directory: Check that workspace's package.json

Step 2: Read the Package.json

Use the Read tool to open the relevant package.json and find the "scripts" section.

Step 3: Verify the Script Exists

Check if the exact script name exists in the "scripts" object.

Common mistake: Looking for sb:dev:reset in workspace package.json when it's only in root.

Step 4: Understand What the Script Does

Read the script definition to understand:

• What commands it runs
• Whether it delegates to another workspace
• What side effects it has

Example:

"sb:dev:reset": "cd spark/frontend/my-vite-app && pnpm sb:dev:reset"

This root script changes directory to frontend workspace and runs the frontend's sb:dev:reset script.

Step 5: Run the Correct Command

Use the correct command from the correct location.

Script Naming Patterns

Pattern	Purpose	Location
dev, build, check	Main commands	Root (delegates to workspaces)
dev:fe, build:fe, check:fe	Frontend-specific	Root (uses --filter vite)
dev:w, w:deploy:*	Worker-specific	Root
sb:*	Supabase commands	Both root and frontend
Bare commands	Direct execution	Workspace package.json

Root vs Workspace Scripts

Root Scripts (Delegation Pattern):

// Root package.json
{
    "scripts": {
        "sb:dev:start": "cd spark/frontend/my-vite-app && pnpm sb:dev:start",
        "dev:f": "pnpm --filter vite dev"
    }
}

These scripts change directory or use --filter to run workspace scripts.

Workspace Scripts (Direct Execution):

// Frontend package.json
{
    "scripts": {
        "sb:dev:start": "supabase start",
        "dev": "vite"
    }
}

These scripts execute actual commands, not delegation.

Workspace Filtering with pnpm --filter

When using pnpm --filter, you're running scripts from a workspace's package.json:

# This runs the "dev" script from frontend package.json
pnpm --filter vite dev

# NOT from root package.json

Common Anti-Patterns to Avoid

1. ❌ Assuming a script exists without checking
2. ❌ Looking in wrong package.json (checking frontend for root-only script)
3. ❌ Using npm instead of pnpm (this is a pnpm workspace)
4. ❌ Not understanding script delegation (must check BOTH package.json files)

Best Practices

1. ✅ Always read package.json first
2. ✅ Verify the exact script name (typos are common)
3. ✅ Understand what the script does before running
4. ✅ Check delegation chains (root → workspace)
5. ✅ Use correct workspace filter when needed
6. ✅ Run from correct directory or use absolute paths

Example Workflow

User asks: "Run the Supabase reset command"

Your process:

1. Identify the likely script: sb:dev:reset
2. Read root package.json to verify
3. Find: "sb:dev:reset": "cd spark/frontend/my-vite-app && pnpm sb:dev:reset"
4. Understand: This delegates to frontend workspace
5. Read frontend package.json to verify the target exists
6. Find: "sb:dev:reset": "supabase db reset --local"
7. Run: pnpm sb:dev:reset from root (or the appropriate location)

Key: You verified the script exists in BOTH locations (root and frontend) before running.

For detailed examples: .claude/skills/general-pnpm-scripts/examples.md