javascript-conventions

javascript-conventions 439 words MIT v1.0.0 wyattowalsh Custom

JS/TS tooling conventions. Enforce pnpm. Use when working on JS/TS files or package.json. NOT for Python, backend-only, or shell scripts.

Quick Start

Install:

npx skills add wyattowalsh/agents/skills/javascript-conventions -g

Use: /javascript-conventions

Works with Claude Code, Gemini CLI, and other agentskills.io-compatible agents.

Source & provenance

This page is generated from the repository file skills/javascript-conventions/SKILL.md by wagents docs generate.

What It Does

Apply these conventions when working on JavaScript or Node.js files or projects.

Note

This is an auto-invoke skill — it activates automatically when the agent detects relevant context. It is not visible in the / slash command menu.

Modes

$ARGUMENTS	Action
Active (auto-invoked when working on JS/TS files)	Apply all conventions below
Empty	Display convention summary
check	Verify package manager compliance only

Package Management

• Use pnpm for all Node.js package management
• Do not use npm or yarn unless the project explicitly requires them
• Commands: pnpm install, pnpm add <pkg>, pnpm run <script>, pnpm exec <cmd>
• Always commit pnpm-lock.yaml — never .gitignore it
• Run pnpm install --frozen-lockfile in CI environments

Monorepo Conventions

• Use pnpm workspaces for multi-package repositories
• Define workspaces in pnpm-workspace.yaml at the repo root
• Use pnpm -r or pnpm --filter <pkg> for targeted operations
• Hoist shared dependencies to the root where possible

Lockfile Handling

• Commit lockfiles to version control
• Use --frozen-lockfile in CI to prevent drift
• When migrating from npm/yarn, delete the old lockfile and run pnpm import or pnpm install

Tooling Preferences

Purpose	Tool
Package manager	pnpm
Bundler	vite or esbuild
Linting	eslint
Formatting	prettier
Testing	vitest or framework-native runner
Type checking	tsc --noEmit

Critical Rules

1. Always use pnpm unless an existing lockfile or CI config mandates otherwise
2. Never mix package managers in the same project (no npm install alongside pnpm)
3. Commit pnpm-lock.yaml to version control in every project
4. Run pnpm install --frozen-lockfile in CI — never allow lockfile mutation
5. Check references/edge-cases.md before breaking any convention
6. Use pnpm exec instead of npx for running local binaries

Canonical terms (use these exactly):

• pnpm — the required package manager (not npm, not yarn)
• lockfile — pnpm-lock.yaml specifically
• workspace — pnpm workspace for monorepo packages
• frozen-lockfile — CI mode that prevents lockfile changes

General

Field	Value
Name	javascript-conventions
License	MIT
Version	1.0.0
Author	wyattowalsh

Claude Code

Field	Value
User Invocable	No

Related Skills

python-conventions Python tooling conventions. Enforce uv, ty. Use when working on .py files or pyproject.toml. NOT for JS/TS or shell scripts.

View Full SKILL.md

SKILL.md

---
name: javascript-conventions
description: >-
  JS/TS tooling conventions. Enforce pnpm. Use when working on JS/TS files
  or package.json. NOT for Python, backend-only, or shell scripts.
user-invocable: false
disable-model-invocation: false
license: MIT
metadata:
  author: wyattowalsh
  version: "1.0.0"
---

# JavaScript/Node.js Conventions

Apply these conventions when working on JavaScript or Node.js files or projects.

## Dispatch

| $ARGUMENTS | Action |
|------------|--------|
| Active (auto-invoked when working on JS/TS files) | Apply all conventions below |
| Empty | Display convention summary |
| `check` | Verify package manager compliance only |

## References

| File | Purpose |
|------|---------|
| `references/edge-cases.md` | Repo-specific exceptions and edge cases |
| `references/typescript-patterns.md` | Discriminated unions, type guards, utility types |

## Package Management

- Use `pnpm` for all Node.js package management
- Do not use `npm` or `yarn` unless the project explicitly requires them
- Commands: `pnpm install`, `pnpm add <pkg>`, `pnpm run <script>`, `pnpm exec <cmd>`
- Always commit `pnpm-lock.yaml` -- never `.gitignore` it
- Run `pnpm install --frozen-lockfile` in CI environments

### Monorepo Conventions

- Use `pnpm` workspaces for multi-package repositories
- Define workspaces in `pnpm-workspace.yaml` at the repo root
- Use `pnpm -r` or `pnpm --filter <pkg>` for targeted operations
- Hoist shared dependencies to the root where possible

### Lockfile Handling

- Commit lockfiles to version control
- Use `--frozen-lockfile` in CI to prevent drift
- When migrating from npm/yarn, delete the old lockfile and run `pnpm import` or `pnpm install`

## Tooling Preferences

| Purpose | Tool |
|---------|------|
| Package manager | `pnpm` |
| Bundler | `vite` or `esbuild` |
| Linting | `eslint` |
| Formatting | `prettier` |
| Testing | `vitest` or framework-native runner |
| Type checking | `tsc --noEmit` |

## TypeScript Type Safety

1. Prefer `unknown` over `any`; enforce via `noImplicitAny` in `tsconfig.json`
2. Prefer `interface` for object shapes; use `type` for unions and intersections
3. Use discriminated unions for state machines and tagged types
4. Use `as const` assertions to preserve literal types
5. Avoid type assertions (`as`); prefer type guards and `satisfies`
6. Enable all `strict` compiler options in `tsconfig.json`
7. Test types with `@ts-expect-error` or `tsd`
8. See `references/typescript-patterns.md` for discriminated union and utility type patterns

## Critical Rules

1. Always use `pnpm` unless an existing lockfile or CI config mandates otherwise
2. Never mix package managers in the same project (no `npm install` alongside `pnpm`)
3. Commit `pnpm-lock.yaml` to version control in every project
4. Run `pnpm install --frozen-lockfile` in CI — never allow lockfile mutation
5. Check `references/edge-cases.md` before breaking any convention
6. Use `pnpm exec` instead of `npx` for running local binaries

**Canonical terms** (use these exactly):
- `pnpm` -- the required package manager (not npm, not yarn)
- `lockfile` -- `pnpm-lock.yaml` specifically
- `workspace` -- pnpm workspace for monorepo packages
- `frozen-lockfile` -- CI mode that prevents lockfile changes

Download from GitHub

Resources

All Skills Browse the full skill catalog.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

---

View source on GitHub