How to Fix "Unknown file extension .ts" in TypeScript on Heroku

By the end of this page, you will understand why Node.js cannot run TypeScript files directly, how ts-node, ESM, and CommonJS interact, and why your Heroku deployment fails when package.json and tsconfig.json use conflicting module systems. You will also learn practical ways to fix the problem: either compile TypeScript to JavaScript before running it, or configure ts-node correctly for the module system you chose.

TypeScript files use the .ts extension, but Node.js only understands JavaScript at runtime unless you add a tool to translate TypeScript first.

In this question, the main issue is module system mismatch:

• package.json contains "type": "module"
• tsconfig.json contains "module": "commonjs"
• the app is started with ts-node src/App.ts

These settings pull Node in different directions.

What is happening?

Node.js has two main module systems:

• CommonJS: uses require() and module.exports
• ES Modules (ESM): uses import and export

When you set this in package.json:

{
  "type": "module"
}

Node starts treating your project as an ESM project.

Think of Node.js as a person who can only read one language natively: JavaScript.

TypeScript is like a document written in a slightly different language. It looks similar, but it still needs a translator.

• tsc is a translator that converts the document ahead of time
• ts-node is a live interpreter that translates while reading

Now imagine you also tell Node what reading style to use:

• "type": "module" says: “Read this as ESM.”
• "module": "commonjs" says: “Generate CommonJS output.”

That is like giving someone two conflicting instructions:

• “Read this as a modern import/export document”
• “But the translated output will be in an older require/module format”

If the interpreter is not configured to bridge that gap, Node gets confused and stops at the .ts file itself.

Core idea: Node runs JavaScript, not .ts

A common production setup is:

1. compile TypeScript with tsc
2. run the generated JavaScript with node

CommonJS-style production setup

package.json

{
  "main": "dist/App.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/App.js",
    "dev": "nodemon --exec ts-node src/App.ts"
  }
}

tsconfig.json

{
  "compilerOptions": {
     
     
     
     
     
     
     
  
   

Consider this setup:

package.json

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/App.js"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2019",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

src/App.ts

1. Deploying TypeScript apps to Heroku, Render, or Railway

Many beginners run ts-node locally and assume production should do the same. In production, teams often compile first because it is more predictable.

2. Running API servers

Express, Fastify, NestJS, and other backend apps often use TypeScript during development but run compiled JavaScript in production.

Example pattern:

• local: ts-node, tsx, or framework dev server
• production: tsc then node dist/server.js

3. CI/CD pipelines

Build servers usually:

• install dependencies
• run tests
• compile TypeScript
• deploy built JavaScript

This avoids runtime differences between environments.

4. Monorepos and shared libraries

Large projects need clear module formats. If one package is ESM and another is CommonJS, build and runtime settings must be aligned carefully.

5. Worker scripts and cron jobs

Background jobs often fail if the environment cannot load .ts files directly. Precompiling avoids that issue.

In real projects, developers usually pick one of these patterns.

Pattern 1: Compile before start

Very common in production.

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/App.js"
  }
}

Why teams like it:

• fewer runtime surprises
• faster startup in production
• easier debugging of deployment issues
• no need for TypeScript execution hooks at runtime

Pattern 2: Separate dev and prod scripts

{
  "scripts": {
    "dev": "nodemon --exec ts-node src/App.ts",
    "build": "tsc",
    "start": "node dist/App.js"
  }
}

This is a strong beginner-friendly pattern.

1. Mixing ESM and CommonJS settings

Broken setup:

{
  "type": "module"
}

with:

{
  "compilerOptions": {
    "module": "commonjs"
  }
}

Why it is a problem:

• Node treats files as ESM
• TypeScript compiles as CommonJS
• runtime expectations do not match

How to avoid it:

• either remove "type": "module"
• or switch the TypeScript config and runtime tools to a full ESM setup

2. Running ts-node in production without checking compatibility

Broken assumption:

{
  "start": "ts-node src/App.ts"
}

This may work locally but fail in production because of Node version differences or ESM handling.

Quick rules

• Node does not run .ts files natively
• ts-node can run .ts, but its configuration must match your module system
• "type": "module" makes Node treat the project as ESM
• "module": "commonjs" tells TypeScript to output CommonJS
• Mixing those settings often causes runtime errors

Safe production setup

package.json

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/App.js"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "module": 
     
  

Why does Node say .ts is an unknown file extension?

Because Node only understands JavaScript by default. A .ts file must be compiled first or handled by a compatible runtime tool such as ts-node.

Why did this happen on Heroku but maybe not locally?

Production environments may use a different Node version or load modules differently. Heroku also runs your start script exactly as defined, so configuration problems become obvious there.

Is ts-node good for production?

It can work, but many teams prefer compiling with tsc and running JavaScript in production because it is simpler and more reliable.

What is wrong with using "type": "module" and "module": "commonjs" together?

They describe different module systems. Node will expect ESM behavior, while TypeScript will compile for CommonJS. That mismatch often causes runtime errors.

Should I remove "type": "module"?

If your project is meant to use CommonJS and you want the simplest fix, yes. Remove it and compile to JavaScript before running.

What is the easiest fix for this specific setup?

Use a build step with tsc, remove "type": "module", and start the compiled file with .

• TypeScript compilation — Related because .ts files usually need to be compiled into .js before production runtime.
• ts-node — Related because it runs TypeScript directly and is central to this error.
• Node.js module systems — Related because the issue comes from ESM versus CommonJS behavior.
• CommonJS — Related because your tsconfig.json is configured to use it.
• ES Modules — Related because package.json sets type to module.
• package.json scripts — Related because Heroku executes the start script exactly.
• tsconfig.json — Related because compiler options control how TypeScript output is generated.
• Heroku Node deployment — Related because deployment environments amplify configuration mistakes.
• Build vs runtime transpilation — Related because this question is really about when TypeScript gets converted to JavaScript.