](https://www.npmjs.com/package/@chialab/cjs-to-esm) |
-| [@chialab/esbuild-plugin-any-file](./packages/esbuild-plugin-any-file) | A loader plugin for esbuild for files with unknown loader. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-any-file) |
-| [@chialab/esbuild-plugin-babel](./packages/esbuild-plugin-babel) | A pluggable esbuild plugin that runs babel for es5 transpilation. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-babel) |
-| [@chialab/esbuild-plugin-commonjs](./packages/esbuild-plugin-commonjs) | A commonjs to esm converter for esbuild. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-commonjs) |
-| [@chialab/esbuild-plugin-css-import](./packages/esbuild-plugin-css-import) | Resolve CSS imports using the node resolution algorithm and the style field in package.json. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-css-import) |
-| [@chialab/esbuild-plugin-env](./packages/esbuild-plugin-env) | Define all environement variables for esbuild. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-env) |
-| [@chialab/esbuild-plugin-html](./packages/esbuild-plugin-html) | A HTML loader plugin for esbuild. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-html) |
-| [@chialab/esbuild-plugin-lightningcss](./packages/esbuild-plugin-lightningcss) | A CSS loader plugin for esbuild that uses lightningcss as preprocessor. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-lightningcss) |
-| [@chialab/esbuild-plugin-meta-url](./packages/esbuild-plugin-meta-url) | A file loader plugin for esbuild for constructed URLs using import metadata. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-meta-url) |
-| [@chialab/esbuild-plugin-metadata](./packages/esbuild-plugin-metadata) | Write `entrypoints.json` for esbuild builds. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-metadata) |
-| [@chialab/esbuild-plugin-postcss](./packages/esbuild-plugin-postcss) | A CSS loader plugin for esbuild that uses postcss as preprocessor. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-postcss) |
-| [@chialab/esbuild-plugin-unwebpack](./packages/esbuild-plugin-unwebpack) | Remove webpack features from sources. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-unwebpack) |
-| [@chialab/esbuild-plugin-worker](./packages/esbuild-plugin-worker) | Collect and transpile Web Workers with esbuild. | [
](https://www.npmjs.com/package/@chialab/esbuild-plugin-worker) |
-| [@chialab/esbuild-rna](./packages/esbuild-rna) | A framework for esbuild plugins with transform and emit capabilities. | [
](https://www.npmjs.com/package/@chialab/esbuild-rna) |
-| [@chialab/estransform](./packages/estransform) | Execute multiple transformations on JavaScript sources with full sourcemaps support. | [
](https://www.npmjs.com/package/@chialab/estransform) |
-| [@chialab/node-resolve](./packages/node-resolve) | A promise based node resolution library based on enhanced-resolve. | [
](https://www.npmjs.com/package/@chialab/node-resolve) |
-| [@chialab/postcss-preset-chialab](./packages/postcss-preset-chialab) | The postcss preset used by Chialab. | [
](https://www.npmjs.com/package/@chialab/postcss-preset-chialab) |
-| [@chialab/postcss-dart-sass](./packages/postcss-dart-sass) | AA postcss plugin that uses dart sass to transpile scss files. | [
](https://www.npmjs.com/package/@chialab/postcss-dart-sass) |
-| [@chialab/postcss-url-rebase](./packages/postcss-url-rebase) | A postcss plugin for url() rebasing before import. | [
](https://www.npmjs.com/package/@chialab/postcss-url-rebase) |
-| [@chialab/rna](./packages/rna) | A bundler, a server and a test runner for modern modules and applications. | [
](https://www.npmjs.com/package/@chialab/rna) |
-| [@chialab/rna-browser-test-runner](./packages/rna-browser-test-runner) | A test runner for browsers based on Web Test Runner. | [
](https://www.npmjs.com/package/@chialab/rna-browser-test-runner) |
-| [@chialab/rna-bundler](./packages/rna-bundler) | A JavaScript, CSS and HTML bundler based on esbuild. | [
](https://www.npmjs.com/package/@chialab/rna-bundler) |
-| [@chialab/rna-config-loader](./packages/rna-config-loader) | Load and setup RNA configuration object. | [
](https://www.npmjs.com/package/@chialab/rna-config-loader) |
-| [@chialab/rna-node-test-runner](./packages/rna-node-test-runner) | A test runner for node based on mocha. | [
](https://www.npmjs.com/package/@chialab/rna-node-test-runner) |
-| [@chialab/rna-saucelabs-test-runner](./packages/rna-saucelabs-test-runner) | A test runner for Saucelabs based on on Web Test Runner. | [
](https://www.npmjs.com/package/@chialab/rna-saucelabs-test-runner) |
-| [@chialab/rna-dev-server](./packages/rna-dev-server) | A webapp server based on Web Dev Server. | [
](https://www.npmjs.com/package/@chialab/rna-dev-server) |
-| [@chialab/wds-plugin-hmr](./packages/wds-plugin-hmr) | Enable ES modules and CSS hot module replacement for the web dev server. | [
](https://www.npmjs.com/package/@chialab/wds-plugin-hmr) |
-| [@chialab/wds-plugin-legacy](./packages/wds-plugin-legacy) | Transform esm modules served by the web dev server into SystemJS modules for legacy browser compatibility. | [
](https://www.npmjs.com/package/@chialab/wds-plugin-legacy) |
-| [@chialab/wds-plugin-node-resolve](./packages/wds-plugin-node-resolve) | A plugin the Web Dev Server for node resolutions. | [
](https://www.npmjs.com/package/@chialab/wds-plugin-node-resolve) |
-| [@chialab/wds-plugin-polyfill](./packages/wds-plugin-polyfill) | Inject polyfills to HTML responses served by the web dev server. | [
](https://www.npmjs.com/package/@chialab/wds-plugin-polyfill) |
-| [@chialab/wds-plugin-rna](./packages/wds-plugin-rna) | A plugin for the Web Dev Server to transpile sources using the RNA bundler. | [
](https://www.npmjs.com/package/@chialab/wds-plugin-rna) |
-| [@chialab/wtr-mocha-reporter](./packages/wtr-mocha-reporter) | A Mocha reporter interface for the Web Test Runner. | [
](https://www.npmjs.com/package/@chialab/wtr-mocha-reporter) |
diff --git a/docs/Testing-saucelabs.md b/docs/Testing-saucelabs.md
deleted file mode 100644
index d03db9fd..00000000
--- a/docs/Testing-saucelabs.md
+++ /dev/null
@@ -1 +0,0 @@
-# Testing in SauceLabs
diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
deleted file mode 100644
index a25a75a4..00000000
--- a/docs/_Sidebar.md
+++ /dev/null
@@ -1,45 +0,0 @@
-- [Home](./)
-
-### Framework
-
-- [Architecture](./Architecture)
-- [Plugins](./Plugins)
-- [Write a plugin](./Write-a-plugin)
-
-### Build
-
-- [Building JavaScript](./Building-javascript)
- - [Bundling for the Web](./Building-javascript#bundling-for-the-web)
- - [Bundling for Node](./Building-javascript#bundling-for-node)
- - [Modules resolution](./Building-javascript#modules-resolution)
- - [Code splitting](./Building-javascript#code-splitting)
- - [TypeScript](./Building-javascript#typescript)
- - [ENV variables](./Building-javascript#env-variables)
- - [Assets](./Building-javascript#assets)
- - [JSX](./Building-javascript#jsx)
- - [Targeting ES5](./Building-javascript#targeting-es5)
-- [Building CSS](./Building-css)
- - [Assets](./Building-css#assets)
- - [Dependencies](./Building-css#dependencies)
- - [PostCSS](./Building-css#postcss)
-- [Building Web Apps](./Building-web-apps)
- - [Collecting scripts](./Building-web-apps#collecting-scripts)
- - [Collecting styles](./Building-web-apps#collecting-styles)
- - [Icons](./Building-web-apps#icons)
- - [Web manifest](./Building-web-apps#web-manifest)
-
-### Dev Server
-
-- [Dev server for Web Apps](./Dev-server-web-apps)
- - [Legacy browsers](./Dev-server-web-apps#legacy-browsers)
- - [Dev server service](./Dev-server-web-apps#dev-server-as-service)
-
-### Testing
-
-- [Testing in the browser](./Testing-browser)
-- [Testing in node](./Testing-node)
-- [Testing in SauceLabs](./Testing-saucelabs)
-
-### Tutorials
-
-- [Migrate CRA to RNA](./Migrate-CRA)
diff --git a/docs/Architecture.md b/docs/guide/architecture.md
similarity index 100%
rename from docs/Architecture.md
rename to docs/guide/architecture.md
diff --git a/docs/Building-css.md b/docs/guide/building-css.md
similarity index 82%
rename from docs/Building-css.md
rename to docs/guide/building-css.md
index 9555d181..d940704d 100644
--- a/docs/Building-css.md
+++ b/docs/guide/building-css.md
@@ -6,24 +6,40 @@ Unless you are using syntaxes like Sass and Less, CSS builds are less expansive
Even if [esbuild](https://esbuild.github.io/) has out of the box support for CSS files, in order to bundle a CSS module using RNA you may have to install the bundler package along with the postcss plugin for node modules resolution:
-```sh
+::: code-group
+
+```sh[npm]
npm i -D @chialab/rna
```
-```sh
+```sh[yarn]
yarn add -D @chialab/rna
```
+```sh[pnpm]
+pnpm add -D @chialab/rna
+```
+
+:::
+
and run:
-```sh
+::: code-group
+
+```sh[npm]
npx rna build src/index.css --output public/index.css
```
-```sh
+```sh[yarn]
yarn rna build src/index.css --output public/index.css
```
+```sh[pnpm]
+pnpx rna build src/index.css --output public/index.css
+```
+
+:::
+
A CSS bundle will be generated as well as its source map (unless you added the `--no-map` flag).
For production environments, you may want to minify output using the `--minify` flag.
@@ -55,13 +71,27 @@ RNA already uses it to convert dependencies imports to relative references in or
We built a [custom PostCSS preset](https://www.npmjs.com/package/@chialab/postcss-preset-chialab) with common rules we use in every project.
You can install it using npm or yarn:
-```sh
-npm i @chialab/postcss-preset-chialab -D
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/postcss-preset-chialab
+```
+
+```sh[yarn]
+yarn add -D @chialab/postcss-preset-chialab
```
+```sh[pnpm]
+pnpm add -D @chialab/postcss-preset-chialab
+```
+
+:::
+
And creating or updating tghe postcss config file:
-```json
+::: code-group
+
+```json[postcss.config.json]
{
"plugins": {
"@chialab/postcss-preset-chialab": {}
@@ -69,7 +99,7 @@ And creating or updating tghe postcss config file:
}
```
----
+:::
## Recommendations
@@ -78,26 +108,52 @@ And creating or updating tghe postcss config file:
Although out of RNA scope, we strongly recommend to use a linter for CSS projects. Our preferred one is [Stylelint](https://stylelint.io/) that is built upon the PostCSS parser.
First, you need to install the stylelint cli:
-```sh
+::: code-group
+
+```sh[npm]
npm i -D stylelint
```
+```sh[yarn]
+yarn add -D stylelint
+```
+
+```sh[pnpm]
+pnpm add -D stylelint
+```
+
+:::
+
Please follow official guide for [linter configuration](https://stylelint.io/user-guide/configure).
We also provide our configuration preset:
-```sh
+::: code-group
+
+```sh[npm]
npm i -D @chialab/stylelint-config
```
-**.stylelintrc.json**
+```sh[yarn]
+yarn add -D @chialab/stylelint-config
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/stylelint-config
+```
-```json
+:::
+
+::: code-group
+
+```json[.stylelintrc.json]
{
"extends": "@chialab/stylelint-config"
}
```
+:::
+
Also, do not forget to install the linter extension for your IDE:
- [VSCode](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint)
diff --git a/docs/Building-javascript.md b/docs/guide/building-javascript.md
similarity index 65%
rename from docs/Building-javascript.md
rename to docs/guide/building-javascript.md
index b4b5f0c5..ffeb2778 100644
--- a/docs/Building-javascript.md
+++ b/docs/guide/building-javascript.md
@@ -10,24 +10,40 @@ Using [esbuild](https://esbuild.github.io/) under the hood, RNA combines the fat
In order to bundle a JS module using RNA you may have to install the bundler:
-```sh
+::: code-group
+
+```sh[npm]
npm i -D @chialab/rna
```
-```sh
+```sh[yarn]
yarn add -D @chialab/rna
```
+```sh[pnpm]
+pnpm add -D @chialab/rna
+```
+
+:::
+
and run:
-```sh
+::: code-group
+
+```sh[npm]
npx rna build src/index.js --output public/index.js
```
-```sh
+```sh[yarn]
yarn rna build src/index.js --output public/index.js
```
+```sh[pnpm]
+pnpx rna build src/index.js --output public/index.js
+```
+
+:::
+
This will generate a ESM bundle at the `--output` destination. Using `--format` and `--platform` flags we can generate multiple bundles that targets both browser and Node environments.
## Bundling for the Web
@@ -36,27 +52,21 @@ The Web is the primary target of the RNA toolchain. Everything is optimized for
So, the explicit command is equivalent to the previous run snippet:
```sh
-npx rna build src/index.js --output public/index.js --format esm --platform browser
-```
-
-```sh
-yarn rna build src/index.js --output public/index.js --format esm --platform browser
+rna build src/index.js --output public/index.js --format esm --platform browser
```
When targeting the browser platform, RNA will respect your `browser` configuration in the `package.json` in order to optimize the build for the requested environment.
Using the `browser` field is optimal for modules that need to run in both browser and node environments:
-**input**
+::: code-group
-```javascript
+```ts[src/index.js]
import jsdom from 'jsdom';
const document = typeof window !== undefined ? window.document : new jsdom.JSOM().window.document;
```
-**package.json**
-
-```json
+```json[package.json]
{
"browser": {
"jsdom": false
@@ -64,48 +74,48 @@ const document = typeof window !== undefined ? window.document : new jsdom.JSOM(
}
```
-**output**
+:::
+
+::: code-group
-```javascript
+```ts[public/index.js]
const document = typeof window !== undefined ? window.document : undefined;
```
+:::
+
## Bundling for Node
Node is also a first class output. Specifying the `cjs` format, RNA will automatically target the `node` platform, converting every `import` statements to `require` invokations.
```sh
-npx rna build src/index.js --output public/index.js --format cjs --platform node
+rna build src/index.js --output public/index.js --format cjs --platform node
```
-```sh
-yarn rna build src/index.js --output public/index.js --format cjs --platform node
-```
+::: code-group
-**input**
-
-```javascript
+```ts[src/index.js]
import jsdom from 'jsdom';
const document = typeof window !== undefined ? window.document : new jsdom.JSOM().window.document;
```
-**output**
+:::
+
+::: code-group
-```javascript
+```ts[public/index.js]
const jsdom = require('jsdom');
const document = typeof window !== undefined ? window.document : new jsdom.JSOM().window.document;
```
-Since even the LTS version of node supports ES modules, you may want to target node with the `esm` format:
+:::
-```sh
-npx rna build src/index.js --output public/index.js --format esm --platform node
-```
+Since even the LTS version of node supports ES modules, you may want to target node with the `esm` format:
```sh
-yarn rna build src/index.js --output public/index.js --format esm --platform node
+rna build src/index.js --output public/index.js --format esm --platform node
```
## Modules resolution
@@ -160,9 +170,9 @@ Dynamic imports and URL assets can be used to split the code into multiple chunk
For example:
-**app.js**
+::: code-group
-```js
+```ts[app.js]
import { route } from 'router';
import { render } from 'view';
@@ -172,9 +182,7 @@ route('/profile', async () => {
});
```
-**Profile.js**
-
-```js
+```ts[Profile.js]
import { render } from 'view';
export function Profile() {
@@ -182,6 +190,8 @@ export function Profile() {
}
```
+:::
+
The build step of this app will generate 3 chunks:
- **vendors.js** that includes the `view` dependency
@@ -195,68 +205,109 @@ TypeScript syntax is supported out of the box from esbuild, also respecting your
However, please not that esbuild will only transpile your source without checking your code. For typechecking, you still need the vanilla `tsc` cli:
-```sh
+::: code-group
+
+```sh[npm]
npm i -D typescript
```
-```sh
+```sh[yarn]
yarn add -D typescript
```
+```sh[pnpm]
+pnpm add -D typescript
+```
+
+:::
+
You can run tsc with the `--noEmit` flag in order to execute typecheck only:
```sh
-npx tsc --noEmit
+tsc --noEmit
```
-```sh
-yarn tsc --noEmit
+### Type imports
+
+During the build step, esbuild removes type references and it is smart enough to detect side effects imports, but sometimes circular dependencies can cause imports order and dead code elimination issues.
+
+Since version 4, TypeScript introduced the `import type` statement that instructs the bundlers how a reference is used.
+It is recommended to use this feature to import interfaces, types and references used as type only.
+
+For example:
+
+::: code-group
+
+```ts[src/index.ts]
+import { Child } from './Child';
+
+export class Parent {
+ children: Child[] = [];
+
+ addChild(name: string) {
+ this.children.push(new Child(name, this));
+ }
+}
```
-
+```
+
+This will result in:
+
+```html
+
+```
+
+### Icons
+
+Manually generate favicons can be a pain. This plugin detects a `` node and uses its reference to generate icons and launch screens for (almost) every browser.
+
+**Sample**
+
+```html
+
+```
+
+This will result in:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+It also update `` content if found.
diff --git a/docs/guide/esbuild-plugin-meta-url.md b/docs/guide/esbuild-plugin-meta-url.md
new file mode 100644
index 00000000..24907a78
--- /dev/null
+++ b/docs/guide/esbuild-plugin-meta-url.md
@@ -0,0 +1,42 @@
+# esbuild-plugin-meta-url
+
+A file loader plugin for [esbuild](https://esbuild.github.io/) for constructed URLs using import metadata.
+
+The plugin looks for `new URL('path/to/file.png', import.meta.url)` in JavaScript and TypeScript files and instructs esbuild to copy referenced files. This is a standard version of the file loader.
+
+```js
+// DONT ❌
+import img from './logo.png';
+
+// DO ✅
+const img = new URL('./logo.png', import.meta.url).href;
+```
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/esbuild-plugin-meta-url
+```
+
+```sh[yarn]
+yarn add -D @chialab/esbuild-plugin-meta-url
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/esbuild-plugin-meta-url
+```
+
+:::
+
+## Usage
+
+```ts
+import metaUrlPlugin from '@chialab/esbuild-plugin-meta-url';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+ plugins: [metaUrlPlugin()],
+});
+```
diff --git a/docs/guide/esbuild-plugin-metadata.md b/docs/guide/esbuild-plugin-metadata.md
new file mode 100644
index 00000000..facb91c3
--- /dev/null
+++ b/docs/guide/esbuild-plugin-metadata.md
@@ -0,0 +1,70 @@
+# esbuild-plugin-metadata
+
+Write a entrypoints.json manifest for esbuild builds.
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/esbuild-plugin-metadata
+```
+
+```sh[yarn]
+yarn add -D @chialab/esbuild-plugin-metadata
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/esbuild-plugin-metadata
+```
+
+:::
+
+## Usage
+
+```ts
+import metadataPlugin from '@chialab/esbuild-plugin-metadata';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+ plugins: [
+ metadataPlugin({
+ entrypoints: {
+ metafilePath: 'webroot/metafile.json',
+ manifestPath: 'webroot/manifest.json',
+ entrypointsPath: 'webroot/entrypoints.json',
+ },
+ }),
+ ],
+});
+```
+
+::: code-group
+
+```json[webroot/entrypoints.json]
+{
+ "index": {
+ "format": "esm",
+ "js": ["http://localhost:3000/__web-dev-server__web-socket.js", "http://localhost:3000/index.js"],
+ "css": ["http://localhost:3000/index.css"]
+ }
+}
+```
+
+:::
+
+Then, you can read this file and load resources in your PHP application:
+
+```twig
+{% set entrypoints = 'webroot/entrypoints.json'|file_get_content|json_decode %}
+{% for script in entrypoints.index.js %}
+
+{% endfor %}
+{% for link in entrypoints.index.css %}
+
+{% endfor %}
+```
+
+Here is a list of RNA-based helpers for common frameworks:
+
+- [RNA CakePHP](https://github.com/chialab/rna-cakephp)
diff --git a/docs/guide/esbuild-plugin-postcss.md b/docs/guide/esbuild-plugin-postcss.md
new file mode 100644
index 00000000..6a8df8ea
--- /dev/null
+++ b/docs/guide/esbuild-plugin-postcss.md
@@ -0,0 +1,54 @@
+# esbuild-plugin-postcss
+
+A CSS loader plugin for [esbuild](https://esbuild.github.io/) that uses [PostCSS](https://postcss.org/) as preprocessor.
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/esbuild-plugin-postcss
+```
+
+```sh[yarn]
+yarn add -D @chialab/esbuild-plugin-postcss
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/esbuild-plugin-postcss
+```
+
+:::
+
+## Usage
+
+```js
+import postcssPlugin from '@chialab/esbuild-plugin-postcss';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+ plugins: [postcssPlugin()],
+});
+```
+
+This plugin looks for a postcss configuration in the project and fallbacks to out custom [postcss-preset-env](https://www.npmjs.com/package/postcss-preset-env).
+
+### Sass
+
+The plugin automatically tries to load the `@chialab/postcss-plugin-dart-sass` when it processes `.scss` files. Please make sure to have installed the optional dependency in order to correctly transpiler Sass files:
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/postcss-plugin-dart-sass
+```
+
+```sh[yarn]
+yarn add -D @chialab/postcss-plugin-dart-sass
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/postcss-plugin-dart-sass
+```
+
+:::
diff --git a/docs/guide/esbuild-plugin-require-resolve.md b/docs/guide/esbuild-plugin-require-resolve.md
new file mode 100644
index 00000000..81ab9fa8
--- /dev/null
+++ b/docs/guide/esbuild-plugin-require-resolve.md
@@ -0,0 +1,36 @@
+# esbuild-plugin-require-resolve
+
+A file loader plugin for [esbuild](https://esbuild.github.io/) for `require.resolve` statements.
+
+## How it works
+
+The plugin looks for `require.resolve('path/to/file.png')` statements in JavaScript and TypeScript files and instructs esbuild to copy referenced files.
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/esbuild-plugin-require-resolve
+```
+
+```sh[yarn]
+yarn add -D @chialab/esbuild-plugin-require-resolve
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/esbuild-plugin-require-resolve
+```
+
+:::
+
+## Usage
+
+```ts
+import requireResolvePlugin from '@chialab/esbuild-plugin-require-resolve';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+ plugins: [requireResolvePlugin()],
+});
+```
diff --git a/docs/guide/esbuild-plugin-virtual.md b/docs/guide/esbuild-plugin-virtual.md
new file mode 100644
index 00000000..6a90358b
--- /dev/null
+++ b/docs/guide/esbuild-plugin-virtual.md
@@ -0,0 +1,51 @@
+# esbuild-plugin-virtual
+
+A virtual file system for [esbuild](https://esbuild.github.io/) modules.
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/esbuild-plugin-virtual
+```
+
+```sh[yarn]
+yarn add -D @chialab/esbuild-plugin-virtual
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/esbuild-plugin-virtual
+```
+
+:::
+
+## Usage
+
+Define a virtual module:
+
+```ts
+import virtualPlugin from '@chialab/esbuild-plugin-virtual';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+ entrypoints: ['index.js'],
+ plugins: [
+ virtualPlugin([
+ {
+ path: 'virtual-entry.js',
+ contents: 'export const nil = () => {};',
+ loader: 'js',
+ },
+ ]),
+ ],
+});
+```
+
+::: code-group
+
+```ts[index.js]
+import { nil } from 'virtual-entry.js';
+
+nil();
+```
diff --git a/docs/guide/esbuild-plugin-worker.md b/docs/guide/esbuild-plugin-worker.md
new file mode 100644
index 00000000..f5847624
--- /dev/null
+++ b/docs/guide/esbuild-plugin-worker.md
@@ -0,0 +1,70 @@
+# esbuild-plugin-worker
+
+Collect and transpile Web Workers with [esbuild](https://esbuild.github.io/).
+
+## How it works
+
+The plugin looks for `new Worker('./path/to/worker.js')` statements in JavaScript and TypeScript files and instructs esbuild to treat that references as entrypoints. Final output will be used to correctly update the statement.
+
+For example, the following script:
+
+```ts
+const worker = new Worker('./path/to/worker.js');
+```
+
+will be transformed to:
+
+```ts
+const worker = new Worker(new URL('./path/to/worker.js', import.meta.url));
+```
+
+and then resolved by the [`@chialab/esbuild-plugin-meta-url`](./esbuild-plugin-meta-url) plugin.
+
+Please note that RNA does not generate a `Worker` class to instantiate like webpack does, but it will just correctly update the import reference. If you need a `Worker` class, you have to wrap it yourself:
+
+```javascript
+const workerClass = function () {
+ return new Worker('./path/to/worker.js');
+};
+```
+
+::: warning
+
+At the moment this plugin does not collect `importScript()` statements and does treat workers as modules, but we have plan to support the `{ type: "module" }` option in the near future.
+
+:::
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/esbuild-plugin-worker
+```
+
+```sh[yarn]
+yarn add -D @chialab/esbuild-plugin-worker
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/esbuild-plugin-worker
+```
+
+:::
+
+## Usage
+
+```ts
+import workerPlugin from '@chialab/esbuild-plugin-worker';
+import esbuild from 'esbuild';
+
+await esbuild.build({
+ plugins: [workerPlugin()],
+});
+```
+
+You can also define a list of Worker constructors to use (default it will look for `Worker` and `SharedWorker`):
+
+```ts
+workerPlugin({ constructors: ['Worker', 'MyWorker'] });
+```
diff --git a/docs/Home.md b/docs/guide/index.md
similarity index 79%
rename from docs/Home.md
rename to docs/guide/index.md
index 071994a8..cfa411e9 100644
--- a/docs/Home.md
+++ b/docs/guide/index.md
@@ -1,18 +1,20 @@
+# Get started
+
## RNA is a bundler
RNA bundler is heavily based on [esbuild](https://esbuild.github.io/), _an extremely fast JavaScript bundler_ with some pre-configured addons. It can bundle and optimize JavaScript, TypeScript, JSX, CSS and HTML and collect referenced assets just using languages features.
The bundler is designed for modern browsers, but it can transpile code for IE11 and other legacy browsers with [Babel](https://babeljs.io/) and [PostCSS](https://postcss.org/) plugins.
-- [Build a JavaScript module](./Building-javascript)
-- [Build a CSS module](./Building-css)
-- [Build a Web App](./Building-web-apps)
+- [Build a JavaScript module](./building-javascript)
+- [Build a CSS module](./building-css)
+- [Build a Web App](./building-web-apps)
## RNA is a dev server
Build plugins are also available for the [Web Dev Server](https://modern-web.dev/docs/dev-server/overview/). Since both WDS and RNA aim to use standard syntax and practises in web projects, you can run a local server with hot module replacement and CSS livereload without have to bundle your web app first or to re-run a partial build for each change. Files loaded via ESM will pass through a little esbuild transpilation in order to support TypeScript, CommonJS modules and node resolution, making a great difference in developer experience. The dev server can be used also for PHP with an Encore-like approach.
-- [Dev server for web apps](./Dev-server-web-apps)
+- [Dev server for web apps](./dev-server)
## RNA is a browser and node test runner
@@ -20,32 +22,45 @@ Built on the Web Dev Server, a configured instance of the [Web Test Runner](http
Since RNA aims to support both browser and Node modules, you can test your modules in Node environments using the RNA test runner based on [Mocha](https://mochajs.org/). Coverage is also available thanks to the v8 coverage tool.
-- [Testing in the browser](./Testing-browser)
-- [Testing in node](./Testing-node)
-- [Testing in SauceLabs](./Testing-saucelabs)
+- [Testing in the browser](./testing-browser)
+- [Testing in node](./testing-node)
## RNA is a build framework
We built RNA to be pluggable and to be interoperable with other build systems. A lot of esbuild and postcss plugins are distribuited as standalone packages in order to be reused outside the RNA opinionated ecosystem. We also designed a micro-sdk for esbuild plugin authors that handles transform pipelines and emits chunks or files.
-- [Architecture](./Architecture)
-- [List of modules](./Plugins)
-- [Write a plugin](./Write-a-plugin)
-
## RNA is a cli
### Quick usage
-```sh
+::: code-group
+
+```sh[npm]
npm i -D \
@chialab/rna \
@chialab/rna-dev-server \
@chialab/rna-browser-test-runner
```
-**package.json**
+```sh[yarn]
+yarn add -D \
+ @chialab/rna \
+ @chialab/rna-dev-server \
+ @chialab/rna-browser-test-runner
+```
-```json
+```sh[pnpm]
+pnpm add -D \
+ @chialab/rna \
+ @chialab/rna-dev-server \
+ @chialab/rna-browser-test-runner
+```
+
+:::
+
+::: code-group
+
+```json[package.json]
{
"scripts": {
"start": "rna serve src --port 3000",
@@ -55,6 +70,4 @@ npm i -D \
}
```
-### Tutorials
-
-- [Migrate Create React App to RNA](./Migrate-CRA)
+:::
diff --git a/docs/Migrate-CRA.md b/docs/guide/migrate-CRA.md
similarity index 87%
rename from docs/Migrate-CRA.md
rename to docs/guide/migrate-CRA.md
index 46d840c5..80cad948 100644
--- a/docs/Migrate-CRA.md
+++ b/docs/guide/migrate-CRA.md
@@ -7,11 +7,23 @@ In this tutorial we will migrate [Create React App](https://facebook.github.io/c
The RNA dev server works serving a source directory that contains one (or more) HTML entrypoints. CRA static files are stored under the `public` folder, so we need to move them to the `src` directory:
```sh
-$ mv public/index.html src/index.html
-$ mv public/favicon.ico src/favicon.ico
-$ mv public/logo192.png src/logo192.png
-$ mv public/logo512.png src/logo512.png
-$ mv public/manifest.json src/manifest.json
+mv public/index.html src/index.html
+```
+
+```sh
+mv public/favicon.ico src/favicon.ico
+```
+
+```sh
+mv public/logo192.png src/logo192.png
+```
+
+```sh
+mv public/logo512.png src/logo512.png
+```
+
+```sh
+mv public/manifest.json src/manifest.json
```
### Replace `%PUBLIC_URL%` with local references
@@ -54,14 +66,22 @@ Optionally, you can also include a bundle for browsers that don't support ESM mo
First, we need to install `rna` dependencies:
-```sh
+::: code-group
+
+```sh[npm]
npm i -D @chialab/rna @chialab/rna-dev-server
```
-```sh
+```sh[yarn]
yarn add -D @chialab/rna @chialab/rna-dev-server
```
+```sh[pnpm]
+pnpm add -D @chialab/rna @chialab/rna-dev-server
+```
+
+:::
+
Then, we are ready to update the `package.json` file to replace `react-scripts` witn `rna`.
We will pass `--jsxImportSource` to make sure `React` JSX pragma is imported in JavaScript files. Other JSX configurations for React are automatically loaded by `esbuild`.
diff --git a/docs/guide/postcss-dart-sass.md b/docs/guide/postcss-dart-sass.md
new file mode 100644
index 00000000..bb952428
--- /dev/null
+++ b/docs/guide/postcss-dart-sass.md
@@ -0,0 +1,27 @@
+# postcss-dart-sass
+
+A [PostCSS](https://postcss.org/) plugin that uses dart [sass](https://sass-lang.com/) to transpile scss files.
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/postcss-dart-sass
+```
+
+```sh[yarn]
+yarn add -D @chialab/postcss-dart-sass
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/postcss-dart-sass
+```
+
+:::
+
+## Usage
+
+```ts
+import '@chialab/postcss-dart-sass';
+```
diff --git a/docs/guide/postcss-url-rebase.md b/docs/guide/postcss-url-rebase.md
new file mode 100644
index 00000000..e2d17a2d
--- /dev/null
+++ b/docs/guide/postcss-url-rebase.md
@@ -0,0 +1,32 @@
+# postcss-url-rebase
+
+A [PostCSS](https://postcss.org/) plugin for `url()` rebasing before import.
+
+## Install
+
+::: code-group
+
+```sh[npm]
+npm i -D @chialab/postcss-url-rebase
+```
+
+```sh[yarn]
+yarn add -D @chialab/postcss-url-rebase
+```
+
+```sh[pnpm]
+pnpm add -D @chialab/postcss-url-rebase
+```
+
+:::
+
+## Usage
+
+```ts
+import postcss from 'postcss';
+import urlRebase from '@chialab/postcss-url-rebase';
+
+postcss([
+ urlRebase(),
+]).process(...);
+```
diff --git a/docs/Testing-browser.md b/docs/guide/testing-browser.md
similarity index 80%
rename from docs/Testing-browser.md
rename to docs/guide/testing-browser.md
index f0513680..021a5ed7 100644
--- a/docs/Testing-browser.md
+++ b/docs/guide/testing-browser.md
@@ -1 +1,3 @@
# Testing in the browser
+
+TODO
diff --git a/docs/Testing-node.md b/docs/guide/testing-node.md
similarity index 75%
rename from docs/Testing-node.md
rename to docs/guide/testing-node.md
index 15fb63f1..ea666c3c 100644
--- a/docs/Testing-node.md
+++ b/docs/guide/testing-node.md
@@ -1 +1,3 @@
# Testing in Node
+
+TODO
diff --git a/docs/Write-a-plugin.md b/docs/guide/write-a-plugin.md
similarity index 100%
rename from docs/Write-a-plugin.md
rename to docs/guide/write-a-plugin.md
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..4f57ce5c
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,26 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+title: RNA
+titleTemplate: Build tools for modern web modules and applications
+
+hero:
+ name: 'RNA'
+ tagline: 'Build tools for modern web modules and applications'
+ image:
+ src: https://raw.githubusercontent.com/chialab/rna/main/logo.svg
+ alt: RNA logo
+ actions:
+ - theme: brand
+ text: npm i -D @chialab/rna
+ link: /guide/
+
+features:
+ - title: Modular
+ details: RNA is an ecosystem of modular plugins for common bundlers and transformers like esbuild and postcss. Every feature is a standalone package that can be installed and used independently.
+ icon:
+ - title: A toolchain
+ details: RNA is a toolchain for common frontend (and JavaScript in general) tasks with a strong conventions over configuration and largely opinionated policy.
+ icon:
+---
diff --git a/package.json b/package.json
index 66004d64..76efd77d 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,9 @@
"lint": "prettier --check . && eslint 'packages/*/lib/**/*.js'",
"test": "rna test:node packages/*/test/**/*.spec.js --coverage",
"new": "plop --plopfile internals/generators/plopfile.cjs module",
+ "docs:dev": "vitepress dev docs",
+ "docs:build": "vitepress build docs",
+ "docs:preview": "vitepress preview docs",
"version": "changeset version && YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install"
},
"repository": {
diff --git a/packages/esbuild-plugin-any-file/README.md b/packages/esbuild-plugin-any-file/README.md
index 9abffeec..10fe7a31 100644
--- a/packages/esbuild-plugin-any-file/README.md
+++ b/packages/esbuild-plugin-any-file/README.md
@@ -6,30 +6,9 @@
----
+## Documentation
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-any-file -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-any-file -D
-```
-
-## Usage
-
-```js
-import filePlugin from '@chialab/esbuild-plugin-any-file';
-import esbuild from 'esbuild';
-
-await esbuild.build({
- plugins: [filePlugin()],
-});
-```
-
----
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-any-file).
## License
diff --git a/packages/esbuild-plugin-babel/README.md b/packages/esbuild-plugin-babel/README.md
index afbf069d..e4b3391a 100644
--- a/packages/esbuild-plugin-babel/README.md
+++ b/packages/esbuild-plugin-babel/README.md
@@ -1,39 +1,14 @@
- Esbuild Plugin Babel • A pluggable esbuild plugin that runs babel for es5 transpilation. + Esbuild Plugin Babel • An esbuild plugin that runs babel for es5 transpilation.
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-commonjs -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-commonjs -D
-```
-
-## Usage
-
-```js
-import commonjsPlugin from '@chialab/esbuild-plugin-commonjs';
-import esbuild from 'esbuild';
+## Documentation
-await esbuild.build({
- plugins: [commonjsPlugin()],
-});
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-commonjs).
---
diff --git a/packages/esbuild-plugin-css-import/README.md b/packages/esbuild-plugin-css-import/README.md
index e178c6d1..e3c4ac5a 100644
--- a/packages/esbuild-plugin-css-import/README.md
+++ b/packages/esbuild-plugin-css-import/README.md
@@ -6,59 +6,9 @@
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-css-import -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-css-import -D
-```
-
-## Usage
-
-This plugin enables the node resolution algorithm for CSS files. That means that `@import` and `@url()` statements can refer to both relative files and NPM packages. CSS modules must have the `style` field in their pakcage.json in order to correctly pickup the CSS entrypoint.
-
-```js
-import cssImportPlugin from '@chialab/esbuild-plugin-css-import';
-import esbuild from 'esbuild';
-
-await esbuild.build({
- plugins: [cssImportPlugin()],
-});
-```
-
-### Example
-
-**node_modules/css-framework/package.json**
-
-```json
-{
- "name": "css-framework",
- "style": "index.css"
-}
-```
-
-**node_modules/css-framework/index.css**
-
-```css
-:root {
- --accent-color: #000;
-}
-```
-
-**src/main.css**
-
-```css
-@import 'css-framework';
+## Documentation
-body {
- color: var(--accent-color);
-}
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-css-import).
---
diff --git a/packages/esbuild-plugin-env/README.md b/packages/esbuild-plugin-env/README.md
index 933c8fe6..36222f18 100644
--- a/packages/esbuild-plugin-env/README.md
+++ b/packages/esbuild-plugin-env/README.md
@@ -6,28 +6,9 @@
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-env -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-env -D
-```
-
-## Usage
-
-```js
-import envPlugin from '@chialab/esbuild-plugin-env';
-import esbuild from 'esbuild';
+## Documentation
-await esbuild.build({
- plugins: [envPlugin()],
-});
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-env).
---
diff --git a/packages/esbuild-plugin-html/README.md b/packages/esbuild-plugin-html/README.md
index 07115df3..a70bfb8e 100644
--- a/packages/esbuild-plugin-html/README.md
+++ b/packages/esbuild-plugin-html/README.md
@@ -6,233 +6,9 @@
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-html -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-html -D
-```
-
-## Usage
-
-The plugin tries to respect esbuild configuration closely as possible. Since it treats HTML files as entrypoints, the resulting documents will use the pattern provided by `entryNames`, while JavaScript and CSS files will be written using the `chunkNames` config. Other files use the `assetNames` option.
-
-### Common configurations
-
-#### Build mode
-
-```js
-import htmlPlugin from '@chialab/esbuild-plugin-html';
-import esbuild from 'esbuild';
-
-await esbuild.build({
- entryPoints: ['src/index.html'],
- outdir: 'public',
- assetNames: 'assets/[name]-[hash]',
- chunkNames: '[ext]/[name]-[hash]',
- plugins: [htmlPlugin()],
-});
-```
-
-The output structure would be something similar to:
-
-```
-public
-├── index.html
-├── assets/favicon-YYYYY.png
-├── css/style-YYYYY.css
-├── css/style-YYYYY.css.map
-├── js/index-YYYYY.js
-└── js/index-YYYYY.js.map
-```
-
-#### Serve mode
-
-```js
-import htmlPlugin from '@chialab/esbuild-plugin-html';
-import esbuild from 'esbuild';
-
-await esbuild.serve(
- {
- servedir: 'public',
- },
- {
- entryPoints: ['src/index.html'],
- outdir: 'public',
- assetNames: 'assets/[name]',
- chunkNames: '[ext]/[name]',
- plugins: [htmlPlugin()],
- }
-);
-```
-
-### Options
-
-The HTML plugin accepts an options object with the following properties:
-
-#### `scriptsTarget`
-
-The target of the plain scripts build (`type="text/javascript"`).
-
-#### `modulesTarget`
-
-The target of the ES modules build (`type="module"`).
-
----
-
-## How it works
-
-**Esbuild Plugin HTML** instructs esbuild to load a HTML file as entrypoint. It parses the HTML and runs esbuild on scripts, styles, assets and icons.
-
-### Scripts
-
-It handles both inline and file scripts. When the `type="module"` attribute is found in the `
-
-```
-
-This will result in producing two bundles:
-
-```html
-
-
-```
-
-### Styles
-
-It supports both `` and `
-```
-
-This will result in producing two css bundles:
-
-```html
-
-
-```
-
-### Assets
-
-Referenced files by `src` and `href` attributes are copy along the html file in the `assets` directory.
-
-**Sample**
-
-```html
-
-```
-
-This will result in:
-
-```html
-
-```
-
-### Icons
-
-Manually generate favicons can be a pain. This plugin detects a `` node and uses its reference to generate icons and launch screens for (almost) every browser.
-
-**Sample**
-
-```html
-
-```
-
-This will result in:
-
-```html
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-```
+## Documentation
-It also update `` content if found.
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-html).
---
diff --git a/packages/esbuild-plugin-meta-url/README.md b/packages/esbuild-plugin-meta-url/README.md
index 08f709f0..39813a6c 100644
--- a/packages/esbuild-plugin-meta-url/README.md
+++ b/packages/esbuild-plugin-meta-url/README.md
@@ -6,42 +6,9 @@
----
-
-## How it works
-
-**Esbuild Plugin Meta Url** looks for `new URL('path/to/file.png', import.meta.url)` in JavaScript and TypeScript files and instructs esbuild to copy referenced files. This is a standard version of the file loader.
-
-```js
-// DONT ❌
-import img from './logo.png';
-
-// DO ✅
-const img = new URL('./logo.png', import.meta.url).href;
-```
-
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-meta-url -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-meta-url -D
-```
-
-## Usage
-
-```js
-import metaUrlPlugin from '@chialab/esbuild-plugin-meta-url';
-import esbuild from 'esbuild';
+## Documentation
-await esbuild.build({
- plugins: [metaUrlPlugin()],
-});
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-meta-url).
---
diff --git a/packages/esbuild-plugin-metadata/README.md b/packages/esbuild-plugin-metadata/README.md
index a7065a14..d9029c89 100644
--- a/packages/esbuild-plugin-metadata/README.md
+++ b/packages/esbuild-plugin-metadata/README.md
@@ -1,41 +1,14 @@
- esbuild-plugin-metadata • Write entrypoints.json for esbuild builds. + esbuild-plugin-metadata • Write entrypoints.json manifest for esbuild builds.
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-postcss -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-postcss -D
-```
-
-## Usage
-
-```js
-import postcssPlugin from '@chialab/esbuild-plugin-postcss';
-import esbuild from 'esbuild';
-
-await esbuild.build({
- plugins: [postcssPlugin()],
-});
-```
-
-This plugin looks for a postcss configuration in the project and fallbacks to out custom [postcss-preset-env](https://www.npmjs.com/package/postcss-preset-env).
-
-### Sass
-
-The plugin automatically tries to load the `@chialab/postcss-plugin-dart-sass` when it processes `.scss` files. Please make sure to have installed the optional dependency in order to correctly transpiler Sass files:
-
-```sh
-npm i @chialab/postcss-plugin-dart-sass -D
-```
+## Documentation
-```sh
-yarn add @chialab/postcss-plugin-dart-sass -D
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-postcss).
---
diff --git a/packages/esbuild-plugin-virtual/README.md b/packages/esbuild-plugin-virtual/README.md
index 15f20be3..6cf2f64f 100644
--- a/packages/esbuild-plugin-virtual/README.md
+++ b/packages/esbuild-plugin-virtual/README.md
@@ -6,47 +6,9 @@
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-virtual -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-virtual -D
-```
-
-## Usage
-
-Define a virtual module:
-
-```js
-import virtualPlugin from '@chialab/esbuild-plugin-virtual';
-import esbuild from 'esbuild';
-
-await esbuild.build({
- entrypoints: ['index.js'],
- plugins: [
- virtualPlugin([
- {
- path: 'virtual-entry.js',
- contents: 'export const nil = () => {};',
- loader: 'js',
- },
- ]),
- ],
-});
-```
-
-**index.js**
-
-```js
-import { nil } from 'virtual-entry.js';
+## Documentation
-nil();
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-virtual).
---
diff --git a/packages/esbuild-plugin-worker/README.md b/packages/esbuild-plugin-worker/README.md
index 140e6437..f61d6afa 100644
--- a/packages/esbuild-plugin-worker/README.md
+++ b/packages/esbuild-plugin-worker/README.md
@@ -6,65 +6,9 @@
----
-
-## How it works
-
-**Esbuild Plugin Worker** looks for `new Worker('./path/to/worker.js')` statements in JavaScript and TypeScript files and instructs esbuild to treat that references as entrypoints. Final output will be used to correctly update the statement.
-
-For example, the following script:
-
-```js
-const worker = new Worker('./path/to/worker.js');
-```
-
-will be transformed to:
-
-```js
-const worker = new Worker(new URL('./path/to/worker.js', import.meta.url));
-```
-
-and then resolved by the [`@chialab/esbuild-plugin-meta-url`](../esbuild-plugin-meta-url) plugin.
-
-Please note that RNA does not generate a `Worker` class to instantiate like webpack does, but it will just correctly update the import reference. If you need a `Worker` class, you have to wrap it yourself:
-
-```javascript
-const workerClass = function () {
- return new Worker('./path/to/worker.js');
-};
-```
-
-⚠️ At the moment this plugin does not collect `importScript()` statements and does treat workers as modules, but we have plan to support the `{ type: "module" }` option in the near future.
-
----
-
-## Install
-
-```sh
-npm i @chialab/esbuild-plugin-worker -D
-```
-
-```sh
-yarn add @chialab/esbuild-plugin-worker -D
-```
-
-## Usage
-
-```js
-import metaUrlPlugin from '@chialab/esbuild-plugin-meta-url';
-import workerPlugin from '@chialab/esbuild-plugin-worker';
-import esbuild from 'esbuild';
-
-await esbuild.build({
- plugins: [workerPlugin(), metaUrlPlugin()],
-});
-```
-
-You can also define a list of Worker constructors to use (default it will look for `Worker` and `SharedWorker`):
+## Documentation
-```js
-workerPlugin({ constructors: ['Worker', 'MyWorker'] });
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/esbuild-plugin-worker).
---
diff --git a/packages/postcss-dart-sass/README.md b/packages/postcss-dart-sass/README.md
index 1653a282..640ab148 100644
--- a/packages/postcss-dart-sass/README.md
+++ b/packages/postcss-dart-sass/README.md
@@ -6,23 +6,9 @@
----
-
-## Install
-
-```sh
-npm i @chialab/postcss-dart-sass -D
-```
-
-```sh
-yarn add @chialab/postcss-dart-sass -D
-```
-
-## Usage
+## Documentation
-```js
-import '@chialab/postcss-dart-sass';
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/postcss-dart-sass).
---
diff --git a/packages/postcss-url-rebase/README.md b/packages/postcss-url-rebase/README.md
index cc53239c..e3a05110 100644
--- a/packages/postcss-url-rebase/README.md
+++ b/packages/postcss-url-rebase/README.md
@@ -6,26 +6,9 @@
-## Install
+## Documentation
-```sh
-npm i @chialab/postcss-url-rebase -D
-```
-
-```sh
-yarn add @chialab/postcss-url-rebase -D
-```
-
-## Usage
-
-```js
-import postcss from 'postcss';
-import urlRebase from '@chialab/postcss-url-rebase';
-
-postcss([
- urlRebase(),
-]).process(...);
-```
+Read the documentation at [chialab.github.io/rna](https://chialab.github.io/rna/guide/postcss-url-rebase).
---