or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli.md index.md integrations.md register.md transformation.md

tile.json

Registration and Hooks

The registration system provides automatic file transformation using Node.js require hooks. This enables transparent compilation during development without explicit build steps, making it ideal for development workflows and testing environments.

Capabilities

Hook Management

Core hook management function that registers file extension handlers with custom transform options.

/**
 * Add a require hook for a specific file extension
 * @param extension - File extension to handle (e.g., ".ts", ".tsx")
 * @param sucraseOptions - Transform options to apply
 * @param hookOptions - Optional hook behavior configuration
 * @returns Function to remove the hook
 */
function addHook(
  extension: string,
  sucraseOptions: Options,
  hookOptions?: HookOptions
): RevertFunction;

interface HookOptions {
  /** Custom function to determine if a file should be transformed */
  matcher?: (code: string) => boolean;
  /** Skip transformation of files in node_modules */
  ignoreNodeModules?: boolean;
}

type RevertFunction = () => void;

Usage Example:

import { addHook } from "sucrase/register";

// Register TypeScript transformation for .ts files
const revertTS = addHook(".ts", 
  { transforms: ["typescript"] },
  { ignoreNodeModules: true }
);

// Register JSX + TypeScript for .tsx files with custom matcher
const revertTSX = addHook(".tsx", 
  { transforms: ["typescript", "jsx"] },
  { 
    matcher: (code) => code.includes("export") || code.includes("import"),
    ignoreNodeModules: true 
  }
);

// Remove hooks when done
revertTS();
revertTSX();

Convenience Registration Functions

Pre-configured registration functions for common file types and use cases.

/**
 * Register transformation for .js files (Flow + JSX + imports)
 * @param hookOptions - Optional hook configuration
 * @returns Function to remove the hook
 */
function registerJS(hookOptions?: HookOptions): RevertFunction;

/**
 * Register transformation for .jsx files (Flow + JSX + imports)
 * @param hookOptions - Optional hook configuration
 * @returns Function to remove the hook
 */
function registerJSX(hookOptions?: HookOptions): RevertFunction;

/**
 * Register transformation for .ts files (TypeScript + imports)
 * @param hookOptions - Optional hook configuration
 * @returns Function to remove the hook
 */
function registerTS(hookOptions?: HookOptions): RevertFunction;

/**
 * Register transformation for .tsx files (TypeScript + JSX + imports)
 * @param hookOptions - Optional hook configuration
 * @returns Function to remove the hook
 */
function registerTSX(hookOptions?: HookOptions): RevertFunction;

/**
 * Register .ts files with legacy TypeScript module interop
 * @param hookOptions - Optional hook configuration
 * @returns Function to remove the hook
 */
function registerTSLegacyModuleInterop(hookOptions?: HookOptions): RevertFunction;

/**
 * Register .tsx files with legacy TypeScript module interop
 * @param hookOptions - Optional hook configuration
 * @returns Function to remove the hook
 */
function registerTSXLegacyModuleInterop(hookOptions?: HookOptions): RevertFunction;

/**
 * Register all common file types (.js, .jsx, .ts, .tsx)
 * @param hookOptions - Optional hook configuration
 * @returns Function to remove all hooks
 */
function registerAll(hookOptions?: HookOptions): RevertFunction;

Usage Examples:

import { registerAll, registerTS, registerTSX } from "sucrase/register";

// Register all file types at once
const revertAll = registerAll({ ignoreNodeModules: true });

// Or register specific types
const revertTS = registerTS();
const revertTSX = registerTSX();

// Remove hooks
revertAll(); // or revertTS() + revertTSX()

Direct Register Modules

Pre-built registration modules that can be required directly for immediate setup.

Main Register Module

require("sucrase/register"); // Registers all file types (.js, .jsx, .ts, .tsx)

File-Specific Register Modules

require("sucrase/register/js");   // Register .js files only
require("sucrase/register/jsx");  // Register .jsx files only
require("sucrase/register/ts");   // Register .ts files only
require("sucrase/register/tsx");  // Register .tsx files only

Legacy Module Interop

require("sucrase/register/ts-legacy-module-interop");   // .ts with legacy interop
require("sucrase/register/tsx-legacy-module-interop");  // .tsx with legacy interop

Environment Configuration

Environment Variable Override

The registration system supports runtime configuration via environment variables.

# Override options for all registered hooks
export SUCRASE_OPTIONS='{"production":true,"jsxRuntime":"automatic"}'
node -r sucrase/register app.tsx

The SUCRASE_OPTIONS environment variable should contain a JSON string that will be merged with the hook's base options.

Command Line Registration

Using Node.js -r Flag

# Register all file types
node -r sucrase/register script.ts

# Register specific file types
node -r sucrase/register/ts script.ts
node -r sucrase/register/tsx app.tsx

Using sucrase-node Binary

# Simple wrapper that registers all types automatically
sucrase-node script.ts
sucrase-node app.tsx

# Equivalent to: node -r sucrase/register script.ts

Common Registration Patterns

Development Setup

// development.js - development entry point
import { registerAll } from "sucrase/register";

// Register all file types for development
registerAll({ ignoreNodeModules: true });

// Import your main application
import("./src/app.tsx").then(app => app.start());

Testing Setup

// test-setup.js
import { registerAll } from "sucrase/register";

// Register for test files
registerAll({
  ignoreNodeModules: true,
  matcher: (code) => {
    // Only transform files that look like source code
    return code.includes("import") || code.includes("export");
  }
});

Conditional Registration

// Only register in development
if (process.env.NODE_ENV === "development") {
  require("sucrase/register");
}

Custom Extension Handling

import { addHook } from "sucrase/register";

// Handle .vue files with TypeScript
addHook(".vue", {
  transforms: ["typescript", "jsx"]
}, {
  matcher: (code) => code.includes("<script lang=\"ts\">")
});

// Handle .mjs files
addHook(".mjs", {
  transforms: ["jsx"],
  preserveDynamicImport: true
});

Error Handling and Debugging

The registration system automatically includes file paths in error messages and can generate source maps for debugging.

import { addHook } from "sucrase/register";

// Enable source maps for debugging
addHook(".ts", {
  transforms: ["typescript"],
  sourceMapOptions: { compiledFilename: "compiled.js" }
});

When transformation fails, errors will include the original file path and line numbers for easier debugging.