0
# Build Tool Integrations
1

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

4
## Capabilities
5

6
### Jest Integration
7

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

10
**Package:** `@sucrase/jest-plugin`
11

12
```typescript { .api }
13
/**
14
 * Jest transformer function
15
 * @param src - Source code to transform
16
 * @param filename - File path being transformed
17
 * @param options - Jest transform options with optional Sucrase configuration
18
 * @returns Transformed code with source map
19
 */
20
function process(
21
  src: string,
22
  filename: string,
23
  options: TransformOptions<Partial<Options>>
24
): { code: string; map?: RawSourceMap | string | null };
25

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

29
interface TransformOptions<T> {
30
  transformerConfig?: T;
31
  supportsStaticESM?: boolean;
32
  supportsDynamicImport?: boolean;
33
}
34
```
35

36
**Jest Configuration:**
37

38
```javascript
39
// jest.config.js
40
module.exports = {
41
  transform: {
42
    "\\.(ts|tsx|js|jsx)$": "@sucrase/jest-plugin"
43
  },
44
  transformerConfig: {
45
    // Optional Sucrase options
46
    production: false,
47
    disableESTransforms: true
48
  }
49
};
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
// Basic setup for TypeScript + React
56
module.exports = {
57
  transform: {
58
    "\\.(ts|tsx)$": "@sucrase/jest-plugin"
59
  }
60
};
61

62
// With custom options
63
module.exports = {
64
  transform: {
65
    "\\.(ts|tsx|js|jsx)$": "@sucrase/jest-plugin"
66
  },
67
  transformerConfig: {
68
    keepUnusedImports: true,
69
    jsxRuntime: "automatic"
70
  }
71
};
72

73
// ESM support
74
module.exports = {
75
  extensionsToTreatAsEsm: ['.ts', '.tsx'],
76
  transform: {
77
    "\\.(ts|tsx)$": "@sucrase/jest-plugin"
78
  },
79
  transformerConfig: {
80
    preserveDynamicImport: true
81
  }
82
};
83
```
84

85
### Webpack Integration
86

87
Webpack loader that transforms files during the build process.
88

89
**Package:** `@sucrase/webpack-loader`
90

91
```typescript { .api }
92
/**
93
 * Webpack loader function
94
 * @param code - Source code to transform
95
 * @returns Transformed code
96
 * @this - Webpack loader context with options
97
 */
98
function loader(this: LoaderContext, code: string): string;
99

100
interface LoaderContext {
101
  getOptions(): Options;
102
  getRemainingRequest(): string;
103
}
104
```
105

106
**Webpack Configuration:**
107

108
```javascript
109
// webpack.config.js
110
module.exports = {
111
  module: {
112
    rules: [
113
      {
114
        test: /\.(ts|tsx)$/,
115
        use: {
116
          loader: "@sucrase/webpack-loader",
117
          options: {
118
            transforms: ["typescript", "jsx"]
119
          }
120
        },
121
        exclude: /node_modules/
122
      }
123
    ]
124
  }
125
};
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
// TypeScript only
132
{
133
  test: /\.ts$/,
134
  use: {
135
    loader: "@sucrase/webpack-loader",
136
    options: {
137
      transforms: ["typescript"]
138
    }
139
  }
140
}
141

142
// React with TypeScript
143
{
144
  test: /\.(ts|tsx)$/,
145
  use: {
146
    loader: "@sucrase/webpack-loader",
147
    options: {
148
      transforms: ["typescript", "jsx"],
149
      jsxRuntime: "automatic",
150
      production: process.env.NODE_ENV === "production"
151
    }
152
  }
153
}
154

155
// Flow with JSX
156
{
157
  test: /\.(js|jsx)$/,
158
  use: {
159
    loader: "@sucrase/webpack-loader",
160
    options: {
161
      transforms: ["flow", "jsx", "imports"]
162
    }
163
  }
164
}
165

166
// Multiple loaders chain
167
{
168
  test: /\.tsx?$/,
169
  use: [
170
    {
171
      loader: "@sucrase/webpack-loader",
172
      options: {
173
        transforms: ["typescript", "jsx"]
174
      }
175
    }
176
  ]
177
}
178
```
179

