Sucrase Documentation

Sucrase is designed for speed and is primarily intended for development environments targeting modern runtimes. Before using it, be aware of the following limitations:

• No Error Checking: Sucrase does not check your code for errors. It assumes the input is valid. Always use a linter or typechecker (like ESLint or TypeScript) alongside Sucrase.
• Not Pluginizable: Unlike Babel, you cannot easily add custom transforms.
• No ES5 Support: Sucrase will not compile code down to ES5 for old browsers like IE.
• No Typechecking: Sucrase processes files in isolation. It cannot perform cross-file type analysis (e.g., TypeScript const enums are treated as regular enums).
• Production Use: While usable, Babel or tsc are often more suitable for production builds. Sucrase is most beneficial in development to speed up build steps.

To run tests and generate a coverage report, use the --coverage flag. Note that this requires an extra -- separator when using npm test.

npm test -- --coverage

For the most robust Node integration, use the Sucrase plugin for ts-node. This allows you to configure Sucrase via your tsconfig.json.

yarn add --dev sucrase ts-node typescript
./node_modules/.bin/ts-node --transpiler sucrase/ts-node-plugin main.ts

To use Sucrase with Jest, you must install both @sucrase/jest-plugin and sucrase as development dependencies.

yarn add --dev @sucrase/jest-plugin sucrase

By default, npm test optimizes execution by only running tests related to files changed since the last Git or Mercurial commit.

To force Jest to run all tests while in watch mode, press a in the terminal.

To use the Sucrase Webpack loader, you must install both @sucrase/webpack-loader and sucrase as development dependencies.

yarn add --dev @sucrase/webpack-loader sucrase

Jest automatically detects test files based on specific naming patterns. You can place these files in __tests__ folders or anywhere under the src directory. Supported conventions include:

• Files with a .js suffix inside __tests__ folders.
• Files with a .test.js suffix.
• Files with a .spec.js suffix.

It is recommended to colocate test files with the code they test (e.g., App.test.js next to App.js) to simplify relative imports.

To use Sucrase for rapid development, install it as a dev dependency and use the sucrase/register hook to run TypeScript files directly in Node.js.

yarn add --dev sucrase  # Or npm install --save-dev sucrase
node -r sucrase/register main.ts

If your tests do not rely on browser globals (like window or document), ReactDOM.render(), or Enzyme's mount(), you can disable jsdom to speed up execution.

In your package.json, change the test script from: "test": "react-scripts test --env=jsdom" to: "test": "react-scripts test".

Note: jsdom is not needed for shallow rendering (shallow()) or snapshot testing.

To use more readable matchers like toContainReact, install jest-enzyme and import it in your src/setupTests.js file.

Installation:

npm install --save jest-enzyme

Setup in src/setupTests.js:

import 'jest-enzyme';

If you need to mock browser APIs (like localStorage) or perform global setup before tests run, create a src/setupTests.js file. This file is automatically executed before every test run.

const localStorageMock = {
  getItem: jest.fn(),
  setItem: jest.fn(),
  clear: jest.fn()
};
global.localStorage = localStorageMock