Modern Type Checking (No Build Step)

Configure projects for type safety without a compilation step (tsc/build) by leveraging JSDoc for browser code and Erasable Syntax for Node.js.

Core Philosophy

• Browser (Client-side): Use pure .js files with JSDoc annotations. This ensures the code runs directly in the browser while maintaining full IDE type support and error checking.

• Node.js (Server-side/Tooling): Use .ts files with Erasable Syntax. This allows Node.js (v24.11.0+) to execute TypeScript files directly without a build step, provided they don't use non-erasable features like enums or namespaces.

Configuration Standards

Apply these settings to enable seamless type checking.

1. package.json

Ensure the project is an ES Module and specifies a modern Node.js version.

{ "type": "module", "engines": { "node": ">=24.11.0" }, "scripts": { "typecheck": "tsc --noEmit" } }

2. tsconfig.json

Configure the TypeScript compiler to check JavaScript files and enforce erasable syntax.

{ "compilerOptions": { "target": "esnext", "module": "nodenext",

/* Node.js - Native TS Execution Flags */    
"erasableSyntaxOnly": true, /* Prevents using unsupported TypeScript features. */
"verbatimModuleSyntax": true, /* Enforces explicit type imports: https://nodejs.org/api/typescript.html#importing-types-without-type-keyword */
"allowImportingTsExtensions": true, /* Allows 'import x from "./file.ts"' */
"rewriteRelativeImportExtensions": true, /* Handle the import adjustment if compiling to JS */

/* Type Checking Strategy */
"noEmit": true,
"allowJs": true,
"checkJs": true,
"strict": true,
"skipLibCheck": true

} }

Coding Rules

Follow these rules to maintain a build-free environment.

Browser Rules (.js files)

• Use JSDoc for all types: Define variable types, function signatures, and complex objects using JSDoc comments.

• Avoid TS-specific syntax: Do not use interface , type aliases, or other TypeScript-only syntax in .js files.

• Import types correctly: Do NOT use the legacy typedef import (/** @typedef {import('./types.js').User} User / ). Use the modern TS 5.5+ style: /* @import {User} from './types.js' */ .

Node.js Rules (.ts files)

• Strictly use Erasable Syntax: Avoid features that require transformation.

• ❌ No enum

• ❌ No namespaces

• ❌ No parameter properties in constructors

• ❌ No experimentalDecorators

• Include file extensions: Always include the .ts extension in import paths: import { x } from './utils.ts' .

• Use import type : Explicitly mark type-only imports to satisfy verbatimModuleSyntax .

• Once implemented, add to project docs/guidelines that agents should NOT use npx tsx or ts-node to run node scripts; instead, just run them directly: node script.ts .

Example Files

• examples/tsconfig.json
• A complete type-checking configuration.