180
### Gulp Integration
181

182
Gulp plugin for streaming file transformation in build pipelines.
183

184
**Package:** `@sucrase/gulp-plugin`
185

186
```typescript { .api }
187
/**
188
 * Create Gulp transform stream
189
 * @param options - Sucrase transform options
190
 * @returns Gulp-compatible transform stream
191
 */
192
function gulpSucrase(options: Options): NodeJS.ReadWriteStream;
193
```
194

195
**Gulp Configuration:**
196

197
```javascript
198
// gulpfile.js
199
const gulp = require("gulp");
200
const sucrase = require("@sucrase/gulp-plugin");
201

202
gulp.task("build", () => {
203
  return gulp.src("src/**/*.ts")
204
    .pipe(sucrase({
205
      transforms: ["typescript"]
206
    }))
207
    .pipe(gulp.dest("dist"));
208
});
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
// TypeScript compilation
215
gulp.task("typescript", () => {
216
  return gulp.src("src/**/*.ts")
217
    .pipe(sucrase({
218
      transforms: ["typescript"]
219
    }))
220
    .pipe(gulp.dest("dist"));
221
});
222

223
// React with TypeScript
224
gulp.task("react", () => {
225
  return gulp.src("src/**/*.{ts,tsx}")
226
    .pipe(sucrase({
227
      transforms: ["typescript", "jsx"],
228
      jsxRuntime: "automatic"
229
    }))
230
    .pipe(gulp.dest("build"));
231
});
232

233
// Flow transformation
234
gulp.task("flow", () => {
235
  return gulp.src("src/**/*.{js,jsx}")
236
    .pipe(sucrase({
237
      transforms: ["flow", "jsx", "imports"]
238
    }))
239
    .pipe(gulp.dest("lib"));
240
});
241

242
// With source maps and error handling
243
gulp.task("build-with-maps", () => {
244
  return gulp.src("src/**/*.ts")
245
    .pipe(sucrase({
246
      transforms: ["typescript"],
247
      sourceMapOptions: { compiledFilename: "app.js" }
248
    }))
249
    .on("error", (error) => {
250
      console.error("Sucrase error:", error.message);
251
    })
252
    .pipe(gulp.dest("dist"));
253
});
254
```
255

256
### TypeScript Node Integration
257

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

260
**Package:** Built into main sucrase package
261

262
```typescript { .api }
263
/**
264
 * Create ts-node transpiler plugin
265
 * @param createOptions - ts-node plugin creation options
266
 * @returns Transpiler plugin with transpile method
267
 */
268
function create(createOptions: TSNodeCreateOptions): {
269
  transpile(input: string, transpileOptions: TSNodeTranspileOptions): {
270
    outputText: string;
271
    sourceMapText: string;
272
  };
273
};
274

275
interface TSNodeCreateOptions {
276
  nodeModuleEmitKind?: "commonjs" | "esm" | "nodecjs" | "nodeesm";
277
  service: {
278
    config: {
279
      options: {
280
        module?: number;
281
        jsx?: number;
282
        jsxFactory?: string;
283
        jsxFragmentFactory?: string;
284
        jsxImportSource?: string;
285
        esModuleInterop?: boolean;
286
        verbatimModuleSyntax?: boolean;
287
      };
288
    };
289
  };
290
}
291

292
interface TSNodeTranspileOptions {
293
  fileName: string;
294
}
295
```
296

297
**ts-node Configuration:**
298

299
```json
300
// tsconfig.json
301
{
302
  "ts-node": {
303
    "transpiler": "sucrase/ts-node-plugin"
304
  }
305
}
306
```
307

308
**Command Line Usage:**
309

310
```bash
311
# Use Sucrase as ts-node transpiler
312
npx ts-node --transpiler sucrase/ts-node-plugin script.ts
313

314
# Or set in tsconfig.json and run normally
315
npx ts-node script.ts
316
```
317

