Skip to content

docs(nodejs): steer agents to the right module system in code snippets#18

Open
mmanciop wants to merge 1 commit into
mainfrom
docs/nodejs-module-system-guidance
Open

docs(nodejs): steer agents to the right module system in code snippets#18
mmanciop wants to merge 1 commit into
mainfrom
docs/nodejs-module-system-guidance

Conversation

@mmanciop

@mmanciop mmanciop commented Jul 7, 2026

Copy link
Copy Markdown
Member

Summary

Node.js snippets across the otel-instrumentation skill mixed import and require without telling agents how to pick between them. An agent copying snippets into a project could produce SyntaxError: Cannot use import statement outside a module (ESM syntax in a CJS file) or ReferenceError: require is not defined in ES module scope (the reverse).

  • Add a Module system in code snippets subsection to rules/sdks/nodejs.md with:
    • Detection rules (file extension, nearest package.json "type", surrounding code style, new-file default)
    • Explicit statement that all JavaScript snippets in the file default to ESM import
    • Translation table for importrequire, default/named/namespace forms, and exportmodule.exports
    • Note that TypeScript source always uses import regardless of emit target
  • Normalize the pg requestHook snippet in nodejs.md from require to import so all snippets in the file share one style.
  • Switch the Node.js intro snippet in SKILL.md from require to import to match the ESM default.

Test plan

  • Read rules/sdks/nodejs.md end-to-end and confirm no code snippet uses require( outside the translation table.
  • Confirm SKILL.md intro snippet uses import.
  • Verify the detection rules cover: .mjs/.cjs extensions, package.json "type", existing surrounding syntax, and new-file default.

🤖 Generated with Claude Code

Node.js snippets across the otel-instrumentation skill mixed `import` and
`require` without telling agents how to pick between them. An agent copying
snippets into a project could produce `SyntaxError: Cannot use import
statement outside a module` (ESM syntax in a CJS file) or the reverse.

- Add a "Module system in code snippets" subsection to nodejs.md with
  detection rules (file extension, package.json `"type"`, surrounding code),
  an explicit ESM default for the file's snippets, and a translation table.
- Normalize the `pg` `requestHook` snippet in nodejs.md to `import` so the
  file is internally consistent.
- Switch the Node.js intro snippet in SKILL.md from `require` to `import`
  to match the ESM default.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant