1 | # Sucrase
|
2 |
|
3 | [![Build Status](https://github.com/alangpierce/sucrase/workflows/All%20tests/badge.svg)](https://github.com/alangpierce/sucrase/actions)
|
4 | [![npm version](https://img.shields.io/npm/v/sucrase.svg)](https://www.npmjs.com/package/sucrase)
|
5 | [![Install Size](https://packagephobia.now.sh/badge?p=sucrase)](https://packagephobia.now.sh/result?p=sucrase)
|
6 | [![MIT License](https://img.shields.io/npm/l/express.svg?maxAge=2592000)](LICENSE)
|
7 | [![Join the chat at https://gitter.im/sucrasejs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/sucrasejs/Lobby)
|
8 |
|
9 | ## [Try it out](https://sucrase.io)
|
10 |
|
11 | ## Quick usage
|
12 |
|
13 | ```bash
|
14 | yarn add --dev sucrase # Or npm install --save-dev sucrase
|
15 | node -r sucrase/register main.ts
|
16 | ```
|
17 |
|
18 | Using the [ts-node](https://github.com/TypeStrong/ts-node) integration:
|
19 |
|
20 | ```bash
|
21 | yarn add --dev sucrase ts-node typescript
|
22 | ./node_modules/.bin/ts-node --transpiler sucrase/ts-node-plugin main.ts
|
23 | ```
|
24 |
|
25 | ## Project overview
|
26 |
|
27 | Sucrase is an alternative to Babel that allows super-fast development builds.
|
28 | Instead of compiling a large range of JS features to be able to work in Internet
|
29 | Explorer, Sucrase assumes that you're developing with a recent browser or recent
|
30 | Node.js version, so it focuses on compiling non-standard language extensions:
|
31 | JSX, TypeScript, and Flow. Because of this smaller scope, Sucrase can get away
|
32 | with an architecture that is much more performant but less extensible and
|
33 | maintainable. Sucrase's parser is forked from Babel's parser (so Sucrase is
|
34 | indebted to Babel and wouldn't be possible without it) and trims it down to a
|
35 | focused subset of what Babel solves. If it fits your use case, hopefully Sucrase
|
36 | can speed up your development experience!
|
37 |
|
38 | **Sucrase has been extensively tested.** It can successfully build
|
39 | the [Benchling](https://benchling.com/) frontend code,
|
40 | [Babel](https://github.com/babel/babel),
|
41 | [React](https://github.com/facebook/react),
|
42 | [TSLint](https://github.com/palantir/tslint),
|
43 | [Apollo client](https://github.com/apollographql/apollo-client), and
|
44 | [decaffeinate](https://github.com/decaffeinate/decaffeinate)
|
45 | with all tests passing, about 1 million lines of code total.
|
46 |
|
47 | **Sucrase is about 20x faster than Babel.** Here's one measurement of how
|
48 | Sucrase compares with other tools when compiling the Jest codebase 3 times,
|
49 | about 360k lines of code total:
|
50 |
|
51 | ```text
|
52 | Time Speed
|
53 | Sucrase 0.57 seconds 636975 lines per second
|
54 | swc 1.19 seconds 304526 lines per second
|
55 | esbuild 1.45 seconds 248692 lines per second
|
56 | TypeScript 8.98 seconds 40240 lines per second
|
57 | Babel 9.18 seconds 39366 lines per second
|
58 | ```
|
59 |
|
60 | Details: Measured on July 2022. Tools run in single-threaded mode without warm-up. See the
|
61 | [benchmark code](https://github.com/alangpierce/sucrase/blob/main/benchmark/benchmark.ts)
|
62 | for methodology and caveats.
|
63 |
|
64 | ## Transforms
|
65 |
|
66 | The main configuration option in Sucrase is an array of transform names. These
|
67 | transforms are available:
|
68 |
|
69 | * **jsx**: Enables JSX syntax. By default, JSX is transformed to `React.createClass`,
|
70 | but may be preserved or transformed to `_jsx()` by setting the `jsxRuntime` option.
|
71 | Also adds `createReactClass` display names and JSX context information.
|
72 | * **typescript**: Compiles TypeScript code to JavaScript, removing type
|
73 | annotations and handling features like enums. Does not check types. Sucrase
|
74 | transforms each file independently, so you should enable the `isolatedModules`
|
75 | TypeScript flag so that the typechecker will disallow the few features like
|
76 | `const enum`s that need cross-file compilation.
|
77 | * **flow**: Removes Flow type annotations. Does not check types.
|
78 | * **imports**: Transforms ES Modules (`import`/`export`) to CommonJS
|
79 | (`require`/`module.exports`) using the same approach as Babel and TypeScript
|
80 | with `--esModuleInterop`. If `preserveDynamicImport` is specified in the Sucrase
|
81 | options, then dynamic `import` expressions are left alone, which is particularly
|
82 | useful in Node to load ESM-only libraries. If `preserveDynamicImport` is not
|
83 | specified, `import` expressions are transformed into a promise-wrapped call to
|
84 | `require`.
|
85 | * **react-hot-loader**: Performs the equivalent of the `react-hot-loader/babel`
|
86 | transform in the [react-hot-loader](https://github.com/gaearon/react-hot-loader)
|
87 | project. This enables advanced hot reloading use cases such as editing of
|
88 | bound methods.
|
89 | * **jest**: Hoist desired [jest](https://jestjs.io/) method calls above imports in
|
90 | the same way as [babel-plugin-jest-hoist](https://github.com/facebook/jest/tree/master/packages/babel-plugin-jest-hoist).
|
91 | Does not validate the arguments passed to `jest.mock`, but the same rules still apply.
|
92 |
|
93 | When the `imports` transform is *not* specified (i.e. when targeting ESM), the
|
94 | `injectCreateRequireForImportRequire` option can be specified to transform TS
|
95 | `import foo = require("foo");` in a way that matches the
|
96 | [TypeScript 4.7 behavior](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/#commonjs-interoperability)
|
97 | with `module: nodenext`.
|
98 |
|
99 | These newer JS features are transformed by default:
|
100 |
|
101 | * [Optional chaining](https://github.com/tc39/proposal-optional-chaining): `a?.b`
|
102 | * [Nullish coalescing](https://github.com/tc39/proposal-nullish-coalescing): `a ?? b`
|
103 | * [Class fields](https://github.com/tc39/proposal-class-fields): `class C { x = 1; }`.
|
104 | This includes static fields but not the `#x` private field syntax.
|
105 | * [Numeric separators](https://github.com/tc39/proposal-numeric-separator):
|
106 | `const n = 1_234;`
|
107 | * [Optional catch binding](https://github.com/tc39/proposal-optional-catch-binding):
|
108 | `try { doThing(); } catch { }`.
|
109 |
|
110 | If your target runtime supports these features, you can specify
|
111 | `disableESTransforms: true` so that Sucrase preserves the syntax rather than
|
112 | trying to transform it. Note that transpiled and standard class fields behave
|
113 | slightly differently; see the
|
114 | [TypeScript 3.7 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier)
|
115 | for details. If you use TypeScript, you can enable the TypeScript option
|
116 | `useDefineForClassFields` to enable error checking related to these differences.
|
117 |
|
118 | ### Unsupported syntax
|
119 |
|
120 | All JS syntax not mentioned above will "pass through" and needs to be supported
|
121 | by your JS runtime. For example:
|
122 |
|
123 | * Decorators, private fields, `throw` expressions, generator arrow functions,
|
124 | and `do` expressions are all unsupported in browsers and Node (as of this
|
125 | writing), and Sucrase doesn't make an attempt to transpile them.
|
126 | * Object rest/spread, async functions, and async iterators are all recent
|
127 | features that should work fine, but might cause issues if you use older
|
128 | versions of tools like webpack. BigInt and newer regex features may or may not
|
129 | work, based on your tooling.
|
130 |
|
131 | ### JSX Options
|
132 |
|
133 | By default, JSX is compiled to React functions in development mode. This can be
|
134 | configured with a few options:
|
135 |
|
136 | * **jsxRuntime**: A string specifying the transform mode, which can be one of three values:
|
137 | * `"classic"` (default): The original JSX transform that calls `React.createElement` by default.
|
138 | To configure for non-React use cases, specify:
|
139 | * **jsxPragma**: Element creation function, defaults to `React.createElement`.
|
140 | * **jsxFragmentPragma**: Fragment component, defaults to `React.Fragment`.
|
141 | * `"automatic"`: The [new JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html)
|
142 | introduced with React 17, which calls `jsx` functions and auto-adds import statements.
|
143 | To configure for non-React use cases, specify:
|
144 | * **jsxImportSource**: Package name for auto-generated import statements, defaults to `react`.
|
145 | * `"preserve"`: Don't transform JSX, and instead emit it as-is in the output code.
|
146 | * **production**: If `true`, use production version of functions and don't include debugging
|
147 | information. When using React in production mode with the automatic transform, this *must* be
|
148 | set to true to avoid an error about `jsxDEV` being missing.
|
149 |
|
150 | ### Legacy CommonJS interop
|
151 |
|
152 | Two legacy modes can be used with the `imports` transform:
|
153 |
|
154 | * **enableLegacyTypeScriptModuleInterop**: Use the default TypeScript approach
|
155 | to CommonJS interop instead of assuming that TypeScript's `--esModuleInterop`
|
156 | flag is enabled. For example, if a CJS module exports a function, legacy
|
157 | TypeScript interop requires you to write `import * as add from './add';`,
|
158 | while Babel, Webpack, Node.js, and TypeScript with `--esModuleInterop` require
|
159 | you to write `import add from './add';`. As mentioned in the
|
160 | [docs](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#support-for-import-d-from-cjs-form-commonjs-modules-with---esmoduleinterop),
|
161 | the TypeScript team recommends you always use `--esModuleInterop`.
|
162 | * **enableLegacyBabel5ModuleInterop**: Use the Babel 5 approach to CommonJS
|
163 | interop, so that you can run `require('./MyModule')` instead of
|
164 | `require('./MyModule').default`. Analogous to
|
165 | [babel-plugin-add-module-exports](https://github.com/59naga/babel-plugin-add-module-exports).
|
166 |
|
167 | ## Usage
|
168 |
|
169 | ### Tool integrations
|
170 |
|
171 | * [Webpack](https://github.com/alangpierce/sucrase/tree/main/integrations/webpack-loader)
|
172 | * [Gulp](https://github.com/alangpierce/sucrase/tree/main/integrations/gulp-plugin)
|
173 | * [Jest](https://github.com/alangpierce/sucrase/tree/main/integrations/jest-plugin)
|
174 | * [Rollup](https://github.com/rollup/plugins/tree/master/packages/sucrase)
|
175 | * [Broccoli](https://github.com/stefanpenner/broccoli-sucrase)
|
176 |
|
177 | ### Usage in Node
|
178 |
|
179 | The most robust way is to use the Sucrase plugin for [ts-node](https://github.com/TypeStrong/ts-node),
|
180 | which has various Node integrations and configures Sucrase via `tsconfig.json`:
|
181 | ```bash
|
182 | ts-node --transpiler sucrase/ts-node-plugin
|
183 | ```
|
184 |
|
185 | For projects that don't target ESM, Sucrase also has a require hook with some
|
186 | reasonable defaults that can be accessed in a few ways:
|
187 |
|
188 | * From code: `require("sucrase/register");`
|
189 | * When invoking Node: `node -r sucrase/register main.ts`
|
190 | * As a separate binary: `sucrase-node main.ts`
|
191 |
|
192 | ### Compiling a project to JS
|
193 |
|
194 | For simple use cases, Sucrase comes with a `sucrase` CLI that mirrors your
|
195 | directory structure to an output directory:
|
196 | ```bash
|
197 | sucrase ./srcDir -d ./outDir --transforms typescript,imports
|
198 | ```
|
199 |
|
200 | ### Usage from code
|
201 |
|
202 | For any advanced use cases, Sucrase can be called from JS directly:
|
203 |
|
204 | ```js
|
205 | import {transform} from "sucrase";
|
206 | const compiledCode = transform(code, {transforms: ["typescript", "imports"]}).code;
|
207 | ```
|
208 |
|
209 | ## What Sucrase is not
|
210 |
|
211 | Sucrase is intended to be useful for the most common cases, but it does not aim
|
212 | to have nearly the scope and versatility of Babel. Some specific examples:
|
213 |
|
214 | * Sucrase does not check your code for errors. Sucrase's contract is that if you
|
215 | give it valid code, it will produce valid JS code. If you give it invalid
|
216 | code, it might produce invalid code, it might produce valid code, or it might
|
217 | give an error. Always use Sucrase with a linter or typechecker, which is more
|
218 | suited for error-checking.
|
219 | * Sucrase is not pluginizable. With the current architecture, transforms need to
|
220 | be explicitly written to cooperate with each other, so each additional
|
221 | transform takes significant extra work.
|
222 | * Sucrase is not good for prototyping language extensions and upcoming language
|
223 | features. Its faster architecture makes new transforms more difficult to write
|
224 | and more fragile.
|
225 | * Sucrase will never produce code for old browsers like IE. Compiling code down
|
226 | to ES5 is much more complicated than any transformation that Sucrase needs to
|
227 | do.
|
228 | * Sucrase is hesitant to implement upcoming JS features, although some of them
|
229 | make sense to implement for pragmatic reasons. Its main focus is on language
|
230 | extensions (JSX, TypeScript, Flow) that will never be supported by JS
|
231 | runtimes.
|
232 | * Like Babel, Sucrase is not a typechecker, and must process each file in
|
233 | isolation. For example, TypeScript `const enum`s are treated as regular
|
234 | `enum`s rather than inlining across files.
|
235 | * You should think carefully before using Sucrase in production. Sucrase is
|
236 | mostly beneficial in development, and in many cases, Babel or tsc will be more
|
237 | suitable for production builds.
|
238 |
|
239 | See the [Project Vision](./docs/PROJECT_VISION.md) document for more details on
|
240 | the philosophy behind Sucrase.
|
241 |
|
242 | ## Motivation
|
243 |
|
244 | As JavaScript implementations mature, it becomes more and more reasonable to
|
245 | disable Babel transforms, especially in development when you know that you're
|
246 | targeting a modern runtime. You might hope that you could simplify and speed up
|
247 | the build step by eventually disabling Babel entirely, but this isn't possible
|
248 | if you're using a non-standard language extension like JSX, TypeScript, or Flow.
|
249 | Unfortunately, disabling most transforms in Babel doesn't speed it up as much as
|
250 | you might expect. To understand, let's take a look at how Babel works:
|
251 |
|
252 | 1. Tokenize the input source code into a token stream.
|
253 | 2. Parse the token stream into an AST.
|
254 | 3. Walk the AST to compute the scope information for each variable.
|
255 | 4. Apply all transform plugins in a single traversal, resulting in a new AST.
|
256 | 5. Print the resulting AST.
|
257 |
|
258 | Only step 4 gets faster when disabling plugins, so there's always a fixed cost
|
259 | to running Babel regardless of how many transforms are enabled.
|
260 |
|
261 | Sucrase bypasses most of these steps, and works like this:
|
262 |
|
263 | 1. Tokenize the input source code into a token stream using a trimmed-down fork
|
264 | of the Babel parser. This fork does not produce a full AST, but still
|
265 | produces meaningful token metadata specifically designed for the later
|
266 | transforms.
|
267 | 2. Scan through the tokens, computing preliminary information like all
|
268 | imported/exported names.
|
269 | 3. Run the transform by doing a pass through the tokens and performing a number
|
270 | of careful find-and-replace operations, like replacing `<Foo` with
|
271 | `React.createElement(Foo`.
|
272 |
|
273 | Because Sucrase works on a lower level and uses a custom parser for its use
|
274 | case, it is much faster than Babel.
|
275 |
|
276 | ## Contributing
|
277 |
|
278 | Contributions are welcome, whether they be bug reports, PRs, docs, tests, or
|
279 | anything else! Please take a look through the [Contributing Guide](./CONTRIBUTING.md)
|
280 | to learn how to get started.
|
281 |
|
282 | ## License and attribution
|
283 |
|
284 | Sucrase is MIT-licensed. A large part of Sucrase is based on a fork of the
|
285 | [Babel parser](https://github.com/babel/babel/tree/main/packages/babel-parser),
|
286 | which is also MIT-licensed.
|
287 |
|
288 | ## Why the name?
|
289 |
|
290 | Sucrase is an enzyme that processes sugar. Get it?
|