tessl/npm-ts-node

TypeScript execution environment and REPL for Node.js with source map support

—

Pending

Overview

Eval results

Files

Transpiler Integration

Name: tessl/npm-ts-node
Author: tessl

Support for alternative transpilers like SWC for faster compilation and experimental features, providing pluggable compilation backends.

Capabilities

Transpiler Module Interface

Interface for third-party transpiler modules that can replace TypeScript's compiler.

/**
 * Third-party transpiler module interface
 */
interface TranspilerModule {
  /**
   * Create a transpiler instance
   * @param options - Configuration options for the transpiler
   * @returns Transpiler instance
   */
  create(options: CreateTranspilerOptions): Transpiler;
}

/**
 * Options for creating transpiler instances
 */
interface CreateTranspilerOptions {
  /** TypeScript service instance */
  service: Service;
  /** TypeScript configuration */
  config: _ts.ParsedCommandLine;
  /** File extension mapping */
  nodeModuleEmitKind?: NodeModuleEmitKind;
  /** Transform function */
  transformers?: _ts.CustomTransformers | ((program: _ts.Program) => _ts.CustomTransformers);
}

/**
 * Factory function for creating transpiler instances
 */
type TranspilerFactory = (options: CreateTranspilerOptions) => Transpiler;

/**
 * Node.js module emit types
 */
type NodeModuleEmitKind = 'nodeesm' | 'nodecjs';

Transpiler Instance Interface

Interface for transpiler instances that perform the actual code transformation.

/**
 * Transpiler instance interface
 */
interface Transpiler {
  /**
   * Transpile TypeScript code to JavaScript
   * @param code - TypeScript source code
   * @param options - Transpilation options
   * @returns Transpiled output
   */
  transpile(code: string, options: TranspileOptions): TranspileOutput;
}

/**
 * Options for transpilation
 */
interface TranspileOptions {
  /** Source file name */
  fileName: string;
  /** Line offset for error reporting */
  lineOffset?: number;
  /** Whether to emit decorators */
  experimentalDecorators?: boolean;
  /** Target ECMAScript version */
  target?: _ts.ScriptTarget;
  /** Module format */
  module?: _ts.ModuleKind;
}

/**
 * Transpiler output interface
 */
interface TranspileOutput {
  /** Transpiled JavaScript code */
  outputText: string;
  /** Source map if generated */
  sourceMapText?: string;
  /** Diagnostic messages */
  diagnostics?: ReadonlyArray<_ts.Diagnostic>;
}

Built-in SWC Transpiler

Built-in SWC (Speedy Web Compiler) integration for faster TypeScript compilation.

// Available as ts-node/transpilers/swc entry point
// Production-ready SWC transpiler integration

// Available as ts-node/transpilers/swc-experimental entry point  
// Experimental SWC features and optimizations

Usage Examples:

import { register } from "ts-node";

// Use SWC transpiler (recommended)
register({
  swc: true, // Shorthand for transpiler: 'ts-node/transpilers/swc'
  compilerOptions: {
    target: "es2020",
    module: "commonjs",
  }
});

// Use SWC explicitly
register({
  transpiler: 'ts-node/transpilers/swc',
  transpileOnly: true, // Required with custom transpilers
});

// Use experimental SWC features
register({
  transpiler: 'ts-node/transpilers/swc-experimental',
  transpileOnly: true,
});

Custom Transpiler Implementation

Creating a Custom Transpiler

// custom-transpiler.ts
import { TranspilerModule, CreateTranspilerOptions, Transpiler } from "ts-node";

const customTranspilerModule: TranspilerModule = {
  create(options: CreateTranspilerOptions): Transpiler {
    const { service, config } = options;
    
    return {
      transpile(code: string, transpileOptions: TranspileOptions) {
        // Custom transpilation logic
        const result = customCompile(code, {
          target: transpileOptions.target,
          module: transpileOptions.module,
          fileName: transpileOptions.fileName,
          // Use ts-node's TypeScript configuration
          ...config.options
        });
        
        return {
          outputText: result.code,
          sourceMapText: result.map,
          diagnostics: result.diagnostics || []
        };
      }
    };
  }
};

module.exports = customTranspilerModule;

function customCompile(code: string, options: any) {
  // Implement your custom compilation logic
  // This could use Babel, esbuild, or any other compiler
  return {
    code: '// Compiled code here',
    map: undefined,
    diagnostics: []
  };
}

Usage:

import { register } from "ts-node";

register({
  transpiler: './custom-transpiler.ts',
  transpileOnly: true,
});

Babel Transpiler Example

// babel-transpiler.ts
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
import { transform } from "@babel/core";

const babelTranspilerModule: TranspilerModule = {
  create(options: CreateTranspilerOptions) {
    return {
      transpile(code: string, transpileOptions) {
        const result = transform(code, {
          filename: transpileOptions.fileName,
          presets: [
            ['@babel/preset-typescript', {
              target: transpileOptions.target
            }],
            ['@babel/preset-env', {
              targets: { node: 'current' }
            }]
          ],
          sourceMaps: true,
        });
        
        return {
          outputText: result?.code || '',
          sourceMapText: JSON.stringify(result?.map),
        };
      }
    };
  }
};

module.exports = babelTranspilerModule;

