javascript-conventions

---
name: "javascript-conventions"
description: "Apply these conventions when JavaScript, TypeScript, Node.js tooling, or package.json is the primary workstream."
license: "MIT"
---

# JavaScript/TypeScript 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:

```bash
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.