build-free-types（构建自由类型）

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.