tessl/npm-sucrase

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

—

Pending

Overview

Eval results

Files

Build Tool Integrations

Name: tessl/npm-sucrase
Author: tessl

Sucrase provides ready-to-use plugins for popular build tools and test frameworks, enabling seamless integration into existing development workflows with minimal configuration.

Capabilities

Jest Integration

Jest transformer that automatically handles TypeScript, JSX, and other syntax extensions during test execution.

Package: @sucrase/jest-plugin

/**
 * Jest transformer function
 * @param src - Source code to transform
 * @param filename - File path being transformed
 * @param options - Jest transform options with optional Sucrase configuration
 * @returns Transformed code with source map
 */
function process(
  src: string,
  filename: string,
  options: TransformOptions<Partial<Options>>
): { code: string; map?: RawSourceMap | string | null };

// Default export provides Jest-compatible transformer
export default { process };

interface TransformOptions<T> {
  transformerConfig?: T;
  supportsStaticESM?: boolean;
  supportsDynamicImport?: boolean;
}

Jest Configuration:

// jest.config.js
module.exports = {
  transform: {
    "\\.(ts|tsx|js|jsx)$": "@sucrase/jest-plugin"
  },
  transformerConfig: {
    // Optional Sucrase options
    production: false,
    disableESTransforms: true
  }
};

Usage Examples:

// Basic setup for TypeScript + React
module.exports = {
  transform: {
    "\\.(ts|tsx)$": "@sucrase/jest-plugin"
  }
};

// With custom options
module.exports = {
  transform: {
    "\\.(ts|tsx|js|jsx)$": "@sucrase/jest-plugin"
  },
  transformerConfig: {
    keepUnusedImports: true,
    jsxRuntime: "automatic"
  }
};

// ESM support
module.exports = {
  extensionsToTreatAsEsm: ['.ts', '.tsx'],
  transform: {
    "\\.(ts|tsx)$": "@sucrase/jest-plugin"
  },
  transformerConfig: {
    preserveDynamicImport: true
  }
};

Webpack Integration

Webpack loader that transforms files during the build process.

Package: @sucrase/webpack-loader

/**
 * Webpack loader function
 * @param code - Source code to transform
 * @returns Transformed code
 * @this - Webpack loader context with options
 */
function loader(this: LoaderContext, code: string): string;

interface LoaderContext {
  getOptions(): Options;
  getRemainingRequest(): string;
}

Webpack Configuration:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/,
        use: {
          loader: "@sucrase/webpack-loader",
          options: {
            transforms: ["typescript", "jsx"]
          }
        },
        exclude: /node_modules/
      }
    ]
  }
};

Usage Examples:

// TypeScript only
{
  test: /\.ts$/,
  use: {
    loader: "@sucrase/webpack-loader",
    options: {
      transforms: ["typescript"]
    }
  }
}

// React with TypeScript
{
  test: /\.(ts|tsx)$/,
  use: {
    loader: "@sucrase/webpack-loader",
    options: {
      transforms: ["typescript", "jsx"],
      jsxRuntime: "automatic",
      production: process.env.NODE_ENV === "production"
    }
  }
}

// Flow with JSX
{
  test: /\.(js|jsx)$/,
  use: {
    loader: "@sucrase/webpack-loader",
    options: {
      transforms: ["flow", "jsx", "imports"]
    }
  }
}

// Multiple loaders chain
{
  test: /\.tsx?$/,
  use: [
    {
      loader: "@sucrase/webpack-loader",
      options: {
        transforms: ["typescript", "jsx"]
      }
    }
  ]
}

Gulp Integration

Gulp plugin for streaming file transformation in build pipelines.

Package: @sucrase/gulp-plugin

/**
 * Create Gulp transform stream
 * @param options - Sucrase transform options
 * @returns Gulp-compatible transform stream
 */
function gulpSucrase(options: Options): NodeJS.ReadWriteStream;

Gulp Configuration:

// gulpfile.js
const gulp = require("gulp");
const sucrase = require("@sucrase/gulp-plugin");

gulp.task("build", () => {
  return gulp.src("src/**/*.ts")
    .pipe(sucrase({
      transforms: ["typescript"]
    }))
    .pipe(gulp.dest("dist"));
});

Usage Examples:

// TypeScript compilation
gulp.task("typescript", () => {
  return gulp.src("src/**/*.ts")
    .pipe(sucrase({
      transforms: ["typescript"]
    }))
    .pipe(gulp.dest("dist"));
});

// React with TypeScript
gulp.task("react", () => {
  return gulp.src("src/**/*.{ts,tsx}")
    .pipe(sucrase({
      transforms: ["typescript", "jsx"],
      jsxRuntime: "automatic"
    }))
    .pipe(gulp.dest("build"));
});

// Flow transformation
gulp.task("flow", () => {
  return gulp.src("src/**/*.{js,jsx}")
    .pipe(sucrase({
      transforms: ["flow", "jsx", "imports"]
    }))
    .pipe(gulp.dest("lib"));
});

