javascript-conventions

Apply these conventions when JavaScript, TypeScript, Node.js tooling, or package.json is the primary workstream.

Dispatch

| $ARGUMENTS | Action | |------------|--------| | Active (auto-invoked when JS/TS work is primary) | Apply the operator contract below | | Empty | Display the convention summary and routing guidance | | check | Verify tooling compliance only |

Reference File Index

| File | Purpose | When to Read | |------|---------|--------------| | references/tooling-contract.md | Required package-manager, command, CI, workspace, and package-root rules | Package commands, scripts, dependencies, lockfiles, or CI | | references/redirection-boundaries.md | When JS/TS conventions should yield to Python, shell, CI, or framework-specific skills | Mixed-language or ambiguous work | | references/edge-cases.md | Exception gates for npm/yarn, Corepack, generated apps, and migrations | Deviations from pnpm defaults | | references/typescript-patterns.md | TypeScript config, narrowing, type guards, unions, and type-test patterns | TypeScript code or tsconfig.json | | references/eslint-prettier.md | ESLint flat config, typed linting, and Prettier separation | Linting or formatting changes |

Operator Contract

Active

1. Apply this skill only when JS/TS files, Node tooling, or package.json are the primary surface of the task.
2. Read references/redirection-boundaries.md when JS/TS appears alongside Python, shell, CI, or framework-specific work.
3. Enforce the hard requirements in references/tooling-contract.md for package management, package-root selection, command execution, lockfiles, workspaces, and CI installs.
4. Check references/edge-cases.md before recommending npm, yarn, global package managers, Corepack assumptions, or lockfile migrations.
5. Read references/typescript-patterns.md for TypeScript config or type-safety changes.
6. Read references/eslint-prettier.md for linting, typed linting, or formatting changes.
7. Use guided preferences only when starting new work or when the repo does not already have a stronger local convention.

Empty / Help

1. Summarize the hard requirements: pnpm, packageManager, pnpm-lock.yaml, pnpm install --frozen-lockfile, pnpm exec, pnpm dlx, tsc --noEmit, eslint, and prettier.
2. Show the difference between hard requirements and guided preferences.
3. Point to the exact reference files for tooling, exceptions, TypeScript, lint/format, and mixed-language routing.

check

1. Verify JS/TS tooling compliance only; do not widen into implementation advice unless the user asks.
2. Report whether the project uses the expected package root, pnpm, packageManager, pnpm-lock.yaml, workspace config, scripts, tsconfig.json, ESLint flat config, and Prettier.
3. Flag npm/yarn/Corepack/legacy deviations and require the reason to match references/edge-cases.md.
4. Reject recommendations that replace repo-required tooling with npm install, npx, or ad hoc global binaries unless an exception is documented.

Hard Requirements

• Package manager: use pnpm for JS/TS package operations unless an exception is documented.
• Package manager pin: honor the nearest owning package.json and its packageManager field.
• Lockfile: commit pnpm-lock.yaml; never mix lockfiles in one package root without a migration plan.
• Install: use pnpm install; use pnpm install --frozen-lockfile in CI.
• Dependencies: use pnpm add <pkg> or pnpm add -D <pkg> from the owning package root.
• Local binaries: use pnpm exec <cmd>; use pnpm dlx <pkg> only for one-off registry execution.
• Scripts: use pnpm run <script> or pnpm --filter <pkg> run <script>.
• Type checking: use pnpm exec tsc --noEmit or the repo's package script.
• Linting: use ESLint flat config for new ESLint setup.
• Formatting: use Prettier for formatting and ESLint for code-quality rules.

Guided Preferences

When starting new JS/TS work and no stronger local constraint exists, prefer these tools. These are defaults, not absolute law; check references/edge-cases.md before overriding an established project choice.

| Purpose | Tool | Notes | |---------|------|-------| | Package manager | pnpm | Pin through packageManager when the package root owns package.json | | Bundler | vite or esbuild | Respect framework-owned builders first | | Linting | eslint | Use flat config for new setup | | Formatting | prettier | Keep formatting separate from linting | | Testing | vitest or framework-native runner | Prefer existing repo scripts | | Type checking | tsc --noEmit | Run through pnpm exec or package scripts |

