Troubleshooting

Common issues and solutions when working with this template.

Installation Issues

pnpm Not Found

Symptom:

pnpm: command not found

Solution:

Enable Corepack (included with Node.js 16.13+):

corepack enable

Or install pnpm globally:

npm install -g pnpm

Wrong pnpm Version

Symptom:

ERR_PNPM_UNSUPPORTED_ENGINE  Unsupported pnpm version

Solution:

The template uses a specific pnpm version defined in package.json:

{
  "packageManager": "pnpm@9.0.0"
}

Enable Corepack to use the correct version automatically:

corepack enable
corepack prepare

Node Version Error

Symptom:

error your-package@1.0.0: The engine "node" is incompatible

Solution:

This template requires Node.js 20+. Check your version:

node --version

Use nvm or fnm to install Node.js 20:

# With nvm
nvm install 20
nvm use 20

# With fnm
fnm install 20
fnm use 20

Lockfile Out of Sync

Symptom:

ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile"

Solution:

Update the lockfile:

pnpm install

Then commit the updated pnpm-lock.yaml.

Build Issues

TypeScript Errors in Build

Symptom:

✘ [ERROR] Could not resolve "..."

Possible causes:

1. Missing dependency — Install the package
2. Wrong import path — Check relative paths
3. tsconfig issue — Verify paths configuration

Debug:

# Check types first
pnpm run typecheck

# Then build
pnpm run build

tsup Build Fails

Symptom:

Build failed with X error(s)

Common fixes:

1. Check tsup.config.ts entry points exist
2. Ensure source files have no syntax errors
3. Verify all imports resolve

Verbose output:

pnpm tsup --debug

No Output in dist/

Symptom: Build succeeds but dist/ is empty or missing files

Check:

1. Verify entry points in tsup.config.ts:

   entry: ["src/index.ts"]; // Must match your source

2. Ensure source files exist at those paths

3. Check for clean: true running at unexpected times

Lint Issues

ESLint Flat Config Error

Symptom:

ESLint couldn't find a configuration file

Solution:

This template uses ESLint 9 flat config. Ensure you're using ESLint 9+:

pnpm eslint --version

The config file is eslint.config.mjs (not .eslintrc).

Prettier Conflicts

Symptom: ESLint and Prettier disagree on formatting

Solution:

This template uses eslint-config-prettier to disable conflicting rules. If you still see conflicts:

1. Run Prettier first, then ESLint:

   pnpm format
   pnpm lint --fix

2. Or use the combined command:

   pnpm lint:staged

knip False Positives

Symptom: knip reports used code as unused

Common cases:

1. Dynamic imports — knip can't analyze them
2. Config files — Some patterns aren't detected
3. Scripts — Files only used in npm scripts

Solution:

Add to knip.json:

{
  "ignore": ["scripts/**", "docs/.vitepress/**"],
  "ignoreDependencies": ["some-dev-dependency"]
}

publint Errors

Symptom:

npm WARN publint

Common issues:

Error	Fix
Missing exports	Add exports field to package.json
Wrong types path	Point to correct .d.ts file
Missing files entry	Add built files to files array

Debug:

pnpm publint

This shows detailed explanations for each issue.

Test Issues

Tests Not Found

Symptom:

No test files found

Check:

1. Test files match the pattern in vitest.config.ts:

   include: ["**/*.{test,spec}.{js,ts}"];

2. Test files are not excluded:

   exclude: ["node_modules", "dist"];

Import Errors in Tests

Symptom:

Cannot find module '../src/...'

Solution:

Use the configured path aliases or relative imports:

// If using aliases
import { hello } from "@/index";

// Or relative paths
import { hello } from "../src/index";

Coverage Not Generating

Symptom: Tests pass but no coverage report

Solution:

Run tests with coverage flag:

pnpm test --coverage

Or use the coverage script:

pnpm run test:coverage

Git Hooks Issues

Hooks Not Running

