feat(check): erasable-typescript-only rule + ship erasableSyntaxOnly in tsconfigs

vivek7405 · vivek7405 · commit 490372abc888 · 2026-05-19T01:41:38.000+05:30
Adds compilerOptions.erasableSyntaxOnly to: the scaffold tsconfig
generator (packages/cli/lib/create.js), the blog example, the docs
site, the marketing site. TypeScript 5.8+ rejects enum, namespace
with values, constructor parameter properties, legacy decorators
with emitDecoratorMetadata, and import = require at compile time
when this flag is set. Violations surface as red squiggles in the
editor, well before they would hit Node's built-in strip-types and
trigger the (slower, sourcemap-bearing) esbuild fallback path.

Adds a new webjs check rule, erasable-typescript-only, that loads
the project's tsconfig.json and warns when erasableSyntaxOnly is
missing or set to false. Lighter than a custom TS parser because
the actual checking is delegated to tsc; this rule just verifies
the tsconfig opted in. Verified against the blog example: passes
with the flag on, flags a single violation when flipped to false.
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
@@ -9,7 +9,8 @@
     "allowJs": true,
     "checkJs": true,
     "allowImportingTsExtensions": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "erasableSyntaxOnly": true
   },
   "include": ["app/**/*", "components/**/*"],
   "exclude": ["node_modules", ".webjs"]
diff --git a/examples/blog/tsconfig.json b/examples/blog/tsconfig.json
@@ -3,7 +3,11 @@
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
     "strict": true,
     "noEmit": true,
     "checkJs": true,
@@ -12,9 +16,12 @@
     "skipLibCheck": true,
     "isolatedModules": true,
     "verbatimModuleSyntax": false,
+    "erasableSyntaxOnly": true,
     "jsx": "preserve",
     "plugins": [
-      { "name": "@webjskit/ts-plugin" }
+      {
+        "name": "@webjskit/ts-plugin"
+      }
     ]
   },
   "include": [
@@ -25,5 +32,9 @@
     "middleware.js",
     "middleware.ts"
   ],
-  "exclude": ["node_modules", ".webjs", "prisma/migrations"]
-}
+  "exclude": [
+    "node_modules",
+    ".webjs",
+    "prisma/migrations"
+  ]
+}
diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
@@ -224,6 +224,17 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       noEmit: true,
       allowImportingTsExtensions: true,
       skipLibCheck: true,
+      // webjs uses Node's built-in type-stripping (`process.features.
+      // typescript === 'strip'`) which preserves source positions
+      // byte-exactly. The constraint is that TypeScript must be
+      // "erasable": no `enum`, no `namespace` with values, no
+      // constructor parameter properties, no legacy decorators with
+      // `emitDecoratorMetadata`. erasableSyntaxOnly makes the
+      // compiler reject those at edit time so violations surface as
+      // red squiggles instead of runtime ERR_UNSUPPORTED_TYPESCRIPT_
+      // SYNTAX errors. Use a `const` object + union for enum-shaped
+      // values; write fields + constructor assignments explicitly.
+      erasableSyntaxOnly: true,
       // @webjskit/ts-plugin gives the editor:
       //   • type-check + diagnostics inside html`` templates (via the
       //     ts-lit-plugin it bundles internally)
diff --git a/packages/server/src/check.js b/packages/server/src/check.js
@@ -87,6 +87,11 @@ export const RULES = [
     description:
       'Only the root layout (app/layout.{js,ts}) may write a <!doctype>/<html>/<head>/<body> shell to override default <html lang>, <body class>, etc. Non-root layouts (app/<segment>/layout.{js,ts}) and pages (app/**/page.{js,ts}) must not: the framework auto-emits the wrapper around the whole composition, so a nested shell ends up nested inside <body> where browsers drop it. Triggers on any of <!doctype>, <html, <head, <body in a non-root layout or page.',
   },
