Node.js runs TypeScript natively: lessons from production

For years, running TypeScript in Node.js meant either compiling it to JavaScript first or using a loader like ts-node. That friction is gone. Node.js runs TypeScript natively—it strips type annotations and executes the result directly, making TypeScript a viable first-class runtime language without an intermediate build step. But this power comes with important constraints you need to understand to use it effectively.

What it does — Node removes type annotations and runs the result

When you enable TypeScript support in Node.js (via the --experimental-strip-types flag in recent versions, or through the tsx runtime), Node.js acts as a type-stripping engine. It reads your .ts file, removes all type annotations, and executes the resulting JavaScript in the same process. No separate compilation, no output files, no build artifacts.

This is genuinely useful. Here's what happens under the hood:

// user.ts
interface User {
  id: number;
  name: string;
  email: string;
}

function getUser(userId: number): User {
  return {
    id: userId,
    name: "Alice",
    email: "alice@example.com"
  };
}

const user = getUser(1);
console.log(user.name);

Node strips the interface and type annotations to produce:

function getUser(userId) {
  return {
    id: userId,
    name: "Alice",
    email: "alice@example.com"
  };
}

const user = getUser(1);
console.log(user.name);

Then it runs that result. The types are completely removed at runtime—there's no type validation happening, no reflection on type information, and no runtime overhead from type metadata. What remains is pure, executable JavaScript logic.

I use this pattern heavily for build scripts and CLI tools. Instead of maintaining both a TypeScript source and a compiled output folder, I just run the .ts file directly. It's simpler, faster to iterate on, and still gives me static type safety during development.

What it doesn't — No type checking. Run tsc --noEmit separately

This is the critical limitation that catches many developers off guard. Type stripping is not type checking. Node.js doesn't validate that your types are correct—it just removes them and runs the code. If you have a type error, you won't know until runtime (or until your code logic breaks).

Consider this example:

interface Config {
  apiUrl: string;
  timeout: number;
}

function loadConfig(data: unknown): Config {
  // This looks like it returns a Config, but it doesn't
  return data as Config;
}

const config = loadConfig({ apiUrl: "http://api.example.com" });
console.log(config.timeout.toString()); // Runtime error: timeout is undefined

Without type checking, Node.js strips the interface and the as Config cast, then runs the code. It crashes at runtime because timeout is undefined. The TypeScript compiler would have caught this immediately if you'd run type checking.

The solution is simple: run type checking separately as part of your workflow. Use tsc --noEmit in your CI pipeline or before deploying:

// package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "start": "node --experimental-strip-types src/server.ts",
    "build": "npm run typecheck && tsc"
  }
}

In development, most IDEs will show you type errors as you code. In CI, add a separate typecheck step that runs before tests or deployment. This decouples runtime execution from type validation, which is actually fine—the types are optional metadata anyway, not part of the runtime contract.

Limitations — No enums, namespaces or parameter properties without extra flags

Type stripping works because types don't generate code. But some TypeScript features do generate code at runtime. Node.js's basic type-stripping mode doesn't handle these, so you need workarounds.

Enums are the biggest culprit:

enum Status {
  Active = "active",
  Inactive = "inactive",
  Pending = "pending"
}

const userStatus: Status = Status.Active;
console.log(userStatus); // What gets printed?

TypeScript normally compiles enums to JavaScript objects. But basic type stripping just removes the enum keyword and all the values disappear. You're left with undefined code. For enums, use a const object instead:

const Status = {
  Active: "active",
  Inactive: "inactive",
  Pending: "pending"
} as const;

type Status = typeof Status[keyof typeof Status];

const userStatus: Status = Status.Active;
console.log(userStatus); // "active"

Parameter properties (the class shorthand) also generate code:

class User {
  constructor(
    public id: number,
    public name: string
  ) {}
}

// This becomes an assignment in compiled JS, but gets stripped in basic mode

Avoid the shorthand and use explicit assignments instead:

class User {
  id: number;
  name: string;

  constructor(id: number, name: string) {
    this.id = id;
    this.name = name;
  }
}

Namespaces are rarely used in modern TypeScript anyway, so I'd skip them entirely and use ES modules. If you absolutely need these features, you can enable experimentalDecorators, emitDecoratorMetadata, or use a full TypeScript compilation step instead of type stripping.

Great for scripts — Run tooling scripts without a build step

This is where type-stripped TypeScript really shines: command-line tools, build scripts, and deployment utilities. Any time you'd write a Node.js script, you can write it in TypeScript and run it directly.

Here's a real example from my recent work—a database migration runner:

// scripts/migrate.ts
import { execSync } from "child_process";
import { readdir } from "fs/promises";
import { join } from "path";

interface MigrationFile {
  name: string;
  timestamp: number;
}

async function runMigrations(direction: "up" | "down"): Promise {
  const migrationDir = join(process.cwd(), "migrations");
  const files = await readdir(migrationDir);

  const migrations: MigrationFile[] = files
    .filter((f) => f.endsWith(".sql"))
    .map((name) => ({
      name,
      timestamp: parseInt(name.split("_")[0], 10)
    }))
    .sort((a, b) => a.timestamp - b.timestamp);

  console.log(`Found ${migrations.length} migrations`);

  for (const migration of migrations) {
    console.log(`Running: ${migration.name}`);
    execSync(
      `psql $DATABASE_URL -f migrations/${migration.name}`,
      { stdio: "inherit" }
    );
  }

  console.log("Migrations complete");
}

runMigrations(process.argv[2] as "up" | "down").catch(console.error);

I run this with node --experimental-strip-types scripts/migrate.ts up. No compilation, no build output, no clutter. The script gets type checking in my editor, but at runtime it's just JavaScript executing as fast as native Node.js would run it.

The same pattern works for:

• Database seed scripts
• API scaffolding generators
• Configuration validators
• Data transformation utilities
• Deployment verification checks

For production services, I'd still prefer a full TypeScript build with tsc. For scripts and tooling that run in CI or locally, type-stripped TypeScript removes friction without sacrificing type safety.

Common mistakes

Mistake 1: Assuming type checking happens automatically. It doesn't. Add tsc --noEmit to your CI pipeline or pre-commit hooks. Catch errors before they reach production.

Mistake 2: Using enums in type-stripped mode without realizing they won't work. Test your scripts. Better yet, use const objects and type annotations instead.

Mistake 3: Running type-stripped code in production without verification. Type stripping is best for scripts and development tooling. For long-running services, compiled TypeScript or JavaScript is safer because you control exactly what's being executed and can verify it's been type-checked.

Mistake 4: Forgetting that tsconfig.json settings still matter. Module resolution, JSX, target version—these still apply. Make sure your tsconfig aligns with your Node.js version and runtime requirements.

Key takeaways

• Node.js runs TypeScript natively by stripping type annotations and executing the result as JavaScript—no build step required.
• Type stripping is not type checking. You must run tsc --noEmit separately in CI to catch type errors.
• Avoid enums, namespaces, and parameter properties in type-stripped mode, or use workarounds (const objects, explicit class assignments).
• This pattern is ideal for scripts, build utilities, and CLI tools where you want type safety without compilation overhead.
• For production services, compile TypeScript to JavaScript and version-control the output for auditability and performance guarantees.