Symptom: Commit succeeds without running lint-staged

Possible causes:

1. Husky not installed — Run:

   pnpm exec husky install

2. Git version too old — Husky requires Git 2.9+

   git --version

3. Hooks bypassed — Someone used --no-verify

lint-staged Failing

Symptom:

✖ lint-staged failed

Debug:

# Run lint-staged manually with verbose output
pnpm lint-staged --verbose

Common fixes:

1. Fix the linting errors shown
2. Stage the fixes: git add .
3. Try the commit again

Permission Denied on Hook

Symptom:

.husky/pre-commit: Permission denied

Solution (Unix/Mac):

chmod +x .husky/pre-commit
chmod +x .husky/pre-push

Solution (Windows):

This usually happens in WSL. Try:

git config core.filemode false

Documentation Issues

VitePress Build Fails

Symptom:

[vitepress] Error when building

Common causes:

1. Broken links — Check for dead internal links
2. Invalid frontmatter — YAML syntax errors
3. Missing files — Referenced images/files don't exist

Debug:

pnpm docs:dev

Development mode shows more detailed errors.

API Docs Not Updating

Symptom: Changed source code but API docs are outdated

Solution:

Regenerate API documentation:

pnpm run docs:api

TypeDoc needs to run again after source changes.

404 on GitHub Pages

Symptom: Docs deploy succeeds but pages show 404

Causes:

1. Wrong base path — Check docs/.vitepress/config.mts:

   base: "/your-repo-name/";

2. Pages not enabled — Go to Settings → Pages → set Source to "GitHub Actions"

3. First deploy — Wait a few minutes, then hard refresh

See GitHub Pages for detailed setup.

Release Issues

Changeset Not Found

Symptom:

No changesets found

Solution:

Create a changeset before committing:

pnpm changeset

Version PR Not Created

Symptom: Pushed changesets but no Version PR appears

Check:

1. Release workflow ran (Actions tab)
2. Workflow has pull-requests: write permission
3. GITHUB_TOKEN has correct scope

npm Publish Fails

Symptom:

npm ERR! 403 Forbidden

Causes:

1. No NPM_TOKEN — Add it to repository secrets
2. Token expired — Generate a new one
3. Name taken — Package name already exists on npm
4. No publish access — Token needs write permission

Check npm token:

npm whoami --registry https://registry.npmjs.org/

Wrong Version Published

Symptom: Published version doesn't match expected

Check:

1. Changeset specified correct bump (patch/minor/major)
2. No manual package.json version edits
3. Version PR was reviewed before merge

IDE Issues

TypeScript Errors Not Matching

Symptom: VS Code shows different errors than pnpm typecheck

Solution:

1. Restart TypeScript server:

   • Cmd+Shift+P → "TypeScript: Restart TS Server"

2. Check VS Code uses workspace TypeScript:

   • Cmd+Shift+P → "TypeScript: Select TypeScript Version"
   • Choose "Use Workspace Version"

ESLint Not Working in VS Code

Symptom: No ESLint errors shown in editor

Solution:

1. Install ESLint extension

2. Enable flat config support (VS Code settings):

   {
     "eslint.experimental.useFlatConfig": true
   }

3. Reload VS Code window

Getting More Help

If your issue isn't covered here:

1. Search existing issues — GitHub Issues
2. Check tool documentation — Each tool has its own docs
3. Create a minimal reproduction — Helps identify the problem
4. Open an issue — Include error messages and steps to reproduce

Useful Debug Commands

# Check all versions
node --version
pnpm --version
pnpm eslint --version
pnpm tsc --version

# Verbose output
pnpm install --reporter=ndjson
pnpm tsup --debug
pnpm lint-staged --verbose
pnpm vitest --reporter=verbose

# Check package.json validity
pnpm pack --dry-run
pnpm publint

# Clear caches
rm -rf node_modules
rm -rf dist
pnpm store prune
pnpm install