feat(create-module): lint server-runtime-unavailable APIs in server files

[romain-pm]

Closes #703 — part of EPIC #698 (developer experience).

Problem

The server runtime is GraalJS: microtask-only, no timers, no fetch, no Node built-ins. Today you discover that at runtime, on the first call — {"error":"setTimeout is not defined"} — and only for the one API you happened to reach first. It is the first wall a developer coming from the JS ecosystem hits.

Change

ESLint core rules (no-restricted-globals, no-restricted-imports) scoped to **/*.server.{js,jsx,ts,tsx} and **/*.action.{js,ts}, shipped in the scaffolded config and dogfooded on the samples and the test module. No new plugin, no new dependency. Client files are untouched — they run in a browser, where all of this exists.

Each message points at a new reference page, docs/3-reference/3-server-runtime-boundary, documenting what is available, what is not, and why.

How the restricted list was established

Rather than assuming, the restricted names were probed against the exact GraalJS version the engine pins (23.0.5), in a context built with the same options as GraalVMEngine.ContextPoolFactory#create, evaluating typeof <name> for ~80 names. The 40 restricted globals are those the probe reported undefined, grouped as timers/scheduling, network & async I/O, Node.js, browser, and web-platform extras. node:* and bare Node built-in imports both throw in the probe (Unsupported URI scheme node / Error reading: fs), hence the import patterns.

Deliberately not restricted:

• console — present, used throughout the samples;
• TextEncoder / TextDecoder — absent from raw GraalJS but polyfilled by the engine (fast-text-encoding in src/server/index.ts), so they work at runtime;
• Promise, Intl, Atomics, WeakRef, all ECMAScript builtins — present;
• a dozen further absent names (Worker, ReadableStream, …) documented as equally unavailable but left out of the rule, to keep it to what people actually reach for.

One real violation found

Repo-wide, exactly one: vite-plugin/fixtures/src/process.env.server.tsx reads process.env.NODE_ENV — the one legitimate use, since the Vite plugin statically replaces that expression at build time. It gets a targeted eslint-disable-next-line with the reason, and the exception is documented on the reference page. The rule was not weakened.

Verification

node --test → 4 tests: a server file using setTimeout, fetch, process.env and both Node import forms fails with both rule IDs and messages ending in the docs URL; a clean server file using console + TextEncoder passes; a client file using fetch, AbortController, window and document passes. eslint --print-config independently confirms the scoping (40 restricted globals on a server file, none on a client file). Repo yarn lint is green, and the vite-plugin snapshot test passes after regenerating the one affected map.

Not done

The build-time scan for transitive references (item 2 of the issue) is out of scope by design: the rule is syntactic and does not follow imports, which the docs page states.

Authored with Claude Code and reviewed before pushing; the test and lint output above was reproduced independently.

[github-actions]

📝 Documentation Guidelines

Thank you for contributing to our documentation! To ensure your contributions meet our standards, please review these resources:

• How to push markdown documents to the Academy - Learn the process for publishing documentation
• Documentation style guide and writing guidelines - Follow our style conventions

This comment is posted automatically when changes are detected in the docs/ folder.

[github-actions]

🦜 Chachalog

javascript-modules patch

• Scaffolded modules now lint the server-runtime boundary: using a timer, fetch, a browser global or a Node.js built-in inside a *.server.* or *.action.* file is reported in the editor and by yarn lint, with a link to the new server runtime boundary reference, instead of failing at runtime on the first call. Client files are unaffected. (Lint/build-time guard for APIs unavailable in the server runtime #703)

Create a new entry online or run npx chachalog@0.5.2 prompt to create a new entry locally.