Buckets:
| # Sucrase | |
| [](https://github.com/alangpierce/sucrase/actions) | |
| [](https://www.npmjs.com/package/sucrase) | |
| [](https://packagephobia.now.sh/result?p=sucrase) | |
| [](LICENSE) | |
| [](https://gitter.im/sucrasejs/Lobby) | |
| ## [Try it out](https://sucrase.io) | |
| ## Quick usage | |
| ```bash | |
| yarn add --dev sucrase # Or npm install --save-dev sucrase | |
| node -r sucrase/register main.ts | |
| ``` | |
| Using the [ts-node](https://github.com/TypeStrong/ts-node) integration: | |
| ```bash | |
| yarn add --dev sucrase ts-node typescript | |
| ./node_modules/.bin/ts-node --transpiler sucrase/ts-node-plugin main.ts | |
| ``` | |
| ## Project overview | |
| Sucrase is an alternative to Babel that allows super-fast development builds. | |
| Instead of compiling a large range of JS features to be able to work in Internet | |
| Explorer, Sucrase assumes that you're developing with a recent browser or recent | |
| Node.js version, so it focuses on compiling non-standard language extensions: | |
| JSX, TypeScript, and Flow. Because of this smaller scope, Sucrase can get away | |
| with an architecture that is much more performant but less extensible and | |
| maintainable. Sucrase's parser is forked from Babel's parser (so Sucrase is | |
| indebted to Babel and wouldn't be possible without it) and trims it down to a | |
| focused subset of what Babel solves. If it fits your use case, hopefully Sucrase | |
| can speed up your development experience! | |
| **Sucrase has been extensively tested.** It can successfully build | |
| the [Benchling](https://benchling.com/) frontend code, | |
| [Babel](https://github.com/babel/babel), | |
| [React](https://github.com/facebook/react), | |
| [TSLint](https://github.com/palantir/tslint), | |
| [Apollo client](https://github.com/apollographql/apollo-client), and | |
| [decaffeinate](https://github.com/decaffeinate/decaffeinate) | |
| with all tests passing, about 1 million lines of code total. | |
| **Sucrase is about 20x faster than Babel.** Here's one measurement of how | |
| Sucrase compares with other tools when compiling the Jest codebase 3 times, | |
| about 360k lines of code total: | |
| ```text | |
| Time Speed | |
| Sucrase 0.57 seconds 636975 lines per second | |
| swc 1.19 seconds 304526 lines per second | |
| esbuild 1.45 seconds 248692 lines per second | |
| TypeScript 8.98 seconds 40240 lines per second | |
| Babel 9.18 seconds 39366 lines per second | |
| ``` | |
| Details: Measured on July 2022. Tools run in single-threaded mode without warm-up. See the | |
| [benchmark code](https://github.com/alangpierce/sucrase/blob/main/benchmark/benchmark.ts) | |
| for methodology and caveats. | |
| ## Transforms | |
| The main configuration option in Sucrase is an array of transform names. These | |
| transforms are available: | |
| * **jsx**: Enables JSX syntax. By default, JSX is transformed to `React.createClass`, | |
| but may be preserved or transformed to `_jsx()` by setting the `jsxRuntime` option. | |
| Also adds `createReactClass` display names and JSX context information. | |
| * **typescript**: Compiles TypeScript code to JavaScript, removing type | |
| annotations and handling features like enums. Does not check types. Sucrase | |
| transforms each file independently, so you should enable the `isolatedModules` | |
| TypeScript flag so that the typechecker will disallow the few features like | |
| `const enum`s that need cross-file compilation. The Sucrase option `keepUnusedImports` | |
| can be used to disable all automatic removal of imports and exports, analogous to TS | |
| `verbatimModuleSyntax`. | |
| * **flow**: Removes Flow type annotations. Does not check types. | |
| * **imports**: Transforms ES Modules (`import`/`export`) to CommonJS | |
| (`require`/`module.exports`) using the same approach as Babel and TypeScript | |
| with `--esModuleInterop`. If `preserveDynamicImport` is specified in the Sucrase | |
| options, then dynamic `import` expressions are left alone, which is particularly | |
| useful in Node to load ESM-only libraries. If `preserveDynamicImport` is not | |
| specified, `import` expressions are transformed into a promise-wrapped call to | |
| `require`. | |
| * **react-hot-loader**: Performs the equivalent of the `react-hot-loader/babel` | |
| transform in the [react-hot-loader](https://github.com/gaearon/react-hot-loader) | |
| project. This enables advanced hot reloading use cases such as editing of | |
| bound methods. | |
| * **jest**: Hoist desired [jest](https://jestjs.io/) method calls above imports in | |
| the same way as [babel-plugin-jest-hoist](https://github.com/facebook/jest/tree/master/packages/babel-plugin-jest-hoist). | |
| Does not validate the arguments passed to `jest.mock`, but the same rules still apply. | |
| When the `imports` transform is *not* specified (i.e. when targeting ESM), the | |
| `injectCreateRequireForImportRequire` option can be specified to transform TS | |
| `import foo = require("foo");` in a way that matches the | |
| [TypeScript 4.7 behavior](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/#commonjs-interoperability) | |
| with `module: nodenext`. | |
| These newer JS features are transformed by default: | |
| * [Optional chaining](https://github.com/tc39/proposal-optional-chaining): `a?.b` | |
| * [Nullish coalescing](https://github.com/tc39/proposal-nullish-coalescing): `a ?? b` | |
| * [Class fields](https://github.com/tc39/proposal-class-fields): `class C { x = 1; }`. | |
| This includes static fields but not the `#x` private field syntax. | |
| * [Numeric separators](https://github.com/tc39/proposal-numeric-separator): | |
| `const n = 1_234;` | |
| * [Optional catch binding](https://github.com/tc39/proposal-optional-catch-binding): | |
| `try { doThing(); } catch { }`. | |
| If your target runtime supports these features, you can specify | |
| `disableESTransforms: true` so that Sucrase preserves the syntax rather than | |
| trying to transform it. Note that transpiled and standard class fields behave | |
| slightly differently; see the | |
| [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) | |
| for details. If you use TypeScript, you can enable the TypeScript option | |
| `useDefineForClassFields` to enable error checking related to these differences. | |
| ### Unsupported syntax | |
| All JS syntax not mentioned above will "pass through" and needs to be supported | |
| by your JS runtime. For example: | |
| * Decorators, private fields, `throw` expressions, generator arrow functions, | |
| and `do` expressions are all unsupported in browsers and Node (as of this | |
| writing), and Sucrase doesn't make an attempt to transpile them. | |
| * Object rest/spread, async functions, and async iterators are all recent | |
| features that should work fine, but might cause issues if you use older | |
| versions of tools like webpack. BigInt and newer regex features may or may not | |
| work, based on your tooling. | |
| ### JSX Options | |
| By default, JSX is compiled to React functions in development mode. This can be | |
| configured with a few options: | |
| * **jsxRuntime**: A string specifying the transform mode, which can be one of three values: | |
| * `"classic"` (default): The original JSX transform that calls `React.createElement` by default. | |
| To configure for non-React use cases, specify: | |
| * **jsxPragma**: Element creation function, defaults to `React.createElement`. | |
| * **jsxFragmentPragma**: Fragment component, defaults to `React.Fragment`. | |
| * `"automatic"`: The [new JSX transform](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) | |
| introduced with React 17, which calls `jsx` functions and auto-adds import statements. | |
| To configure for non-React use cases, specify: | |
| * **jsxImportSource**: Package name for auto-generated import statements, defaults to `react`. | |
| * `"preserve"`: Don't transform JSX, and instead emit it as-is in the output code. | |
| * **production**: If `true`, use production version of functions and don't include debugging | |
| information. When using React in production mode with the automatic transform, this *must* be | |
| set to true to avoid an error about `jsxDEV` being missing. | |
| ### Legacy CommonJS interop | |
| Two legacy modes can be used with the `imports` transform: | |
| * **enableLegacyTypeScriptModuleInterop**: Use the default TypeScript approach | |
| to CommonJS interop instead of assuming that TypeScript's `--esModuleInterop` | |
| flag is enabled. For example, if a CJS module exports a function, legacy | |
| TypeScript interop requires you to write `import * as add from './add';`, | |
| while Babel, Webpack, Node.js, and TypeScript with `--esModuleInterop` require | |
| you to write `import add from './add';`. As mentioned in the | |
| [docs](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#support-for-import-d-from-cjs-form-commonjs-modules-with---esmoduleinterop), | |
| the TypeScript team recommends you always use `--esModuleInterop`. | |
| * **enableLegacyBabel5ModuleInterop**: Use the Babel 5 approach to CommonJS | |
| interop, so that you can run `require('./MyModule')` instead of | |
| `require('./MyModule').default`. Analogous to | |
| [babel-plugin-add-module-exports](https://github.com/59naga/babel-plugin-add-module-exports). | |
| ## Usage | |
| ### Tool integrations | |
| * [Webpack](https://github.com/alangpierce/sucrase/tree/main/integrations/webpack-loader) | |
| * [Gulp](https://github.com/alangpierce/sucrase/tree/main/integrations/gulp-plugin) | |
| * [Jest](https://github.com/alangpierce/sucrase/tree/main/integrations/jest-plugin) | |
| * [Rollup](https://github.com/rollup/plugins/tree/master/packages/sucrase) | |
| * [Broccoli](https://github.com/stefanpenner/broccoli-sucrase) | |
| ### Usage in Node | |
| The most robust way is to use the Sucrase plugin for [ts-node](https://github.com/TypeStrong/ts-node), | |
| which has various Node integrations and configures Sucrase via `tsconfig.json`: | |
| ```bash | |
| ts-node --transpiler sucrase/ts-node-plugin | |
| ``` | |
| For projects that don't target ESM, Sucrase also has a require hook with some | |
| reasonable defaults that can be accessed in a few ways: | |
| * From code: `require("sucrase/register");` | |
| * When invoking Node: `node -r sucrase/register main.ts` | |
| * As a separate binary: `sucrase-node main.ts` | |
| Options can be passed to the require hook via a `SUCRASE_OPTIONS` environment | |
| variable holding a JSON string of options. | |
| ### Compiling a project to JS | |
| For simple use cases, Sucrase comes with a `sucrase` CLI that mirrors your | |
| directory structure to an output directory: | |
| ```bash | |
| sucrase ./srcDir -d ./outDir --transforms typescript,imports | |
| ``` | |
| ### Usage from code | |
| For any advanced use cases, Sucrase can be called from JS directly: | |
| ```js | |
| import {transform} from "sucrase"; | |
| const compiledCode = transform(code, {transforms: ["typescript", "imports"]}).code; | |
| ``` | |
| ## What Sucrase is not | |
| Sucrase is intended to be useful for the most common cases, but it does not aim | |
| to have nearly the scope and versatility of Babel. Some specific examples: | |
| * Sucrase does not check your code for errors. Sucrase's contract is that if you | |
| give it valid code, it will produce valid JS code. If you give it invalid | |
| code, it might produce invalid code, it might produce valid code, or it might | |
| give an error. Always use Sucrase with a linter or typechecker, which is more | |
| suited for error-checking. | |
| * Sucrase is not pluginizable. With the current architecture, transforms need to | |
| be explicitly written to cooperate with each other, so each additional | |
| transform takes significant extra work. | |
| * Sucrase is not good for prototyping language extensions and upcoming language | |
| features. Its faster architecture makes new transforms more difficult to write | |
| and more fragile. | |
| * Sucrase will never produce code for old browsers like IE. Compiling code down | |
| to ES5 is much more complicated than any transformation that Sucrase needs to | |
| do. | |
| * Sucrase is hesitant to implement upcoming JS features, although some of them | |
| make sense to implement for pragmatic reasons. Its main focus is on language | |
| extensions (JSX, TypeScript, Flow) that will never be supported by JS | |
| runtimes. | |
| * Like Babel, Sucrase is not a typechecker, and must process each file in | |
| isolation. For example, TypeScript `const enum`s are treated as regular | |
| `enum`s rather than inlining across files. | |
| * You should think carefully before using Sucrase in production. Sucrase is | |
| mostly beneficial in development, and in many cases, Babel or tsc will be more | |
| suitable for production builds. | |
| See the [Project Vision](./docs/PROJECT_VISION.md) document for more details on | |
| the philosophy behind Sucrase. | |
| ## Motivation | |
| As JavaScript implementations mature, it becomes more and more reasonable to | |
| disable Babel transforms, especially in development when you know that you're | |
| targeting a modern runtime. You might hope that you could simplify and speed up | |
| the build step by eventually disabling Babel entirely, but this isn't possible | |
| if you're using a non-standard language extension like JSX, TypeScript, or Flow. | |
| Unfortunately, disabling most transforms in Babel doesn't speed it up as much as | |
| you might expect. To understand, let's take a look at how Babel works: | |
| 1. Tokenize the input source code into a token stream. | |
| 2. Parse the token stream into an AST. | |
| 3. Walk the AST to compute the scope information for each variable. | |
| 4. Apply all transform plugins in a single traversal, resulting in a new AST. | |
| 5. Print the resulting AST. | |
| Only step 4 gets faster when disabling plugins, so there's always a fixed cost | |
| to running Babel regardless of how many transforms are enabled. | |
| Sucrase bypasses most of these steps, and works like this: | |
| 1. Tokenize the input source code into a token stream using a trimmed-down fork | |
| of the Babel parser. This fork does not produce a full AST, but still | |
| produces meaningful token metadata specifically designed for the later | |
| transforms. | |
| 2. Scan through the tokens, computing preliminary information like all | |
| imported/exported names. | |
| 3. Run the transform by doing a pass through the tokens and performing a number | |
| of careful find-and-replace operations, like replacing `<Foo` with | |
| `React.createElement(Foo`. | |
| Because Sucrase works on a lower level and uses a custom parser for its use | |
| case, it is much faster than Babel. | |
| ## Contributing | |
| Contributions are welcome, whether they be bug reports, PRs, docs, tests, or | |
| anything else! Please take a look through the [Contributing Guide](./CONTRIBUTING.md) | |
| to learn how to get started. | |
| ## License and attribution | |
| Sucrase is MIT-licensed. A large part of Sucrase is based on a fork of the | |
| [Babel parser](https://github.com/babel/babel/tree/main/packages/babel-parser), | |
| which is also MIT-licensed. | |
| ## Why the name? | |
| Sucrase is an enzyme that processes sugar. Get it? | |
Xet Storage Details
- Size:
- 14.8 kB
- Xet hash:
- 5ce0d6c069f93054fe0fdf703d35ad280b5813d236b08ecf7b4c46865593ea53
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.