TypeScript Register

Common errors

• Error: Cannot find module 'typescript' or its corresponding type declarations.

  cause The `typescript` package, which is a required runtime dependency for compilation, is missing from the project's `node_modules`.
  fix `npm install typescript` or `yarn add typescript` in your project.

• SyntaxError: Unexpected token 'export' (at ...)

• SyntaxError: Unexpected token 'import' (at ...)

  cause Attempting to run a TypeScript file using ESM `import`/`export` syntax within an older Node.js version or a CommonJS context where `typescript-register` is not properly transpiling to CJS, or where the Node.js runtime itself expects CJS.
  fix Ensure your TypeScript files are compiling to CommonJS (if you intend to use `require`), or switch to a modern runner like `tsx` or `ts-node` with ESM support for projects using native ESM.

• TypeError: require.extensions is not a function

  cause Newer Node.js versions have deprecated or changed how `require.extensions` works, or the execution environment (e.g., bundled runtime) has restricted access to it, which this package heavily relies upon.
  fix This package heavily relies on `require.extensions` and is unlikely to work in environments where it's unavailable or modified. Migrate to a modern alternative that uses Node.js's official loader hooks or a more robust transpilation approach.

Warnings

• breaking This package has been abandoned since 2018 (last publish v1.1.0) and is highly unlikely to be compatible with recent versions of Node.js (e.g., Node 16+), TypeScript (e.g., TS 4+), or native ESM modules. Using it in modern projects will likely lead to compilation failures or runtime errors.
  Fix: Consider modern alternatives like `ts-node`, `esbuild-register`, or `tsx` for on-the-fly TypeScript execution, which are actively maintained and support current standards.
• gotcha Configuration for `typescript-register` is exclusively handled through environment variables (`TYPESCRIPT_REGISTER_EMIT_ERROR`, `TYPESCRIPT_REGISTER_USE_CACHE`, `TYPESCRIPT_REGISTER_COMPILER_OPTIONS`). There is no programmatic API or `tsconfig.json` integration, making dynamic configuration complex and potentially error-prone for larger projects.
  Fix: Set environment variables before `require('typescript-register')`. For complex `compilerOptions`, ensure the JSON stringification is valid. For programmatic control, you might need to manage `process.env` directly or pre-process the script.
• gotcha The package registers a global `require` hook. While convenient, this approach can conflict with other custom module loaders, bundlers, or environments that modify Node.js's module resolution, potentially leading to unexpected behavior or difficult-to-debug issues.
  Fix: Avoid using this package in environments where multiple custom `require` hooks are active. Test thoroughly to ensure compatibility with your specific toolchain. Modern alternatives often provide more isolated or controlled execution contexts.
• breaking This package is designed for CommonJS environments and does not natively support ECMAScript Modules (ESM) syntax (`import`/`export` outside of transpilation to CJS) or the `.mjs`/`.mts` file extensions directly. Attempting to use it in an ESM project will likely fail.
  Fix: For ESM projects, use modern TypeScript execution tools like `ts-node` configured for ESM, `tsx`, or `esbuild-register` which are built to handle Node.js's dual-package hazard and ESM loading mechanisms.

Install

• npm install typescript-register npm
• yarn add typescript-register yarn
• pnpm add typescript-register pnpm

Imports

• registerHook
  wrong:

  import 'typescript-register';

  correct:

  require('typescript-register');

  This package registers a global `require` hook and does not export any named symbols. It is primarily designed for CommonJS environments and does not support ESM `import` statements.

Quickstart

Demonstrates how to activate the TypeScript require hook and import a `.ts` file in a CommonJS Node.js application, including basic environment variable configuration and an example `.ts` file.

{
// bar.js
process.env.TYPESCRIPT_REGISTER_EMIT_ERROR = 'true';
process.env.TYPESCRIPT_REGISTER_USE_CACHE = 'true';
// Optional: Configure TypeScript compiler options. This example targets ES2018
// and uses CommonJS modules, with strict type checking enabled.
process.env.TYPESCRIPT_REGISTER_COMPILER_OPTIONS = JSON.stringify({
  target: 'es2018',
  module: 'commonjs',
  strict: true,
  esModuleInterop: true // Often needed for better interop with CommonJS
});

// Activate the TypeScript require hook. All subsequent `require` calls for .ts files
// will be transpiled on the fly.
require('typescript-register');

// Attempt to require a TypeScript file.
try {
  // Ensure 'foo.ts' exists in the same directory as 'bar.js'
  // Example content for 'foo.ts': `export var foo = 3; export const greeting = "Hello";`
  const fooModule = require('./foo.ts');
  console.log('Value from foo.ts:', fooModule.foo); // Expected: 3
  console.log('Greeting from foo.ts:', fooModule.greeting); // Expected: "Hello"
} catch (e) {
  console.error('Error requiring TypeScript file:', e.message);
  if (e.stack) {
    console.error(e.stack);
  }
}

// Additional example: a type-checked function in TypeScript
/*
// In a file named 'calculator.ts'
export function add(a: number, b: number): number {
  return a + b;
}
*/
try {
  const calculator = require('./calculator.ts');
  console.log('2 + 3 =', calculator.add(2, 3)); // Expected: 5
  // This would typically cause a TypeScript error during compilation if type-checked:
  // console.log('2 + "3" =', calculator.add(2, "3"));
} catch (e) {
  console.error('Error requiring calculator.ts:', e.message);
}}