// With source maps and error handling
gulp.task("build-with-maps", () => {
  return gulp.src("src/**/*.ts")
    .pipe(sucrase({
      transforms: ["typescript"],
      sourceMapOptions: { compiledFilename: "app.js" }
    }))
    .on("error", (error) => {
      console.error("Sucrase error:", error.message);
    })
    .pipe(gulp.dest("dist"));
});

TypeScript Node Integration

ts-node transpiler plugin that allows ts-node to use Sucrase for faster TypeScript compilation.

Package: Built into main sucrase package

/**
 * Create ts-node transpiler plugin
 * @param createOptions - ts-node plugin creation options
 * @returns Transpiler plugin with transpile method
 */
function create(createOptions: TSNodeCreateOptions): {
  transpile(input: string, transpileOptions: TSNodeTranspileOptions): {
    outputText: string;
    sourceMapText: string;
  };
};

interface TSNodeCreateOptions {
  nodeModuleEmitKind?: "commonjs" | "esm" | "nodecjs" | "nodeesm";
  service: {
    config: {
      options: {
        module?: number;
        jsx?: number;
        jsxFactory?: string;
        jsxFragmentFactory?: string;
        jsxImportSource?: string;
        esModuleInterop?: boolean;
        verbatimModuleSyntax?: boolean;
      };
    };
  };
}

interface TSNodeTranspileOptions {
  fileName: string;
}

ts-node Configuration:

// tsconfig.json
{
  "ts-node": {
    "transpiler": "sucrase/ts-node-plugin"
  }
}

Command Line Usage:

# Use Sucrase as ts-node transpiler
npx ts-node --transpiler sucrase/ts-node-plugin script.ts

# Or set in tsconfig.json and run normally
npx ts-node script.ts

Usage Examples:

// tsconfig.json - Basic setup
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "jsx": "react-jsx"
  },
  "ts-node": {
    "transpiler": "sucrase/ts-node-plugin"
  }
}

// tsconfig.json - ESM setup
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "esnext",
    "jsx": "react-jsx"
  },
  "ts-node": {
    "transpiler": "sucrase/ts-node-plugin",
    "esm": true
  }
}

Supported tsconfig.json Options:

compilerOptions.module - Module system (CommonJS/ESM)
compilerOptions.jsx - JSX transformation mode
compilerOptions.jsxFactory - JSX pragma function
compilerOptions.jsxFragmentFactory - JSX fragment pragma
compilerOptions.jsxImportSource - JSX import source
compilerOptions.esModuleInterop - Module interop behavior
compilerOptions.verbatimModuleSyntax - Preserve imports/exports

Integration Patterns

Multi-Tool Setup

// Example using multiple integrations
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/,
        use: "@sucrase/webpack-loader",
        options: { transforms: ["typescript", "jsx"] }
      }
    ]
  }
};

// jest.config.js
module.exports = {
  transform: {
    "\\.(ts|tsx)$": "@sucrase/jest-plugin"
  }
};

// gulpfile.js
const sucrase = require("@sucrase/gulp-plugin");
gulp.task("build", () => {
  return gulp.src("src/**/*.ts")
    .pipe(sucrase({ transforms: ["typescript"] }))
    .pipe(gulp.dest("dist"));
});

Development vs Production

// Different configurations for different environments
const isProduction = process.env.NODE_ENV === "production";

// Webpack config
const sucraseOptions = {
  transforms: ["typescript", "jsx"],
  production: isProduction,
  jsxRuntime: isProduction ? "automatic" : "classic"
};

// Jest config
const jestSucraseOptions = {
  disableESTransforms: true,
  keepUnusedImports: !isProduction
};

Error Handling

All integrations provide detailed error messages with file paths and line numbers:

// Webpack loader error
Module build failed (from @sucrase/webpack-loader):
Error transforming src/App.tsx: Unexpected token (line 15:20)

// Jest transformer error  
Transform failed for src/utils.ts:
SyntaxError: Unexpected token 'interface' (line 5:0)

// Gulp plugin error
[gulpSucrase] Error in plugin "@sucrase/gulp-plugin"
Message: Error transforming src/component.ts: Invalid syntax

Performance Optimization

All integrations are optimized for speed, but can be further tuned:

// Webpack - exclude node_modules for better performance
{
  test: /\.(ts|tsx)$/,
  use: "@sucrase/webpack-loader",
  exclude: /node_modules/,
  options: {
    transforms: ["typescript", "jsx"],
    disableESTransforms: true // Skip unnecessary transforms
  }
}

// Jest - only transform what's needed
{
  transform: {
    "^.+\\.(ts|tsx)$": "@sucrase/jest-plugin"
  },
  transformIgnorePatterns: [
    "node_modules/(?!(some-esm-module)/)"
  ]
}

Install with Tessl CLI