Skip to content

Commit

Permalink
fix(docs): Fix README typo, markdown linter problems (#678)
Browse files Browse the repository at this point in the history
This PR contains two changes, corresponding to the two commits included below.

- The actual reason for the PR: Fixes a spot in the `README.md` where the `imports` transform was referred to as the `import` transform.

- A "while I'm here might as well": Adds blank lines before lists and code fence language designations to please the markdown linter, for the markdown files at the top level of the repo. (Other things which were making the linter unhappy, like putting an H3 directly under an H1 without an intervening H2, I left alone, because I didn't actually want to change the appearance of anything.)
  • Loading branch information
lobsterkatie authored Apr 2, 2022
1 parent 57b8eff commit 1d83558
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 7 deletions.
1 change: 0 additions & 1 deletion CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,4 +71,3 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], versi
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

5 changes: 4 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
Thanks for taking a look at the project and thinking about contributing!

There are two main ways to communicate about Sucrase development:

* Join the [Gitter room](https://gitter.im/sucrasejs/Lobby) and feel free to ask
questions or discuss anything.
* File an issue or PR in this repository. Issues don't need to be bug reports;
Expand Down Expand Up @@ -45,7 +46,7 @@ more concrete suggestions.

Sucrase uses `yarn` for everything.

```
```bash
git clone git@github.com:alangpierce/sucrase.git
cd sucrase
yarn # Install dependencies.
Expand All @@ -67,6 +68,7 @@ details of the change and references to any issues closed by the change.

The code is organized as a monorepo (with one primary `sucrase` package and
several smaller packages/projects). Here are the most important directories:

* The `src` directory is where the main code lives. Much of the code is in the
`parser` subdirectory, which is a heavily modified fork of Babel's parser. The
rest of the code handles transforming the code given the result of the parser.
Expand All @@ -92,6 +94,7 @@ several smaller packages/projects). Here are the most important directories:

The main release script is lives in `script/release.ts`, and also contains
documentation on how to prepare and perform a release. Here's a summary:

* To release the core `sucrase` package, update `package.json` and the
release notes, then run `yarn release`, which also updates the internal
Sucrase dependency and re-publishes the website.
Expand Down
20 changes: 15 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,14 +31,16 @@ 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 1.64 seconds 220221 lines per second
swc 2.13 seconds 169502 lines per second
esbuild 3.02 seconds 119738 lines per second
TypeScript 24.18 seconds 14937 lines per second
Babel 27.22 seconds 13270 lines per second
```

Details: Measured on January 2021. 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.
Expand All @@ -47,6 +49,7 @@ for methodology and caveats.

The main configuration option in Sucrase is an array of transform names. These
transforms are available:

* **jsx**: Transforms JSX syntax to `React.createElement`, e.g. `<div a={b} />`
becomes `React.createElement('div', {a: b})`. Behaves like Babel 7's
[React preset](https://github.com/babel/babel/tree/main/packages/babel-preset-react),
Expand All @@ -69,6 +72,7 @@ transforms are available:
Does not validate the arguments passed to `jest.mock`, but the same rules still apply.

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; }`.
Expand All @@ -90,6 +94,7 @@ for details. If you use TypeScript, you can enable the TypeScript option

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.
Expand All @@ -99,13 +104,17 @@ by your JS runtime. For example:
work, based on your tooling.

### JSX Options

Like Babel, Sucrase compiles JSX to React functions by default, but can be
configured for any JSX use case.

* **jsxPragma**: Element creation function, defaults to `React.createElement`.
* **jsxFragmentPragma**: Fragment component, defaults to `React.Fragment`.

### Legacy CommonJS interop
Two legacy modes can be used with the `import` transform:

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
Expand All @@ -123,7 +132,7 @@ Two legacy modes can be used with the `import` transform:

Installation:

```
```bash
yarn add --dev sucrase # Or npm install --save-dev sucrase
```

Expand All @@ -145,13 +154,13 @@ require("sucrase/register");

Compile on-the-fly via a drop-in replacement for node:

```
```bash
sucrase-node index.ts
```

Run on a directory:

```
```bash
sucrase ./srcDir -d ./outDir --transforms typescript,imports
```

Expand Down Expand Up @@ -215,6 +224,7 @@ 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
Expand Down

0 comments on commit 1d83558

Please # to comment.