buildless-types

name	buildless-types
description	Use when the user asks to "set up types without a build step", "use vanilla JS with types", "configure erasable syntax", or mentions "JSDoc type checking". It provides instructions for modern type safety using JSDoc in browsers and native TypeScript execution in Node.js.

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.