writing-clean-javascript
/writing-clean-javascript
Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.
- Author
- eldrego ↗
- Repository
- claude-dev-workflow ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/lint.sh, scripts/test-config.sh
What it does and when to use it
Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.
Original author description
Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.
How it works
- Workflow
- Writing tests
- Core rules
- Self-review checklist
SKILL.md preview
---
name: writing-clean-javascript
description: Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.
---
# Writing clean JavaScript
Apply these conventions to all JavaScript/TypeScript you write or modify.
They are opinionated; follow them over general defaults.
## Workflow
1. Before writing, check the project's existing style: Biome config
(`biome.json`/`biome.jsonc`), ESLint config, Prettier config, `tsconfig.json`,
and neighboring files. If the project's config conflicts with a rule below,
the project wins — consistency within a codebase matters more than any
individual rule.
2. Write the code following the core rules below.
3. Self-review against the checklist at the end of this file.
4. Run the linters on the files you changed:
`bash ${CLAUDE_SKILL_DIR}/scripts/lint.sh <changed files>`
It runs Biome and/or ESLint, whichever the project is configured for. Fix what
it reports and re-run until it is clean.
When refactoring, change structure without changing behavior. If behavior must
change, say so explicitly. Keep refactors scoped to what was asked.
## Writing tests
Before writing or editing tests, run from the project root:
`bash ${CLAUDE_SKILL_DIR}/scripts/test-config.sh`
It prints the Vitest/Jest/Playwright config and global setup files. Anything
configured there applies to every test, so **do not repeat it inside test
files** — duplicated setup drifts out of sync and hides what a test is
actually about. In particular, don't repeat:
- Mock resets (`clearMocks`, `mockReset`, `restoreMocks`) → no
`afterEach(() => vi.clearAllMocks())` / `jest.restoreAllMocks()`.
- Setup-file work: `@testing-library/jest-dom` imports, MSW
`server.listen/resetHandlers/close`, RTL `cleanup()`, polyfills.
- `environment` / `testEnvironment` → no per-file `@vitest-environment` or
`@jest-environment` docblocks that match the default.
- `globals: true` → follow the existing tests on whether to import
`describe/it/expect`; don't mix styles.
- `testTimeout`, fake-timer config, `unstubGlobals`/`unstubEnvs`.
- Path aliases (`resolve.alias`, `moduleNameMapper`) → use the alias, not long
relative imports.
- Playwright `use.baseURL` → `page.goto('/path')`, not full URLs;
`storageState`/global setup auth → don't log in inside each test; don't
override `retries`, `timeout`, or `viewport` per test without a reason.
Only add per-test setup for things that are genuinely specific to that test.
See `references/conventions.md` section 7 for test style rules.
## Core rules
**Variables**: `const` by default; `let` only when reassigned; never `var`.
**Control flow**: Use guard clauses and early returns instead of nested
`if/else`. Max nesting depth of 2 — deeper nesting hides the main path. No
nested ternaries; readers misparse them.
**Functions**: One job per function, roughly 30 lines max. More than 3
parameters → take a single options object so call sites are self-describing.
Prefer pure functions; push side effects (I/O, DOM, network) to the edges.
**Async**: `async/await` over `.then()` chains. Never leave a promise floating —
await it or handle it explicitly. Run independent work with `Promise.all`
instead of sequential awaits.
**Errors**: Never write an empty `catch`. Either handle the error meaningfully,
add context and rethrow (`throw new Error('Failed to load user', { cause: err })`),
or let it propagate. Throw `Error` objects, never strings.
**Naming**: Booleans read as questions (`isActive`, `hasAccess`, `canEdit`).
Functions are verbs (`fetchUsers`, `formatPrice`). Avoid abbreviations except
widely known ones (`id`, `url`, `db`). Magic numbers and strings become named
`UPPER_SNAKE_CASE` constants.
**Data**: Don't mutate function arguments or shared state; return new values
(spread, `map`, `filter`, `structuredClone`). Use optional chaining (`?.`) and
nullish coalescing (`??`) instead of long `&&` chains or `||` defaults that
break on `0` and `''`.
**Modules**: Named exports, not default exports — they keep names consistent
across imports and make refactoring safer. One main concern per file.
**Comments**: Explain *why*, not *what*. Delete commented-out code; git keeps
history.
For detailed rules on arrays, React, TypeScript, Node/Express, and testing,
read `references/conventions.md`. For before/after examples of these rules,
read `references/examples.md`. For design-level problems to avoid (duplicated
code, feature envy, speculative generality, prop drilling, and others), read
`references/code-smells.md` — these are judgement calls, not firm rules.
## Self-review checklist
- [ ] No `var`; `let` only where reassigned
- [ ] No nesting deeper than 2; no nested ternaries
- [ ] No function over ~30 lines or with more than 3 positional parameters
- [ ] No floating promises; independent awaits use `Promise.all`
- [ ] No empty `catch` blocks; only `Error` objects thrown
- [ ] No magic numbers/strings; names are descriptive
- [ ] No mutated arguments
- [ ] Named exports only
- [ ] Tests don't repeat anything from the test config or setup files
- [ ] Linters pass (or none were configured and you said so)
Files in this package (6)
- SKILL.md 5 KB
- references/code-smells.md 5 KB
- references/conventions.md 4 KB
- references/examples.md 3 KB
- scripts/lint.sh 2 KB
- scripts/test-config.sh 2 KB
Versions
The database has no other skills named writing-clean-javascript.
Database snapshot: 13.11.2026 · package version a92eee286e9c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100sota-javascript-typescript
State-of-the-art JavaScript and TypeScript engineering (2026) for both writing and auditing code. Covers strict TypeScript configuration and type design, language idioms and pitfalls, async patterns, Node.js backends, JS/TS-specific security (XSS, prototype pollution, supply… - 100javascript-testing
Write and run JavaScript/TypeScript tests using Vitest or Jest with mocking, component testing, and coverage. Use when writing JS/TS tests, testing Svelte/React components, or setting up test configuration. - 100typescript
Idiomatic programming style, patterns, and conventions for TypeScript and JavaScript development. Trigger when: - Writing, refactoring, reviewing, or debugging TypeScript or JavaScript code. - Files matching the patterns **/*.ts, **/*.tsx, **/*.js, **/*.jsx, package.json are in… - 100js-google
JavaScript style and best practices based on Google's official JavaScript Style Guide. This skill should be used when writing, reviewing, or refactoring JavaScript code to ensure consistent style and prevent common bugs. Triggers on tasks involving JavaScript, ES6, modules,… - 100javascript-typescript
Professional JavaScript and TypeScript development skill covering modern ES6+, TypeScript, Node.js, Express, React, testing frameworks, and best practices. Use this skill when developing JavaScript/TypeScript applications, building React/Node.js projects, implementing RESTful… - 100javascript
Guides JavaScript and TypeScript development with modern tooling and patterns. ALWAYS trigger on "typescript", "javascript", "tsconfig", "eslint", "prettier", "vitest", "jest", "react", "node.js", "express", "npm", "package.json", "type error", "ts error", "js project setup",…