feat: Add compiler option, replace Buble with Sucrase

.github/Contributing.md

@@ -66,24 +66,12 @@ Then run Babel in watch mode:
 npm run compile:watch
 ```
 
-Then open a new terminal and start Styleguidist server:
-
-```bash
-npm run test:cypress:startServer
-```
-
-And, finally, in another separate terminal run tests:
+Then open a new terminal and run Cypress:
 
 ```bash
 npm run test:cypress:run
 ```
 
-Or open Cypress UI:
-
-```bash
-npm run test:cypress:open
-```
-
 ## Other notes
 
 - If you have commit access to repository and want to make big change or not sure about something, make a new branch and open pull request.

.travis.yml

@@ -52,9 +52,7 @@ jobs:
         - npm run test:browser:sections
         # Run integration tests with Cypress
         - npm run test:cypress:pre
-        - npm run test:cypress:startServer &
-        - npm run test:cypress:startServer:post
-        - npm run test:cypress:run
+        - npm run test:cypress:ci
 
     - stage: coverage
       script:

docs/Configuration.md

@@ -8,28 +8,59 @@ Type: `String` or `Array`, optional
 
 Your application static assets folder will be accessible as `/` in the style guide dev server.
 
-## `compilerConfig`
+## `compileExample`
+
+Type: `Function`, default:
+
+```javascript
+;(compiler, code) =>
+  compiler.transform(code, {
+    // Compile TypeScript, JSX and ECMAScript imports
+    transforms: ['typescript', 'jsx', 'imports']
+  })
+```
+
+Where `compiler` is a module defined in the [`compilerModule`](#compilermodule) option.
+
+## `compilerModule`
+
+Type: `String`, default: `sucrase`
+
+The compiler to transpile examples’ code. Styleguidist uses [Sucrase](https://github.com/alangpierce/sucrase/) by default to run modern ECMAScript code on the frontend.
+
+Styleguidist (via Sucrase) supports these proposed JavaScript features by default:
 
-Type: `Object`, default:
+- Optional chaining: `a?.b`.
+- Nullish coalescing: `a ?? b`.
+- Class fields: `class C { x = 1; }`. This includes static fields but not the `#x` private field syntax.
+- Numeric separators: `const n = 1_234`.
+- Optional catch binding: `try { doThing(); } catch {}`.
+
+These JavaScript features will be “pass through”, so they won’t cause a compilation error but your browser must support them:
+
+- Object rest/spread.
+- Async functions, and async iterators.
+- Newer regex features.
+
+Styleguidist also strips TypeScript and Flow type annotations, including TypeScript enums. It doesn’t do actual type checking but you cold use TypeScript or Flow in the examples.
+
+> **Info:** See [Sucrase docs](https://github.com/alangpierce/sucrase/#transforms) for more details.
+
+You can change the compiler by passing the name of the compiler npm package to this option:
 
 ```javascript
-{
-  // Don't include an Object.assign ponyfill, we have our own
-  objectAssign: 'Object.assign',
-  // Transpile only features needed for IE11
-  target: { ie: 11 },
-  transforms: {
-    // Don't throw on ESM imports, we transpile them ourselves
-    modules: false,
-    // Enable tagged template literals for styled-components
-    dangerousTaggedTemplateString: true,
-    // to make async/await work by default (no transformation)
-    asyncAwait: false,
-  },
+module.exports = {
+  compilerModule: '@babel/standalone'
 }
 ```
 
-Styleguidist uses [Bublé](https://buble.surge.sh/guide/) to run ES6 code on the frontend. This config object will be added as the second argument for `buble.transform`.
+> **Warning:** You should change [the `compileExample` option too](#compileexample) to adjust the call, and pass the options for your new compiler.
+
+> **Info:** See [the cookbook](Cookbook.md) to learn how to configure other compilers, like Babel or TypeScript.
+
+## `compilerConfig`
+
+This option has been deprecated, use the [`compilerModule`](#compilermodule) and [`compileExample`](#compileexample) options instead.
 
 ## `components`
 

docs/Cookbook.md

@@ -602,22 +602,74 @@ module.exports = {
 }
 ```
 
-## How to re-use the types in Styleguidist?
+## How to compile examples with Babel?
+
+By default, Stylegudist uses [Sucrase](https://github.com/alangpierce/sucrase/) to compiler examples’ code. To use Babel instead, you need to install [`@babel/standalone`](https://www.npmjs.com/package/@babel/standalone) as a dependency, and define [`compilerModule`](Configuration.md#compilermodule) and [`compileExample`](Configuration.md#compileexample) options:
+
+```js
+module.exports = {
+  compilerModule: '@babel/standalone',
+  compileExample: (compiler, code) =>
+    compiler.transform(code, {
+      presets: ['react', 'env']
+    }).code
+}
+```
+
+## How to compile examples with TypeScript?
+
+By default, Stylegudist uses [Sucrase](https://github.com/alangpierce/sucrase/) to compiler examples’ code. To use TypeScript instead, you need to install [`typescript`](https://www.npmjs.com/package/typescript) as a dependency, and define [`compilerModule`](Configuration.md#compilermodule) and [`compileExample`](Configuration.md#compileexample) options:
+
+```js
+module.exports = {
+  compilerModule: 'typescript',
+  compileExample: (compiler, code) => {
+    const compiledCode = compiler.transpileModule(code, {
+      compilerOptions: {
+        target: 'ES2015',
+        module: 'CommonJS',
+        jsx: 'react',
+        esModuleInterop: true
+      }
+    }).outputText
+    return `const exports = {}; ${compiledCode}`
+  }
+}
+```
+
+This works but gives a compilation warning from webpack: “Critical dependency: the request of a dependency is an expression”. We could silence it using the [`webpackConfig`](#webpackconfig) option and [`webpack-filter-warnings-plugin`](https://www.npmjs.com/package/webpack-filter-warnings-plugin):
+
+```js
+const FilterWarningsPlugin = require('webpack-filter-warnings-plugin')
+module.exports = {
+  webpackConfig: {
+    plugins: [
+      new webpack.FilterWarningsPlugin({
+        exclude: /Critical dependency: the request of a dependency is an expression/
+      })
+    ]
+  }
+}
+```
+
+**Note:** If you know a better way of using TypeScript compiler, please send a pull request.
+
+## How to reuse TypeScript types in Styleguidist?
 
 From version 10, Styleguidist is written using TypeScript language.
 
-It allows the maintainers to catch type mismatch before execution and gives them a better developer experience.
+It allows the maintainers to catch type mismatches before code execution, and gives them better developer experience.
 
 It also allows you to write customized style guide components using TypeScript TSX instead of JavaScript JSX.
 
-**NOTE:** Since all files in `src/client/rsg-components` are aliased to `rsg-components` using webpack, you will have to add this alias to your `tsconfig.json` file:
+**Note:** Since all files in `src/client/rsg-components` are aliased as `rsg-components` using webpack, you will have to add this alias to your `tsconfig.json` file:
 
 ```json
 {
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      // remap rsg-components/anything to its version in react-styleguidist
+      // Remap rsg-components/anything to its version in react-styleguidist
       "rsg-components/*": [
         "node_modules/react-styleguidist/lib/client/rsg-components/*"
       ]

docs/Documenting.md

@@ -222,7 +222,7 @@ Code examples in Markdown use ES6+JSX syntax. You can use the current component
 <Button>Push Me</Button>
 ````
 
-> **Info:** Styleguidist uses [Bublé](https://buble.surge.sh/guide/) to run ES6 code on the frontend, it supports [most of the ES6 features](https://buble.surge.sh/guide/#unsupported-features).
+> **Info:** Styleguidist uses [Sucrase](https://github.com/alangpierce/sucrase/) by default to run modern ECMAScript code on the frontend. [These language features are supported](Configuration.md#compiler).
 
 To use other components, you need to explicitly `import` them:
 

docs/Migration.md

@@ -0,0 +1,23 @@
+# Migration guide
+
+## 11 to 12
+
+### Remove or update `compilerConfig` config option
+
+Since Styleguidist is using [Sucrase](https://github.com/alangpierce/sucrase/) instead of [Bublé](https://buble.surge.sh/guide/) to compile examples’s code by default and allows you to chanage the compiler, the `compilerConfig` config option has been replaced with [`compilerModule`](Configuration.md#compilermodule) and [`compileExample`](Configuration.md#compileexample) options.
+
+Likely, you could remove the `compilerConfig` option.
+
+Otherwise, you could also keep using Bublé by installing `buble` as a dependency, and specifying the `compilerModule` option:
+
+```javascript
+module.exports = {
+  compilerModule: 'buble',
+  compileExample: (compiler, code) =>
+    compiler.transform(code, {
+      /* Bublé options */
+    }).code
+}
+```
+
+Check docs for [`compilerModule`](Configuration.md#compilermodule) and [`compileExample`](Configuration.md#compileexample) options for more details.