• 04-Jun-2023
Lightrun Team
Author Lightrun Team

set “type”: “module” in `package.json` breaks the build

Lightrun Team
Lightrun Team

Explanation of the problem

When the “type” field in the package.json file is set to “module”, the following error occurs:


node -r esbuild-register scripts/test.ts

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /scripts/test.ts
    at Loader.defaultGetFormat [as _getFormat] (internal/modules/esm/get_format.js:65:15)
    at Loader.getFormat (internal/modules/esm/loader.js:101:42)
    at Loader.getModuleJob (internal/modules/esm/loader.js:230:31)
    at Loader.import (internal/modules/esm/loader.js:164:17)
    at Object.loadESM (internal/process/esm_loader.js:68:5) {


This error is caused by the “type” field being set to “module” in the package.json file, which triggers ECMAScript module support in Node.js. When this is enabled, Node.js expects module files to have specific file extensions, such as “.mjs” or “.js”. In the given scenario, the error occurs because the file “scripts/test.ts” has the “.ts” extension, which is not recognized as a valid file extension for ECMAScript modules.

To resolve this issue, you can either change the file extension of the module file to a recognized one (e.g., “.mjs” or “.js”), or you can disable the “type” field as “module” in the package.json file. Here’s an example of how to update the package.json file to disable the “type” field:


  "type": "commonjs",
  "scripts": {
    "test": "node -r esbuild-register scripts/test.ts"


By setting the “type” field to “commonjs”, Node.js will treat the module files as CommonJS modules, which allows the usage of “.ts” file extensions. This change ensures that the “scripts/test.ts” file can be properly recognized and executed without triggering the “ERR_UNKNOWN_FILE_EXTENSION” error.


Troubleshooting with the Lightrun Developer Observability Platform

Getting a sense of what’s actually happening inside a live application is a frustrating experience, one that relies mostly on querying and observing whatever logs were written during development.
Lightrun is a Developer Observability Platform, allowing developers to add telemetry to live applications in real-time, on-demand, and right from the IDE.

  • Instantly add logs to, set metrics in, and take snapshots of live applications
  • Insights delivered straight to your IDE or CLI
  • Works where you do: dev, QA, staging, CI/CD, and production

Start for free today

Problem solution for: set “type”: “module” in `package.json` breaks the build

To solve the problem of the “ERR_UNKNOWN_FILE_EXTENSION” error when using the “type”: “module” configuration in the package.json file, you have a couple of options:

  1. Change the file extension: One approach is to change the file extension of the module file to a recognized one, such as “.mjs” or “.js”. In this case, you can rename the “scripts/test.ts” file to “scripts/test.js”. This ensures that the file is recognized as a valid ECMAScript module when running with the “type”: “module” configuration.
  2. Disable the “type” field as “module”: If you want to keep the “.ts” file extension and continue using TypeScript modules, you can disable the “type” field as “module” in the package.json file. By changing the “type” field to “commonjs”, Node.js will treat the module files as CommonJS modules, which allows the usage of “.ts” file extensions without triggering the “ERR_UNKNOWN_FILE_EXTENSION” error. Here’s an example of the updated package.json file:


  "type": "commonjs",
  "scripts": {
    "test": "node -r esbuild-register scripts/test.ts"


By making this change, Node.js will interpret the “scripts/test.ts” file as a CommonJS module, allowing it to be executed without encountering the “ERR_UNKNOWN_FILE_EXTENSION” error.


Other popular problems with esbuild-register

  1. Error: “Cannot find module ‘esbuild-register'”: Problem Description: One common problem with esbuild-register is encountering the “Cannot find module ‘esbuild-register'” error. This occurs when the esbuild-register module is not installed or cannot be found in the project’s dependencies. It typically happens when attempting to use esbuild-register as a require hook for compiling and loading ECMAScript modules (ESM).

Solution: To resolve this issue, you need to ensure that the esbuild-register module is installed as a dependency in your project. You can install it using npm or yarn by running the following command:


npm install --save-dev esbuild-register


Once the module is installed, you can use it as a require hook in your code to enable the compilation and loading of ESM files:




Make sure that you require/import this module before any other ESM files are loaded in your project.

  1. Error: “SyntaxError: Cannot use import statement outside a module”: Problem Description: Another common problem when working with esbuild-register is encountering the “SyntaxError: Cannot use import statement outside a module” error. This occurs when using import statements in a file that is not recognized as an ECMAScript module. By default, Node.js treats files as CommonJS modules, which use require() instead of import.

Solution: To resolve this issue, you can use the esm package in combination with esbuild-register. The esm package allows you to enable ECMAScript module loading in Node.js. First, install the esm package:


npm install --save-dev esm


Then, modify your require hook to include the esm package:


  // Other esbuild-register options...
  // ...
  require: ['esm']


By including the esm package as a requirement in the esbuild-register options, you enable the usage of import statements in your code.

  1. Error: “esbuild-register failed to transform the file”: Problem Description: Sometimes, you may encounter an error message indicating that esbuild-register failed to transform a particular file. This can happen due to various reasons, such as unsupported JavaScript syntax or incompatible module imports.

Solution: To address this issue, you can try the following steps:

  1. Ensure that the code in the file is written using valid JavaScript syntax. Check for any syntax errors or unsupported language features.
  2. Verify that all imported modules are compatible with the ECMAScript module system. Some third-party modules may not be designed to work as ESM and may require additional configuration or transformation.
  3. If the file relies on specific Node.js features or global objects that are not available in esbuild-register, consider using a different approach or build tool that better supports those features.

By troubleshooting and resolving the specific issues causing the transformation failure, you can overcome the “esbuild-register failed to transform the file” error and ensure successful compilation and execution of your code.


A brief introduction to esbuild-register

esbuild-register is a Node.js module that serves as a require hook for seamless integration of the esbuild bundler with Node.js projects. It enables on-the-fly compilation and loading of ECMAScript modules (ESM) in Node.js, allowing developers to leverage the benefits of esbuild’s fast and efficient bundling capabilities directly within their Node.js applications. By using esbuild-register, developers can write their code using modern JavaScript syntax, including import/export statements, and have it automatically transpiled and executed by the esbuild compiler.

Under the hood, esbuild-register hooks into Node.js’s module loading system and intercepts require calls for ESM files. It dynamically transpiles the ESM code using esbuild’s powerful and performant bundling engine and provides the transformed code to Node.js for execution. This seamless integration enables developers to write their Node.js applications using modern JavaScript features and modules without the need for additional build steps or configuration. The result is faster startup times and improved runtime performance, as esbuild is known for its impressive bundling speed and optimization capabilities.

Overall, esbuild-register simplifies the development process by eliminating the need for manual transpilation and bundling steps, allowing developers to focus on writing clean and modern JavaScript code while benefiting from the performance advantages of esbuild’s bundling engine. It provides a convenient way to leverage the power of esbuild within Node.js projects, enabling developers to take full advantage of modern JavaScript syntax and module features in their server-side applications.


Most popular use cases for esbuild-register

    1. Seamless ECMAScript Module (ESM) Integration: esbuild-register enables seamless integration of ECMAScript modules (ESM) with Node.js applications. It serves as a require hook that automatically transpiles and loads ESM files on-the-fly using the esbuild bundler. This allows developers to write their code using modern JavaScript syntax, including import/export statements, and have it seamlessly executed within Node.js without the need for manual transpilation steps.

    Example code:



// Now you can use ECMAScript modules in your Node.js code
import { someFunction } from './module.js';



  1. Faster Startup and Execution: By leveraging esbuild’s efficient bundling engine, esbuild-register significantly reduces the startup time and improves the runtime performance of Node.js applications. esbuild’s fast bundling capabilities ensure that the ESM code is transpiled and optimized quickly, resulting in reduced load times and improved overall performance of the application.
  2. Streamlined Development Workflow: esbuild-register simplifies the development workflow by eliminating the need for separate transpilation and bundling steps. Developers can write their code using modern JavaScript features and modules, and esbuild-register takes care of the behind-the-scenes transpilation process. This allows for a more streamlined development experience, as developers can focus on writing clean and modern JavaScript code without the overhead of additional build configuration.

Overall, esbuild-register enhances the development process by seamlessly integrating ECMAScript modules with Node.js applications, improving performance, and streamlining the development workflow. It provides a convenient solution for utilizing modern JavaScript syntax and module features within Node.js projects, making it an invaluable tool for developers seeking a more efficient and modern development experience.



It’s Really not that Complicated.

You can actually understand what’s going on inside your live applications.

Try Lightrun’s Playground

Lets Talk!

Looking for more information about Lightrun and debugging?
We’d love to hear from you!
Drop us a line and we’ll get back to you shortly.

By submitting this form, I agree to Lightrun’s Privacy Policy and Terms of Use.