Fix TypeError Unknown File Extension .ts

Seeing the TypeError: Unknown file extension .ts error can be frustrating. It stops your TypeScript code from running. This error happens when Node.js tries to load a .ts file directly without proper setup.

Don't worry. This guide explains why it happens. It also shows clear fixes. You will get your code running fast.

What Does This Error Mean?

Node.js natively understands JavaScript (.js). It does not understand TypeScript (.ts). When you run node myfile.ts, Node.js sees the .ts extension and does not know how to handle it. The result is the TypeError: Unknown file extension .ts.

This error is common for beginners. It also appears when you misconfigure your project. Understanding the root cause helps you fix it.

Common Causes of The Error

Several things can trigger this error:

• Running node directly on a .ts file.
• Missing TypeScript compiler or ts-node.
• Incorrect tsconfig.json settings.
• Using ES modules without proper setup.

Let's look at each cause and its solution.

Fix 1: Use ts-node Instead of Node

The simplest fix is using ts-node. This tool compiles TypeScript on the fly. Install it first.

npm install -g ts-node

Then run your file:

ts-node myfile.ts

Output:

Hello from TypeScript!

This works because ts-node handles the compilation. It acts as a bridge between Node.js and TypeScript.

Fix 2: Compile TypeScript First

Another approach is compiling to JavaScript first. Use the TypeScript compiler tsc.

tsc myfile.ts

This creates a myfile.js file. Then run it normally:

node myfile.js

This method is clean. It separates the build step from execution. It is ideal for production.

Fix 3: Configure tsconfig.json Properly

Sometimes the error comes from a misconfigured tsconfig.json. Ensure your settings are correct. Here is a basic example:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules"]
}

Make sure module is set to "commonjs" for Node.js. If you use ES modules, set it to "ESNext" or "ES2020" and add "type": "module" in your package.json.

Fix 4: Use Node with --loader flag

For Node.js versions 16 and above, you can use the --loader flag. This tells Node.js to use ts-node as a loader.

node --loader ts-node/esm myfile.ts

Output:

Success with ESM loader!

This works well for ES modules. It avoids the TypeError: Unknown file extension .ts error.

Fix 5: Check for Missing Dependencies

If you use ts-node and still get the error, check your package.json. Ensure ts-node and typescript are listed.

npm install --save-dev ts-node typescript

Then try running again. Sometimes a simple reinstall fixes the issue.

Example Code to Test Your Setup

Create a simple TypeScript file to test.

// hello.ts
const greet = (name: string): string => {
  return `Hello, ${name}!`;
};

console.log(greet("World"));

Run it with ts-node:

ts-node hello.ts

Expected output:

Hello, World!

If you see this, your setup works. The error is gone.

How to Avoid This Error in the Future

Follow these best practices:

• Always use ts-node or compile before running.
• Keep your tsconfig.json consistent.
• Use package.json scripts to automate tasks.
• Update Node.js and TypeScript regularly.

For similar issues with other languages, check our guide on Python Character Encoding Guide for Beginners. It helps with encoding errors in Python.

Debugging Tips

If the error persists, try these steps:

1. Check the file extension. Ensure it is .ts and not .tsx or something else.
2. Verify your Node.js version. Use node --version. Older versions lack support.
3. Clear the node_modules folder and reinstall dependencies.

Sometimes the error comes from a corrupted installation. A clean reinstall often fixes it.

Conclusion

The TypeError: Unknown file extension .ts error is common but easy to fix. Use ts-node to run TypeScript directly. Compile with tsc for production. Configure your tsconfig.json properly. Use the --loader flag for ES modules.

Remember, Node.js does not understand TypeScript natively. You need a tool to translate it. With the steps above, you can run any TypeScript file without errors. Happy coding!

For more troubleshooting tips, explore our Python Character Encoding Guide for Beginners. It covers similar debugging concepts.