Skip to content

Commit

Permalink
Copy more content from internal docs to external docs
Browse files Browse the repository at this point in the history
  • Loading branch information
dddlr committed Oct 15, 2024
1 parent 9073acc commit 36358db
Showing 1 changed file with 25 additions and 1 deletion.
26 changes: 25 additions & 1 deletion website/packages/docs/src/pages/css-extraction-webpack.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,16 @@ If your package is a component library, use our **platform stylesheet extraction

If your package exists in the same codebase as, and is _directly consumed_ by, a Webpack or Parcel app, use **Parcel stylesheet extraction** or **Webpack stylesheet extraction** depending on what bundler your app uses.

Note that we currently do not support other bundlers.
Note that Parcel and Webpack are the only bundlers we support.

## Platform stylesheet extraction

Platform stylesheet extraction only works if you use Babel to build your component library. Note that we do not recommend nor support using bundlers (e.g. Webpack or Parcel) to build your component library, because bundlers are appropriate for web apps (e.g. Jira) and not for component libraries.

> **Warning**<br/>
> Ensure that any apps that import your component library also have the Compiled Webpack or Parcel plugins installed (`@compiled/webpack-loader` or `@compiled/parcel-config`), otherwise the order in which the styles are applied will become unpredictable. This can be an issue if you have styles that overlap, e.g. if you mix `padding` and `paddingTop` in the same component, or have `@media` queries that potentially overlap.<br/><br/>
> If the apps that import your component library use other bundlers like Vite or Next.js, or if your apps cannot install the Compiled Webpack or Parcel plugins, stylesheet extraction will still work! However, you must make sure that within each component, you should _never_ mix any CSS properties or styles that overlap.
Add `@compiled/babel-plugin-strip-runtime` to your Babel configuration, with `extractStylesToDirectory` set as an option. Set `source` to the folder your component library's source code is defined in, and `dest` to the folder your component library's build output is generated to.

For example:
Expand Down Expand Up @@ -58,6 +62,26 @@ module.exports = {

Your `dest` may vary depending on how you generate your `dist/` folder in your component library. For example, if you have mutliple `cjs` and `esm` distributions, those will each need a separate `dest` through Babel's environment-specific configuration.

In each component library's `package.json` file, you will also need to add `"sideEffects": ["**/*.compiled.css"]`, to ensure that the Compiled stylesheets that are generated are exempt from Webpack's and Parcel's tree-shaking (which would delete the stylesheets!):

```json
{
"name": "@example/my-component-library",
// …
"dependencies": {
// Replace "version" with the latest version
"@compiled/react": "^version"
},
// …
"sideEffects": ["**/*.compiled.css"]
// …
}
```

To test whether you've set up stylesheet extraction correctly, use your component library's usual build command (e.g. `yarn build`). Inside the `dist` folder, you should see some `.compiled.css` stylesheets generated, one for each `.tsx` file that uses `@compiled/react`.

For example, if you have a file with the path `packages/design-system/button/dist/cjs/button.js` that uses Compiled, you can expect there to be a corresponding `packages/design-system/button/dist/cjs/button.compiled.css`.

## Parcel stylesheet extraction

If you are using a web app that uses Parcel, first install the [Parcel loader](https://compiledcssinjs.com/docs/installation#installation-methods).
Expand Down

0 comments on commit 36358db

Please sign in to comment.