javascript-engineering

javascript engineering guidance for node.js, browser apps, clis, and packages. use when .js, .jsx, .mjs, .cjs, bundler config, or package contract behavior dominate the task and a typescript-first pack would be too type-system-centric.

JavaScript Engineering

Use this skill when the repository is JavaScript-first or the task depends more on runtime behavior, packaging, module format, or toolchain quirks than on a TypeScript type system.

Activation

  • JavaScript files, Node runtime behavior, browser bundling, or package publishing dominate the task
  • the repo uses .js, .jsx, .mjs, .cjs, or mixed module formats
  • package exports, imports, CLI behavior, or browser and server boundaries are central to the change

Load Order

  • rules/common/README.md
  • rules/common/coding-style.md
  • rules/common/patterns.md
  • rules/common/testing.md
  • rules/common/security.md
  • skills/javascript-engineering/references/
  • knowledge-bases/seeded/typescript/docs/frameworks.md when the repository shares the wider Node, React, or Vite ecosystem

Execution Contract

  1. map entrypoints, scripts, package manager, module system, and bundler behavior before editing code
  2. identify whether the edited code runs in Node, the browser, SSR, workers, or multiple runtimes
  3. preserve public package contracts unless the task explicitly authorizes a breaking change
  4. prefer plain, explicit JavaScript and JSDoc-backed contracts over hidden conventions
  5. validate the actual runtime path and packaging behavior, not just lint output

Outputs

  • touched-file plan grouped by package or runtime boundary
  • implementation or debugging summary with the exact module or packaging seam that changed
  • validation path with lint, test, smoke, and package-contract checks
  • compatibility note when exports, entrypoints, or environment assumptions changed

Validation

  • run the repo's preferred test, lint, and smoke commands first
  • confirm Node version, package manager, and lockfile assumptions before touching dependencies or module format
  • inspect package.json type, main, module, exports, and imports when resolution is part of the bug
  • verify browser, SSR, and Node boundaries explicitly when code is shared across environments

Escalation

  • escalate when the repo mixes incompatible ESM, CommonJS, bundler, or runtime assumptions
  • escalate when changing exports would break undocumented consumer entrypoints
  • escalate when package publishing, CLI behavior, or deployment constraints are unclear

Supplemental Engineering References

  • skills/javascript-engineering/references/repo-exploration.md
  • skills/javascript-engineering/references/output-templates.md
  • skills/javascript-engineering/references/agent-patterns.md
  • skills/javascript-engineering/references/debugging-playbook.md
  • skills/javascript-engineering/references/ecosystem-guide.md
  • skills/javascript-engineering/references/node-service-patterns.md
  • skills/javascript-engineering/references/browser-and-bundler-patterns.md
  • skills/javascript-engineering/references/package-contracts.md
  • skills/javascript-engineering/references/testing-and-debugging.md
  • skills/javascript-engineering/references/examples.md