0
# @rollup/plugin-sucrase
1

2
A Rollup plugin that compiles TypeScript, Flow, JSX, and other modern JavaScript syntax using Sucrase for fast compilation. Sucrase is a fast alternative to Babel for transforming modern JavaScript, providing high-performance bundling workflows while maintaining compatibility with Rollup's plugin ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @rollup/plugin-sucrase
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Node Version**: 14.0.0+
10
- **Installation**: `npm install @rollup/plugin-sucrase --save-dev`
11

12
## Core Imports
13

14
```javascript
15
import sucrase from '@rollup/plugin-sucrase';
16
```
17

18
CommonJS:
19

20
```javascript
21
const sucrase = require('@rollup/plugin-sucrase');
22
```
23

24
## Basic Usage
25

26
```javascript
27
import { rollup } from 'rollup';
28
import sucrase from '@rollup/plugin-sucrase';
29
import resolve from '@rollup/plugin-node-resolve';
30

31
export default {
32
  input: 'src/index.ts',
33
  output: {
34
    file: 'dist/bundle.js',
35
    format: 'cjs'
36
  },
37
  plugins: [
38
    resolve({
39
      extensions: ['.js', '.ts']
40
    }),
41
    sucrase({
42
      exclude: ['node_modules/**'],
43
      transforms: ['typescript']
44
    })
45
  ]
46
};
47
```
48

49
## Capabilities
50

51
### Plugin Creation
52

53
Creates a Rollup plugin instance configured for Sucrase transformations.
54

55
```javascript { .api }
56
/**
57
 * Creates a Rollup plugin for compiling modern JavaScript/TypeScript with Sucrase
58
 * @param options - Configuration options for the plugin
59
 * @returns Rollup plugin instance
60
 */
61
function sucrase(options?: RollupSucraseOptions): Plugin;
62
```
63

64
**Usage Examples:**
65

66
```javascript
67
// Basic TypeScript compilation
68
sucrase({
69
  transforms: ['typescript']
70
})
71

72
// JSX with custom pragma
73
sucrase({
74
  transforms: ['jsx'],
75
  jsxPragma: 'React.createElement',
76
  jsxFragmentPragma: 'React.Fragment'
77
})
78

79
// TypeScript + JSX (TSX files)
80
sucrase({
81
  transforms: ['typescript', 'jsx']
82
})
83

84
// With file filtering
85
sucrase({
86
  transforms: ['typescript'],
87
  include: ['src/**/*.ts'],
88
  exclude: ['node_modules/**', '**/*.test.ts']
89
})
90

91
// Production optimizations
92
sucrase({
93
  transforms: ['typescript'],
94
  production: true,
95
  enableLegacyTypeScriptModuleInterop: false
96
})
97

98
// Jest test compilation
99
sucrase({
100
  transforms: ['typescript', 'jest']
101
})
102

103
// ES6 to CommonJS conversion
104
sucrase({
105
  transforms: ['imports'],
106
  production: true
107
})
108
```
109

110
## Configuration Options
111

112
```typescript { .api }
113
interface RollupSucraseOptions {
114
  /**
115
   * Array of transform types to apply
116
   * Supported values: 'typescript', 'jsx', 'flow', 'imports', 'react-hot-loader', 'jest'
117
   */
118
  transforms?: string[];
119
  
120
  /**
121
   * Custom JSX pragma function name
122
   * @default 'React.createElement'
123
   */
124
  jsxPragma?: string;
125
  
126
  /**
127
   * Custom JSX fragment pragma
128
   * @default 'React.Fragment'
129
   */
130
  jsxFragmentPragma?: string;
131
  
132
  /**
133
   * Enable legacy TypeScript module interoperability
134
   * @default false
135
   */
136
  enableLegacyTypeScriptModuleInterop?: boolean;
137
  
138
  /**
139
   * Enable legacy Babel 5 module interoperability
140
   * @default false
141
   */
142
  enableLegacyBabel5ModuleInterop?: boolean;
143
  
144
  /**
145
   * Enable production mode optimizations
146
   * @default false
147
   */
148
  production?: boolean;
149
  
150
  /**
151
   * Disable ES module transforms
152
   * @default false
153
   */
154
  disableESTransforms?: boolean;
155
  
156
  /**
157
   * Picomatch pattern or array of patterns specifying files to include
158
   * @default null (all files)
159
   */
160
  include?: FilterPattern;
161
  
162
  /**
163
   * Picomatch pattern or array of patterns specifying files to exclude
164
   * @default null (no files excluded)
165
   */
166
  exclude?: FilterPattern;
167
}
168
```
169

170
### Transform Types
171

172
The `transforms` option accepts an array of the following transform types:
173

174
- **`'typescript'`**: Compiles TypeScript syntax, removes type annotations
175
- **`'jsx'`**: Transforms JSX syntax to JavaScript function calls
176
- **`'flow'`**: Removes Flow type annotations
177
- **`'imports'`**: Transforms ES6 import/export statements to CommonJS
178
- **`'react-hot-loader'`**: Enables advanced hot reloading for React components
179
- **`'jest'`**: Hoists Jest method calls (like `jest.mock()`) above imports for proper test execution
180

181
**Common combinations:**
182
- `['typescript']` - TypeScript files (.ts)
183
- `['jsx']` - JSX files (.jsx)
184
- `['typescript', 'jsx']` - TypeScript + JSX files (.tsx)
185
- `['flow']` - Flow-typed JavaScript files
186
- `['typescript', 'jest']` - TypeScript test files with Jest
187
- `['imports']` - ES6 modules to CommonJS conversion
188

189
### File Resolution
190

191
The plugin automatically resolves TypeScript imports with the following extension priority:
192

193
1. `{path}.ts`
194
2. `{path}.tsx`
195
3. `{path}/index.ts`
196
4. `{path}/index.tsx`
197

198
For imports ending in `.js`, it also checks:
199
- `{path}.ts` (replacing `.js` with `.ts`)
200
- `{path}.tsx` (replacing `.js` with `.tsx`)
201

202
This allows you to import TypeScript files using `.js` extensions, which TypeScript expects for ES module compatibility.
203

204
## Types
205

206
```typescript { .api }
207
/**
208
 * Rollup plugin interface
209
 */
210
interface Plugin {
211
  name: string;
212
  resolveId?(importee: string, importer?: string): string | null | undefined;
213
  transform?(code: string, id: string): { code: string; map: any } | null;
214
}
215

216
/**
217
 * File filtering pattern type from @rollup/pluginutils
218
 */
219
type FilterPattern = string | RegExp | Array<string | RegExp> | null;
220
```
221

222
## Error Handling
223

224
The plugin handles transformation errors by:
225

226
1. **File Filtering**: Files not matching include/exclude patterns are skipped silently
227
2. **Transform Errors**: Sucrase transformation errors are propagated to Rollup with source location information
228
3. **Resolution Errors**: Module resolution failures return `undefined`, allowing other plugins to handle resolution
229

230
## Performance Considerations
231

232
- **Fast Compilation**: Sucrase is designed for speed over feature completeness compared to Babel
233
- **Limited Transforms**: Focuses on syntax transformation rather than polyfills or advanced transforms
234
- **TypeScript Support**: Faster than tsc for compilation, but does not perform type checking
235
- **Source Maps**: Generates source maps for debugging transformed code