or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

code-compilation.md configuration-management.md esm-loader-support.md index.md runtime-registration.md

tile.json

Code Compilation

Direct compilation of TypeScript/JavaScript code with SWC transformation and optional TypeScript compiler fallback for complex cases.

Capabilities

Compile Function

Core compilation function that transforms TypeScript/JavaScript source code using SWC or falls back to the TypeScript compiler when needed.

/**
 * Compiles TypeScript/JavaScript source code to JavaScript
 * @param sourcecode - Source code to transform (undefined returns undefined)
 * @param filename - File path being transformed (used for configuration and source maps)
 * @param options - TypeScript compiler options with optional fallback function
 * @param async - Whether to use async transformation (defaults to false)
 * @returns Transformed JavaScript code with inline source maps, or undefined if sourcecode is null/undefined
 */
function compile(
  sourcecode: string | undefined,
  filename: string,
  options: ts.CompilerOptions & {
    fallbackToTs?: (filename: string) => boolean;
  }
): string | undefined;

function compile(
  sourcecode: string | undefined,
  filename: string,
  options: ts.CompilerOptions & {
    fallbackToTs?: (filename: string) => boolean;
  },
  async: false
): string | undefined;

function compile(
  sourcecode: string | undefined,
  filename: string,
  options: ts.CompilerOptions & {
    fallbackToTs?: (filename: string) => boolean;
  },
  async: true
): Promise<string | undefined>;

function compile(
  sourcecode: string | undefined,
  filename: string,
  options: ts.CompilerOptions & {
    fallbackToTs?: (filename: string) => boolean;
  },
  async: boolean
): string | undefined | Promise<string | undefined>;

Usage Examples:

import { compile } from "@swc-node/register/register";
import * as ts from "typescript";

// Synchronous compilation
const source = `
  interface User {
    name: string;
    age: number;
  }
  const user: User = { name: "Alice", age: 30 };
  export default user;
`;

const compiled = compile(source, "user.ts", {
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.CommonJS,
  sourceMap: true
});

console.log(compiled);
// Output: Compiled JavaScript with inline source map

// Asynchronous compilation
const compiledAsync = await compile(source, "user.ts", {
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.CommonJS
}, true);

// With TypeScript fallback for complex cases
const compiledWithFallback = compile(source, "complex.ts", {
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.CommonJS,
  fallbackToTs: (filename) => filename.includes("complex")
});

Transformation Modes

The compile function supports different transformation modes based on configuration:

SWC Transformation (Default)

Uses SWC for high-performance transformation:

// When SWCRC environment variable is not set
const compiled = compile(source, filename, {
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.CommonJS
});

SWCRC Configuration Mode

Uses .swcrc file for configuration when SWCRC environment variable is set:

// Set SWCRC=true in environment
process.env.SWCRC = "true";
process.env.SWC_CONFIG_FILE = "./custom.swcrc";

const compiled = compile(source, filename, {}); // Options ignored, uses .swcrc

TypeScript Compiler Fallback

Falls back to TypeScript compiler for files that SWC cannot handle:

const compiled = compile(source, filename, {
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.CommonJS,
  fallbackToTs: (filename) => {
    // Use TypeScript compiler for files with advanced features
    return filename.includes("decorators") || filename.includes("metadata");
  }
});

Source Map Integration

The compile function automatically integrates source maps for debugging:

Reads sourceMap and inlineSourceMap options from TypeScript configuration
Respects SWC_NODE_INLINE_SOURCE_MAP environment variable
Injects inline source maps into the compiled output
Integrates with @swc-node/sourcemap-support for runtime source map resolution

// Enable source maps
const compiled = compile(source, filename, {
  sourceMap: true,
  inlineSourceMap: true
});

// Source maps are automatically embedded in the output:
// //# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLC...

Error Handling

The compile function handles various error scenarios:

Returns undefined if sourcecode parameter is null or undefined
Falls back to TypeScript compiler if SWC transformation fails and fallbackToTs function returns true
Throws errors for unsupported module formats (e.g., SystemJS)
Provides detailed error messages with file context

// Error handling example
try {
  const compiled = compile(source, filename, {
    module: ts.ModuleKind.System // Throws TypeError
  });
} catch (error) {
  console.error("Compilation failed:", error.message);
  // "Do not support system kind module"
}

Version

Tile

Files