esbuild Transpiler Example

// esbuild-transpiler.ts
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
import { transformSync } from "esbuild";

const esbuildTranspilerModule: TranspilerModule = {
  create(options: CreateTranspilerOptions) {
    return {
      transpile(code: string, transpileOptions) {
        const result = transformSync(code, {
          loader: 'ts',
          target: 'node16',
          format: 'cjs',
          sourcemap: 'inline',
          sourcefile: transpileOptions.fileName,
        });
        
        return {
          outputText: result.code,
          sourceMapText: undefined, // Inline source map
        };
      }
    };
  }
};

module.exports = esbuildTranspilerModule;

Transpiler Configuration

SWC Configuration

import { register } from "ts-node";

// SWC with custom configuration
register({
  transpiler: ['ts-node/transpilers/swc', {
    // SWC-specific options
    jsc: {
      target: 'es2020',
      parser: {
        syntax: 'typescript',
        decorators: true,
      },
      transform: {
        decoratorMetadata: true,
      },
    },
    module: {
      type: 'commonjs',
    },
  }],
  transpileOnly: true,
});

Environment-Based Transpiler Selection

import { register } from "ts-node";

const isDevelopment = process.env.NODE_ENV === 'development';
const useSwc = process.env.USE_SWC === 'true';

register({
  // Use SWC in development for speed, TypeScript in production for accuracy
  transpiler: isDevelopment && useSwc ? 'ts-node/transpilers/swc' : undefined,
  transpileOnly: isDevelopment,
  typeCheck: !isDevelopment,
  compilerOptions: {
    target: "es2020",
    module: "commonjs",
    strict: !isDevelopment,
  }
});

Advanced Transpiler Usage

Transpiler with Custom Transformers

// transformer-transpiler.ts
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
import * as ts from "typescript";

const transformerTranspilerModule: TranspilerModule = {
  create(options: CreateTranspilerOptions) {
    const { service } = options;
    
    // Custom AST transformers
    const customTransformers: ts.CustomTransformers = {
      before: [
        // Add custom before transformers
        (context: ts.TransformationContext) => {
          return (sourceFile: ts.SourceFile) => {
            // Custom AST transformation logic
            return sourceFile;
          };
        }
      ],
      after: [
        // Add custom after transformers
      ]
    };
    
    return {
      transpile(code: string, transpileOptions) {
        // Use TypeScript compiler with custom transformers
        const result = ts.transpileModule(code, {
          compilerOptions: {
            target: transpileOptions.target,
            module: transpileOptions.module,
          },
          transformers: customTransformers,
          fileName: transpileOptions.fileName,
        });
        
        return {
          outputText: result.outputText,
          sourceMapText: result.sourceMapText,
          diagnostics: result.diagnostics,
        };
      }
    };
  }
};

module.exports = transformerTranspilerModule;

Performance Benchmarking

// benchmark-transpiler.ts
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";
import { performance } from "perf_hooks";

function createBenchmarkTranspiler(baseTranspiler: string): TranspilerModule {
  return {
    create(options: CreateTranspilerOptions) {
      const baseModule = require(baseTranspiler);
      const base = baseModule.create(options);
      
      return {
        transpile(code: string, transpileOptions) {
          const start = performance.now();
          const result = base.transpile(code, transpileOptions);
          const end = performance.now();
          
          console.log(`Transpiled ${transpileOptions.fileName} in ${end - start}ms`);
          
          return result;
        }
      };
    }
  };
}

module.exports = createBenchmarkTranspiler('ts-node/transpilers/swc');

Transpiler Error Handling

// error-handling-transpiler.ts
import { TranspilerModule, CreateTranspilerOptions } from "ts-node";

const errorHandlingTranspilerModule: TranspilerModule = {
  create(options: CreateTranspilerOptions) {
    const baseModule = require('ts-node/transpilers/swc');
    const base = baseModule.create(options);
    
    return {
      transpile(code: string, transpileOptions) {
        try {
          return base.transpile(code, transpileOptions);
        } catch (error) {
          console.error(`Transpilation error in ${transpileOptions.fileName}:`, error);
          
          // Fallback to TypeScript compiler
          const ts = require('typescript');
          const result = ts.transpileModule(code, {
            compilerOptions: {
              target: transpileOptions.target,
              module: transpileOptions.module,
            },
            fileName: transpileOptions.fileName,
          });
          
          return {
            outputText: result.outputText,
            sourceMapText: result.sourceMapText,
            diagnostics: result.diagnostics,
          };
        }
      }
    };
  }
};

module.exports = errorHandlingTranspilerModule;

CLI Integration with Transpilers

# Use SWC transpiler via CLI
ts-node --swc script.ts

# Use custom transpiler
ts-node --transpiler ./custom-transpiler.js script.ts

# Use transpiler with configuration
ts-node --transpiler '[\"./custom-transpiler.js\",{\"option\":\"value\"}]' script.ts

{
  "scripts": {
    "dev:swc": "ts-node --swc src/index.ts",
    "dev:babel": "ts-node --transpiler ./transpilers/babel-transpiler.js src/index.ts",
    "dev:esbuild": "ts-node --transpiler ./transpilers/esbuild-transpiler.js src/index.ts"
  }
}

Install with Tessl CLI