318
**Usage Examples:**
319

320
```json
321
// tsconfig.json - Basic setup
322
{
323
  "compilerOptions": {
324
    "target": "ES2020",
325
    "module": "commonjs",
326
    "jsx": "react-jsx"
327
  },
328
  "ts-node": {
329
    "transpiler": "sucrase/ts-node-plugin"
330
  }
331
}
332

333
// tsconfig.json - ESM setup
334
{
335
  "compilerOptions": {
336
    "target": "ES2020",
337
    "module": "esnext",
338
    "jsx": "react-jsx"
339
  },
340
  "ts-node": {
341
    "transpiler": "sucrase/ts-node-plugin",
342
    "esm": true
343
  }
344
}
345
```
346

347
**Supported tsconfig.json Options:**
348
- `compilerOptions.module` - Module system (CommonJS/ESM)
349
- `compilerOptions.jsx` - JSX transformation mode
350
- `compilerOptions.jsxFactory` - JSX pragma function
351
- `compilerOptions.jsxFragmentFactory` - JSX fragment pragma
352
- `compilerOptions.jsxImportSource` - JSX import source
353
- `compilerOptions.esModuleInterop` - Module interop behavior
354
- `compilerOptions.verbatimModuleSyntax` - Preserve imports/exports
355

356
## Integration Patterns
357

358
### Multi-Tool Setup
359

360
```javascript
361
// Example using multiple integrations
362
// webpack.config.js
363
module.exports = {
364
  module: {
365
    rules: [
366
      {
367
        test: /\.(ts|tsx)$/,
368
        use: "@sucrase/webpack-loader",
369
        options: { transforms: ["typescript", "jsx"] }
370
      }
371
    ]
372
  }
373
};
374

375
// jest.config.js
376
module.exports = {
377
  transform: {
378
    "\\.(ts|tsx)$": "@sucrase/jest-plugin"
379
  }
380
};
381

382
// gulpfile.js
383
const sucrase = require("@sucrase/gulp-plugin");
384
gulp.task("build", () => {
385
  return gulp.src("src/**/*.ts")
386
    .pipe(sucrase({ transforms: ["typescript"] }))
387
    .pipe(gulp.dest("dist"));
388
});
389
```
390

391
### Development vs Production
392

393
```javascript
394
// Different configurations for different environments
395
const isProduction = process.env.NODE_ENV === "production";
396

397
// Webpack config
398
const sucraseOptions = {
399
  transforms: ["typescript", "jsx"],
400
  production: isProduction,
401
  jsxRuntime: isProduction ? "automatic" : "classic"
402
};
403

404
// Jest config
405
const jestSucraseOptions = {
406
  disableESTransforms: true,
407
  keepUnusedImports: !isProduction
408
};
409
```
410

411
### Error Handling
412

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

415
```javascript
416
// Webpack loader error
417
Module build failed (from @sucrase/webpack-loader):
418
Error transforming src/App.tsx: Unexpected token (line 15:20)
419

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

424
// Gulp plugin error
425
[gulpSucrase] Error in plugin "@sucrase/gulp-plugin"
426
Message: Error transforming src/component.ts: Invalid syntax
427
```
428

429
### Performance Optimization
430

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

433
```javascript
434
// Webpack - exclude node_modules for better performance
435
{
436
  test: /\.(ts|tsx)$/,
437
  use: "@sucrase/webpack-loader",
438
  exclude: /node_modules/,
439
  options: {
440
    transforms: ["typescript", "jsx"],
441
    disableESTransforms: true // Skip unnecessary transforms
442
  }
443
}
444

445
// Jest - only transform what's needed
446
{
447
  transform: {
448
    "^.+\\.(ts|tsx)$": "@sucrase/jest-plugin"
449
  },
450
  transformIgnorePatterns: [
451
    "node_modules/(?!(some-esm-module)/)"
452
  ]
453
}
454
```