$ npm install sucrase
yarn add --dev sucrase # Or npm install --save-dev sucrase
node -r sucrase/register main.ts
Using the ts-node integration:
yarn add --dev sucrase ts-node typescript
./node_modules/.bin/ts-node --transpiler sucrase/ts-node-plugin main.ts
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 frontend code, Babel, React, TSLint, Apollo client, and 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:
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 for methodology and caveats.
The main configuration option in Sucrase is an array of transform names. These transforms are available:
React.createClass
,
but may be preserved or transformed to _jsx()
by setting the jsxRuntime
option.
Also adds createReactClass
display names and JSX context information.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
.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/babel
transform in the react-hot-loader
project. This enables advanced hot reloading use cases such as editing of
bound methods.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
with module: nodenext
.
These newer JS features are transformed by default:
a?.b
a ?? b
class C { x = 1; }
.
This includes static fields but not the #x
private field syntax.const n = 1_234;
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
for details. If you use TypeScript, you can enable the TypeScript option
useDefineForClassFields
to enable error checking related to these differences.
All JS syntax not mentioned above will "pass through" and needs to be supported by your JS runtime. For example:
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.By default, JSX is compiled to React functions in development mode. This can be configured with a few options:
"classic"
(default): The original JSX transform that calls React.createElement
by default.
To configure for non-React use cases, specify:
React.createElement
.React.Fragment
."automatic"
: The new JSX transform
introduced with React 17, which calls jsx
functions and auto-adds import statements.
To configure for non-React use cases, specify:
react
."preserve"
: Don't transform JSX, and instead emit it as-is in the output code.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.Two legacy modes can be used with the imports
transform:
--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,
the TypeScript team recommends you always use --esModuleInterop
.require('./MyModule')
instead of
require('./MyModule').default
. Analogous to
babel-plugin-add-module-exports.The most robust way is to use the Sucrase plugin for ts-node,
which has various Node integrations and configures Sucrase via tsconfig.json
:
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:
require("sucrase/register");
node -r sucrase/register main.ts
sucrase-node main.ts
Options can be passed to the require hook via a SUCRASE_OPTIONS
environment
variable holding a JSON string of options.
For simple use cases, Sucrase comes with a sucrase
CLI that mirrors your
directory structure to an output directory:
sucrase ./srcDir -d ./outDir --transforms typescript,imports
For any advanced use cases, Sucrase can be called from JS directly:
import {transform} from "sucrase";
const compiledCode = transform(code, {transforms: ["typescript", "imports"]}).code;
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:
const enum
s are treated as regular
enum
s rather than inlining across files.See the Project Vision document for more details on the philosophy behind Sucrase.
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:
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:
<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.
Contributions are welcome, whether they be bug reports, PRs, docs, tests, or anything else! Please take a look through the Contributing Guide to learn how to get started.
Sucrase is MIT-licensed. A large part of Sucrase is based on a fork of the Babel parser, which is also MIT-licensed.
Sucrase is an enzyme that processes sugar. Get it?
© 2010 - cnpmjs.org x YWFE | Home | YWFE