TypeScript & Node TypeError: [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ‘.ts’

Introduction

If you’re working with Node.js and TypeScript, you might encounter the [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ‘.ts’ error. This typically happens when Node.js tries to execute a TypeScript file without proper configuration or tooling to recognize and compile the .ts files. In this guide, we’re going to look at some common solutions to fix this error.

Solution 1: Use ts-node

The ts-node utility allows Node.js to run TypeScript files directly by compiling them on-the-fly. It’s an easy fix that means you won’t need to compile your TypeScript files manually before running them.

Steps:

1. Install ts-node by executing npm install -g ts-node in your terminal.
2. Run your TypeScript file using ts-node yourfile.ts.

Code example:

ts-node yourfile.ts

Using ts-node can result in slower performance due to on-the-fly compilation, which might not be ideal for a production environment but is perfectly fine for development.

Advantages: Simple to use; great for development and trying out TypeScript with minimal setup.

Limitations: Not recommended for production due to potential performance issues.

Solution 2: Compiling to JavaScript

Another approach is to compile your TypeScript files into JavaScript and run the resulting .js files with Node.js.

Steps:

1. Ensure TypeScript is installed globally with npm install -g typescript.
2. Compile your TypeScript file using the tsc yourfile.ts command. This will generate a yourfile.js file.
3. Run the compiled JavaScript file with Node.js by typing node yourfile.js.

Code example:

tsc yourfile.ts
node yourfile.js

This solution offers better performance since the JavaScript files are pre-compiled.

Advantages: Better performance; suitable for production.

Limitations: Requires an additional build step and managing generated files.

Solution 3: Configure TypeScript in package.json

You can configure your package.json to include a start script that uses ts-node to run your application, this provides the benefit of not having to remember to use ts-node every time.

Steps:

1. Add ts-node to your development dependencies with npm install --save-dev ts-node.

2. In your package.json file, add a start script as follows:

{
  "scripts": {
    "start": "ts-node ./src/index.ts"
  }
}

3. Run your application with npm start.

This has similar performance considerations as running ts-node directly.

Advantages: Streamlines the development process by integrating with npm’s scripts.

Limitations: Similar to using ts-node directly, it is not ideal for production.

Conclusion

The [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ‘.ts’ error in Node.js can be resolved in multiple ways. Using ts-node is convenient for development, whereas compiling TypeScript to JavaScript is better suited for production deployments. Alternatively, setting up a start script in your package.json can streamline your development workflow. Each method has its own set of trade-offs that you should consider based on your specific use case and environment.