TypeScript Type Safety

1. Prefer unknown over any; do not weaken established strictness to make code compile.
2. Prefer interface for object shapes and type for unions, intersections, and mapped types.
3. Use discriminated unions for state machines and tagged variants.
4. Use as const and satisfies to preserve literal inference without unsafe assertions.
5. Avoid type assertions (as); prefer type guards, assertion functions, and schema validation at boundaries.
6. Enable strict in new TypeScript projects and add stricter options when the repo can absorb them.
7. Test negative type behavior with @ts-expect-error or a type-test tool when type contracts are public.
8. See references/typescript-patterns.md for TSConfig, module-resolution, and narrowing patterns.

Critical Rules

1. Require pnpm for JS/TS dependency changes unless references/edge-cases.md justifies npm, yarn, or another manager.
2. Resolve the owning package root before running package commands; do not assume the repository root owns every JS/TS file.
3. Never mix pnpm-lock.yaml, package-lock.json, and yarn.lock in the same package root outside a dedicated migration.
4. Run CI installs with pnpm install --frozen-lockfile when a pnpm-lock.yaml is present.
5. Use pnpm exec for local binaries and pnpm dlx only for one-off packages fetched from the registry.
6. Do not assume Corepack is bundled with the active Node.js runtime; check references/edge-cases.md before recommending Corepack setup.
7. Keep Prettier responsible for formatting and ESLint responsible for code-quality rules.
8. Redirect mixed-language or non-JS-primary work through references/redirection-boundaries.md instead of force-fitting this skill onto the whole task.

Scaling Strategy

• Incidental JS/TS file in a broader non-JS task: enforce only the hard requirements that touch the JS/TS-owned surface, then route mixed-workflow questions through references/redirection-boundaries.md.
• JS/TS-primary feature or refactor work: apply the full operator contract, including tooling, TypeScript, linting, formatting, and test guidance where relevant.
• Repo-wide JS/TS tooling or migration work: use check, references/tooling-contract.md, and references/edge-cases.md to separate hard violations from documented transition paths.

Progressive Disclosure

• Do not load every reference by default.
• Read references/tooling-contract.md first for command, dependency, package-root, workspace, lockfile, or CI questions.
• Read references/redirection-boundaries.md when Python, shell, CI, infra, or framework-specific work is mixed into the request.
• Read references/edge-cases.md only when the task appears to require npm, yarn, Corepack setup, generated app scaffolding, or lockfile migration exceptions.
• Read references/typescript-patterns.md only when TypeScript code, tsconfig.json, public types, or type tests are active.
• Read references/eslint-prettier.md only when the task touches linting, typed linting, or formatting.

Scope Boundaries

IS for: JS/TS tooling conventions, Node package commands, dependency-management rules, TypeScript type-safety defaults, lint/format/test command guidance, and exception-aware repo guidance.

NOT for: Python conventions, shell conventions, CI pipeline design, framework architecture, backend-only implementation strategy, or broad frontend UX/design guidance.

Canonical terms (use these exactly):

• pnpm -- the required package manager for JS/TS package operations
• package root -- the nearest directory whose package.json owns the command or dependency
• packageManager -- the package.json field that pins the package manager and version
• pnpm-lock.yaml -- the canonical JS/TS lockfile for pnpm package roots
• workspace -- pnpm workspace declared by pnpm-workspace.yaml
• frozen-lockfile -- CI install mode that prevents lockfile mutation
• pnpm exec -- local project binary execution
• pnpm dlx -- one-off package execution from the registry

Validation Contract

Run from this skill directory before declaring changes complete:

python scripts/check.py
git diff --check

Completion criteria:

1. scripts/check.py exits 0.
2. git diff --check exits 0.
3. No portable-CLI violations remain under this skill directory.

After changing skill definitions, public descriptions, reference files, or eval behavior, invoke docs-steward if available.