CLI and Tools

Sucrase provides command-line tools for batch file transformation, project compilation, and development workflows. The CLI is ideal for build scripts, CI/CD pipelines, and one-off transformations.

Capabilities

Main CLI Tool

The primary sucrase command provides comprehensive file transformation capabilities with extensive configuration options.

sucrase [options] <srcDir>

Basic Usage:

# Transform TypeScript files
sucrase -t typescript -d dist src

# Transform React TypeScript files  
sucrase -t typescript,jsx -d build src

# Transform with custom JSX runtime
sucrase -t typescript,jsx --jsx-runtime automatic -d dist src

# Transform specific project
sucrase -p ./tsconfig.json

CLI Options

Required Options:

• -d, --out-dir <out> - Output directory for compiled files
• -t, --transforms <transforms> - Comma-separated list of transforms to run

Source and Project Options:

• <srcDir> - Source directory to transform (required unless using -p)
• -p, --project <dir> - Compile TypeScript project using tsconfig.json in directory

Output Options:

• --out-extension <extension> - File extension for output files (default: "js")
• -q, --quiet - Don't print the names of converted files

Transform Configuration:

• --disable-es-transforms - Opt out of all ES syntax transforms
• --jsx-runtime <string> - JSX transformation mode ("classic", "automatic", "preserve")
• --production - Enable production mode (affects JSX output)
• --jsx-import-source <string> - Import path prefix for automatic JSX runtime
• --jsx-pragma <string> - Element creation function for classic JSX runtime
• --jsx-fragment-pragma <string> - Fragment component for classic JSX runtime

Import/Export Options:

• --keep-unused-imports - Disable automatic removal of type-only imports/exports
• --preserve-dynamic-import - Don't transpile dynamic import() to require()
• --inject-create-require-for-import-require - Use createRequire for TS import = require in ESM

Module Interop Options:

• --enable-legacy-typescript-module-interop - Use default TypeScript ESM/CJS interop
• --enable-legacy-babel5-module-interop - Use Babel 5 ESM/CJS interop strategy

Directory Options:

• --exclude-dirs <paths> - Comma-separated list of directory names to skip

CLI Examples

TypeScript Project Compilation:

# Using tsconfig.json
sucrase -p ./
sucrase -p ./packages/core

# Manual configuration
sucrase -t typescript -d dist src --out-extension js

React Development Build:

# Modern React with automatic JSX runtime
sucrase -t typescript,jsx \
  --jsx-runtime automatic \
  --jsx-import-source react \
  -d build src

# Classic React
sucrase -t typescript,jsx \
  --jsx-runtime classic \
  --jsx-pragma React.createElement \
  --jsx-fragment-pragma React.Fragment \
  -d build src

Node.js CommonJS Build:

# Convert ES modules to CommonJS
sucrase -t typescript,imports -d dist src

# Legacy module interop
sucrase -t typescript,imports \
  --enable-legacy-typescript-module-interop \
  -d dist src

Production Build:

# Optimized production build
sucrase -t typescript,jsx,imports \
  --production \
  --jsx-runtime automatic \
  --disable-es-transforms \
  -d dist src

Flow Project:

# Flow with JSX
sucrase -t flow,jsx,imports -d dist src

Exclude Directories:

# Skip test and spec directories
sucrase -t typescript -d dist src \
  --exclude-dirs __tests__,spec,stories

Node.js Wrapper Tool

The sucrase-node command provides a simple wrapper around Node.js that automatically registers Sucrase transforms.

sucrase-node <script>

Usage Examples:

# Run TypeScript files directly
sucrase-node app.ts
sucrase-node server.tsx

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

Features:

• Automatically registers all file types (.js, .jsx, .ts, .tsx)
• Uses default transform settings optimized for Node.js
• Simpler than manual require hook registration
• Ideal for development and quick testing

Build Integration Examples

Package.json Scripts:

{
  "scripts": {
    "build": "sucrase -t typescript,jsx -d dist src",
    "build:prod": "sucrase -t typescript,jsx,imports --production -d dist src",
    "dev": "sucrase-node src/server.ts",
    "test": "sucrase-node test/runner.ts"
  }
}

Docker Build:

# Dockerfile
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npx sucrase -t typescript,jsx,imports --production -d dist src
CMD ["node", "dist/server.js"]

GitHub Actions:

# .github/workflows/build.yml
- name: Build with Sucrase
  run: |
    npm install
    npx sucrase -t typescript,jsx -d dist src
    npm test

Error Handling

The CLI provides detailed error messages with file paths and line numbers:

$ sucrase -t typescript -d dist src
Error transforming src/app.ts: Unexpected token (3:15)
  1 | import { Component } from 'react';
  2 | 
> 3 | const App: Comp = () => <div>Hello</div>;
    |               ^
  4 | 
  5 | export default App;

Exit Codes

• 0 - Success
• 1 - Configuration error or transformation failure

Performance Monitoring

Use the --quiet flag to suppress file names for cleaner output in CI/CD:

# Quiet mode for automated builds
sucrase -t typescript,jsx -d dist src --quiet

# Verbose mode for debugging
sucrase -t typescript,jsx -d dist src

TypeScript Project Mode

When using -p, --project, Sucrase reads and respects many tsconfig.json options:

# Uses tsconfig.json in current directory
sucrase -p .

# Uses tsconfig.json in specified directory  
sucrase -p ./packages/core

Supported tsconfig.json options:

• compilerOptions.jsx - JSX mode
• compilerOptions.jsxFactory - JSX pragma
• compilerOptions.jsxFragmentFactory - JSX fragment pragma
• compilerOptions.jsxImportSource - JSX import source
• compilerOptions.esModuleInterop - Module interop behavior
• compilerOptions.verbatimModuleSyntax - Preserve imports/exports

Note: When using project mode, you cannot specify transforms, source directory, or certain other options as they are inferred from tsconfig.json.