TypeScript Require Extension for Node.js

Common errors

• Error: Cannot find module 'some-ts-file'

  cause The `typescript-require` hook was not initialized before attempting to require a `.ts` file, or the path is incorrect.
  fix Ensure `require('typescript-require');` is called once at the very beginning of your application's entry point, and verify the path to the `.ts` file.

• TypeError: Object has no method 'toLowerCase' (or similar runtime type errors)

  cause TypeScript compilation errors occurred, potentially due to outdated `targetES5` settings or missing type definitions, leading to incorrect or incomplete JavaScript output that fails at runtime.
  fix Check the `typescript-require` configuration options like `targetES5` and `nodeLib`. Review the TypeScript code for errors that might be silently emitted (if `emitOnError: true`) but still lead to broken JS. Consider enabling `exitOnError: true` temporarily to halt execution on compilation failures.

Warnings

• breaking This package is largely incompatible with modern TypeScript features, `tsconfig.json` project configuration, or ES Modules (ESM). It was designed for an older TypeScript compiler API and CommonJS environments. Attempting to use it with recent TypeScript syntax or module systems will lead to compilation errors or unexpected behavior.
  Fix: Migrate to `ts-node` for JIT compilation in CommonJS/ESM, or `tsx` for a more modern JIT execution environment. For production, pre-compile TypeScript using `tsc`.
• gotcha The `nodeLib` option is `false` by default, meaning `node.d.ts` definitions are not automatically loaded. This requires explicit `/// <reference path='node.d.ts'/>` comments in TypeScript files that use Node.js types, which is an outdated practice compared to modern `@types/node` imports.
  Fix: If forced to use this package, manually add `/// <reference path='node.d.ts'/>` to relevant `.ts` files, or consider setting `nodeLib: true` in the configuration if available and functional.
• deprecated The `import ... module` syntax for internal module dependencies shown in the README (e.g., `import barmodule = module('barmodule');`) has been deprecated in modern TypeScript in favor of `import * as barmodule from './barmodule';` or default imports.
  Fix: Use modern TypeScript import syntax if the compiler version allows, though this package might not fully support it. The README suggests it compiles to a `require` call anyway.

Install

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

Imports

• TypeScriptRequire
  wrong:

  import 'typescript-require';

  correct:

  require('typescript-require');

  This package is a CommonJS `require` hook and does not support ES module `import` syntax for its own initialization. It enables `import` syntax for TS modules it processes.
• ConfiguredTypeScriptRequire
  wrong:

  import typescriptRequire from 'typescript-require';

  correct:

  require('typescript-require')({ targetES5: true, exitOnError: false });

  Configuration is passed directly as an argument to the initial `require` call, not via a separate import or method.
• TSModuleImport
  wrong:

  import { myModule } from './myModule.ts';

  correct:

  var myModule = require('./myModule.ts');

  While the package enables requiring `.ts` files, the internal examples show `var foomodule = require('./foomodule.js');` and `import barmodule = module('barmodule');` for TS files, implying `require('./some-ts-file')` is the primary way to consume the compiled output in the calling JS code.

Quickstart

This quickstart demonstrates how to initialize `typescript-require` with configuration options and then dynamically create and require a TypeScript module, showing its on-the-fly compilation capabilities.

/* app.js */
const path = require('path');
const fs = require('fs');

// Create a temporary directory for output if it doesn't exist
const tmpDir = path.join(__dirname, 'tmp');
if (!fs.existsSync(tmpDir)) {
    fs.mkdirSync(tmpDir);
}

// Initialize typescript-require with custom options
require('typescript-require')({
    targetES5: true,
    exitOnError: false, // Don't exit process immediately on error for demonstration
    tmpDir: tmpDir // Specify temporary directory
});

// Create a sample TypeScript file dynamically for demonstration
const tsContent = `
    export function lowercase(val: string): string {
        return val.toLowerCase();
    }

    export function uppercase(val: string): string {
        return val.toUpperCase();
    }
`;
const funcsPath = path.join(__dirname, 'funcs.ts');
fs.writeFileSync(funcsPath, tsContent);

// Require the TypeScript module
const funcs = require(funcsPath);

console.log(funcs.lowercase("HELLO FROM TYPESCRIPT!"));
console.log(funcs.uppercase("hello from typescript!"));

// Clean up generated files and directory
fs.unlinkSync(funcsPath);
// Optional: Clean up compiled JS files and source maps in tmpDir as well
fs.readdirSync(tmpDir).forEach(file => {
    if (file.startsWith('funcs.') && (file.endsWith('.js') || file.endsWith('.map'))) {
        fs.unlinkSync(path.join(tmpDir, file));
    }
});
fs.rmdirSync(tmpDir);