+  {
+    name: 'erasable-typescript-only',
+    description:
+      'Apps must opt into TypeScript\'s `erasableSyntaxOnly: true` so the compiler rejects non-erasable syntax (enum, namespace with values, constructor parameter properties, legacy decorators with emitDecoratorMetadata, import = require) at edit time. webjs strips types via Node\'s built-in `module.stripTypeScriptTypes`, which only supports erasable TypeScript and produces byte-exact position preservation (no sourcemap overhead). Files using non-erasable syntax fall back to esbuild + inline sourcemap, which is supported as a safety net for third-party deps but should not be the path your own code takes. The rule checks the project\'s tsconfig.json and warns when `erasableSyntaxOnly` is missing or set to false. Set `compilerOptions.erasableSyntaxOnly: true` in tsconfig.json to comply.',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -754,6 +759,51 @@ export async function checkConventions(appDir, opts) {
     }
   }
 
+  // --- Rule: erasable-typescript-only ---
+  // The dev server's primary type-stripper is Node's built-in
+  // module.stripTypeScriptTypes, which rejects non-erasable TS (enum,
+  // namespace with values, constructor parameter properties, legacy
+  // decorators, `import = require`). The fallback path is esbuild +
+  // inline sourcemap, which is a real ~3x wire-byte hit on every .ts
+  // request that takes it. Enforce TS-side rejection of those patterns
+  // via `compilerOptions.erasableSyntaxOnly: true` in tsconfig.json so
+  // violations surface as red squiggles in the editor before they ever
+  // hit the dev server.
+  if (isRuleEnabled('erasable-typescript-only', overrides)) {
+    let tsconfigContent = null;
+    try {
+      tsconfigContent = await readFile(join(appDir, 'tsconfig.json'), 'utf8');
+    } catch {
+      // No tsconfig.json (pure JS app). Skip the rule.
+    }
+    if (tsconfigContent != null) {
+      let parsed = null;
+      try {
+        const stripped = tsconfigContent
+          .replace(/\/\/.*$/gm, '')
+          .replace(/\/\*[\s\S]*?\*\//g, '')
+          .replace(/,(\s*[}\]])/g, '$1');
+        parsed = JSON.parse(stripped);
+      } catch {
+        parsed = null;
+      }
+      const compilerOptions = parsed && typeof parsed === 'object' ? parsed.compilerOptions : null;
+      const flag = compilerOptions && typeof compilerOptions === 'object' ? compilerOptions.erasableSyntaxOnly : undefined;
+      if (flag !== true) {
+        violations.push({
+          rule: 'erasable-typescript-only',
+          file: 'tsconfig.json',
+          message:
+            flag === false
+              ? '`compilerOptions.erasableSyntaxOnly` is `false`. The framework strips TypeScript via Node\'s built-in stripper, which only supports erasable TS. Non-erasable syntax (enum, namespace with values, constructor parameter properties, legacy decorators) falls back to esbuild + inline sourcemap on every request, costing ~3x wire bytes and losing byte-exact stack-trace positions.'
+              : '`compilerOptions.erasableSyntaxOnly` is not set. The framework strips TypeScript via Node\'s built-in stripper, which only supports erasable TS. Setting this flag makes the TypeScript compiler flag non-erasable syntax as a red squiggle in the editor instead of letting it silently slip through to a slower runtime fallback.',
+          fix:
+            'Set `"erasableSyntaxOnly": true` under `compilerOptions` in tsconfig.json. Replace any existing `enum` declarations with `const X = { ... } as const` plus a `type X = typeof X[keyof typeof X]` union. Replace constructor parameter properties with explicit field declarations + assignments.',
+        });
+      }
+    }
+  }
+
   // --- Rule: tag-name-has-hyphen ---
   if (isRuleEnabled('tag-name-has-hyphen', overrides)) {
     for (const { rel, content } of files) {
diff --git a/website/tsconfig.json b/website/tsconfig.json
@@ -7,7 +7,8 @@
     "strict": true,
     "noEmit": true,
     "allowImportingTsExtensions": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "erasableSyntaxOnly": true
   },
   "include": ["app/**/*", "components/**/*"],
   "exclude": ["node_modules", ".webjs"]
