0
# Sucrase
1

2
Sucrase is a super-fast alternative to Babel that focuses on compiling non-standard language extensions (JSX, TypeScript, Flow) for modern JavaScript environments. Unlike Babel's comprehensive approach, Sucrase targets recent browsers and Node.js versions, achieving approximately 20x faster compilation speeds through a focused architecture that handles only essential transforms.
3

4
## Package Information
5

6
- **Package Name**: sucrase
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install sucrase`
10

11
## Core Imports
12

13
```typescript
14
import { transform, getVersion, getFormattedTokens } from "sucrase";
15
import type { Options, Transform, TransformResult } from "sucrase";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { transform, getVersion, getFormattedTokens } = require("sucrase");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { transform } from "sucrase";
28

29
// Transform TypeScript code to JavaScript
30
const result = transform(
31
  `const greeting: string = "Hello TypeScript!";`,
32
  {
33
    transforms: ["typescript"],
34
    filePath: "example.ts"
35
  }
36
);
37

38
console.log(result.code); // "const greeting = "Hello TypeScript!";"
39

40
// Transform JSX with TypeScript
41
const jsxResult = transform(
42
  `const element: JSX.Element = <div>Hello React!</div>;`,
43
  {
44
    transforms: ["typescript", "jsx"],
45
    filePath: "example.tsx"
46
  }
47
);
48

49
// Transform with source maps
50
const withSourceMap = transform(sourceCode, {
51
  transforms: ["typescript", "jsx"],
52
  sourceMapOptions: { compiledFilename: "output.js" },
53
  filePath: "input.tsx"
54
});
55
```
56

57
## Architecture
58

59
Sucrase is built around several key components:
60

61
- **Core Transform Engine**: Fast, focused parser and transformer for modern JS environments
62
- **Transform Pipeline**: Configurable transforms for JSX, TypeScript, Flow, imports, and more
63
- **Registration System**: Require hooks for automatic file transformation during development
64
- **Integration Ecosystem**: Plugins for Jest, Webpack, Gulp, and ts-node
65
- **CLI Tools**: Command-line utilities for batch transformation and development workflows
66

67
The library uses a forked and trimmed-down version of Babel's parser, optimized for speed over extensibility.
68

69
## Capabilities
70

71
### Core Transformation
72

73
Primary transformation engine that converts source code using specified transforms. Supports all major syntax extensions with optional source map generation.
74

75
```typescript { .api }
76
function transform(code: string, options: Options): TransformResult;
77

78
interface TransformResult {
79
  code: string;
80
  sourceMap?: RawSourceMap;
81
}
82

83
function getVersion(): string;
84
function getFormattedTokens(code: string, options: Options): string;
85
```
86

87
[Transformation](./transformation.md)
88

89
### Registration and Hooks
90

91
Automatic file transformation system using Node.js require hooks. Enables transparent compilation during development without build steps.
92

93
```typescript { .api }
94
function addHook(
95
  extension: string,
96
  sucraseOptions: Options,
97
  hookOptions?: HookOptions
98
): RevertFunction;
99

100
function registerAll(hookOptions?: HookOptions): RevertFunction;
101
function registerJS(hookOptions?: HookOptions): RevertFunction;
102
function registerJSX(hookOptions?: HookOptions): RevertFunction;
103
function registerTS(hookOptions?: HookOptions): RevertFunction;
104
function registerTSX(hookOptions?: HookOptions): RevertFunction;
105
```
106

107
[Registration and Hooks](./register.md)
108

109
### Command Line Interface
110

111
CLI tools for batch file transformation, project compilation, and development workflows. Includes both main CLI and Node.js wrapper.
112

113
```bash
114
sucrase -t typescript,jsx -d dist src
115
sucrase-node script.ts
116
```
117

118
[CLI and Tools](./cli.md)
119

120
### Build Tool Integrations
121

122
Ready-to-use plugins for popular build tools and test frameworks. Seamlessly integrates Sucrase into existing development workflows.
123

124
```typescript { .api }
125
// Jest transformer
126
function process(
127
  src: string,
128
  filename: string,
129
  options: TransformOptions<Partial<Options>>
130
): { code: string; map?: RawSourceMap | string | null };
131

132
// Webpack loader  
133
function loader(code: string): string;
134

135
// ts-node plugin
136
function create(createOptions): { transpile };
137
```
138

139
[Build Tool Integrations](./integrations.md)
140

141
## Common Transform Configurations
142

143
### TypeScript Only
144
```typescript
145
{ transforms: ["typescript"] }
146
```
147

148
### React with TypeScript
149
```typescript
150
{ transforms: ["typescript", "jsx"] }
151
```
152

153
### Legacy CommonJS Modules
154
```typescript
155
{ transforms: ["typescript", "jsx", "imports"] }
156
```
157

158
### Flow with JSX
159
```typescript
160
{ transforms: ["flow", "jsx"] }
161
```
162

163
### Jest Testing
164
```typescript
165
{ transforms: ["typescript", "jsx", "jest"] }
166
```