tessl/npm-sucrase

Super-fast alternative to Babel for when you can target modern JS runtimes

—

Pending

Overview

Eval results

Files

Core Transformation

Name: tessl/npm-sucrase
Author: tessl

The core transformation system provides fast, focused compilation of modern JavaScript syntax extensions. All transformation is performed through the main transform function with extensive configuration options.

Capabilities

Transform Function

Primary transformation function that converts source code using specified transforms.

/**
 * Transform source code using specified transforms
 * @param code - Source code string to transform
 * @param options - Transform configuration options
 * @returns Transform result with converted code and optional source map
 */
function transform(code: string, options: Options): TransformResult;

interface TransformResult {
  code: string;
  sourceMap?: RawSourceMap;
}

interface RawSourceMap {
  version: number;
  sources: string[];
  names: string[];
  mappings: string;
  file?: string;
  sourceRoot?: string;
  sourcesContent?: (string | null)[];
}

Usage Example:

import { transform } from "sucrase";

// Basic TypeScript transformation
const result = transform(
  `function greet(name: string): string { return \`Hello, \${name}!\`; }`,
  { transforms: ["typescript"] }
);

// JSX with TypeScript and source maps
const jsxResult = transform(
  `const Component: React.FC = () => <div>Hello</div>;`,
  {
    transforms: ["typescript", "jsx"],
    sourceMapOptions: { compiledFilename: "Component.js" },
    filePath: "Component.tsx"
  }
);

Version Information

Returns the current Sucrase version string.

/**
 * Get the current Sucrase version
 * @returns Version string (e.g., "3.35.0")
 */
function getVersion(): string;

Token Debugging

Returns a formatted string representation of parsed tokens for debugging purposes.

/**
 * Get formatted token representation for debugging
 * @param code - Source code to tokenize
 * @param options - Parsing options
 * @returns Formatted token string
 */
function getFormattedTokens(code: string, options: Options): string;

Transform Options

Core Options Interface

Complete configuration interface for all transformation options.

interface Options {
  /** Array of transform names to apply */
  transforms: Array<Transform>;
  /** Opt out of all ES syntax transformations */
  disableESTransforms?: boolean;
  /** JSX transformation mode */
  jsxRuntime?: "classic" | "automatic" | "preserve";
  /** Compile for production (affects JSX transform) */
  production?: boolean;
  /** Custom JSX import source for automatic runtime */
  jsxImportSource?: string;
  /** Custom JSX pragma function for classic runtime */
  jsxPragma?: string;
  /** Custom JSX fragment pragma for classic runtime */
  jsxFragmentPragma?: string;
  /** Preserve type-only imports and exports */
  keepUnusedImports?: boolean;
  /** Don't transform dynamic import() expressions */
  preserveDynamicImport?: boolean;
  /** Use createRequire for TS import = require in ESM */
  injectCreateRequireForImportRequire?: boolean;
  /** Use TypeScript's legacy module interop behavior */
  enableLegacyTypeScriptModuleInterop?: boolean;
  /** Use Babel 5's legacy module interop behavior */
  enableLegacyBabel5ModuleInterop?: boolean;
  /** Source map generation options */
  sourceMapOptions?: SourceMapOptions;
  /** File path for error messages and source maps */
  filePath?: string;
}

Usage Examples:

// Minimal configuration
const basic: Options = {
  transforms: ["typescript"]
};

// Production React configuration
const production: Options = {
  transforms: ["typescript", "jsx"],
  jsxRuntime: "automatic",
  production: true,
  sourceMapOptions: { compiledFilename: "bundle.js" }
};

// Legacy CommonJS configuration
const legacy: Options = {
  transforms: ["typescript", "jsx", "imports"],
  enableLegacyTypeScriptModuleInterop: true,
  jsxRuntime: "classic",
  jsxPragma: "React.createElement"
};

Transform Types

Available transform names that can be combined in the transforms array.

type Transform = 
  | "jsx"           // JSX syntax transformation
  | "typescript"    // TypeScript type removal and features
  | "flow"          // Flow type annotation removal
  | "imports"       // ES modules to CommonJS conversion
  | "react-hot-loader" // React hot loader support
  | "jest";         // Jest method hoisting

Transform Descriptions:

jsx: Transforms JSX syntax to function calls (React.createElement or jsx function)
typescript: Removes TypeScript types, handles enums, namespace, and TS-specific syntax
flow: Removes Flow type annotations and syntax
imports: Converts ES modules (import/export) to CommonJS (require/module.exports)
react-hot-loader: Adds React Hot Loader compatibility transformations
jest: Hoists jest method calls above imports for proper test setup

Source Map Options

Configuration for source map generation.

interface SourceMapOptions {
  /** 
   * The name to use in the "file" field of the source map.
   * Should be the name of the compiled output file.
   */
  compiledFilename: string;
}

Options Validation

Validates an options object against the expected schema.

/**
 * Validate transform options
 * @param options - Options object to validate
 * @throws Error if options are invalid
 */
function validateOptions(options: Options): void;

Transform Context

Internal transformation context used during processing (exported for advanced use cases).

interface SucraseContext {
  tokenProcessor: TokenProcessor;
  scopes: Array<Scope>;
  nameManager: NameManager;
  importProcessor: CJSImportProcessor | null;
  helperManager: HelperManager;
}

Advanced Configuration Examples

Modern ESM Build

const esmConfig: Options = {
  transforms: ["typescript", "jsx"],
  jsxRuntime: "automatic",
  injectCreateRequireForImportRequire: true,
  preserveDynamicImport: true
};

Legacy Browser Support

const legacyConfig: Options = {
  transforms: ["typescript", "jsx", "imports"],
  jsxRuntime: "classic",
  jsxPragma: "React.createElement",
  jsxFragmentPragma: "React.Fragment",
  enableLegacyBabel5ModuleInterop: true
};

Testing Configuration

const testConfig: Options = {
  transforms: ["typescript", "jsx", "jest"],
  disableESTransforms: true,
  keepUnusedImports: false
};

Development with Source Maps

const devConfig: Options = {
  transforms: ["typescript", "jsx"],
  sourceMapOptions: { compiledFilename: "app.js" },
  filePath: "src/app.tsx"
};

Install with Tessl CLI

npx tessl i tessl/npm-sucrase

docs