From 81250d3a8c39da09e7874c0154785b80ba76cb4e Mon Sep 17 00:00:00 2001 From: Mark Dalgleish Date: Mon, 30 Jan 2023 14:12:56 +1100 Subject: [PATCH] docs: add CSS bundle tree-shaking issue warnings --- docs/guides/styling.md | 5 ++++- docs/pages/gotchas.md | 15 +++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/guides/styling.md b/docs/guides/styling.md index 611ec55bb89..68cd5597ab0 100644 --- a/docs/guides/styling.md +++ b/docs/guides/styling.md @@ -770,6 +770,8 @@ NOTE: You may run into hydration warnings when using Styled Components. Hopefull CSS bundling features are unstable and currently only available behind feature flags. We're confident in the use cases they solve but the API and implementation may change in the future. +When using CSS bundling features, you should avoid using `export *` due to an [issue with esbuild's CSS tree shaking][esbuild-css-tree-shaking-issue]. + Many common approaches to CSS within the React community are only possible when bundling CSS, meaning that the CSS files you write during development are collected into a separate bundle as part of the build process. When using CSS bundling features, the Remix compiler will generate a single CSS file containing all bundled styles in your application. Note that any [regular stylesheet imports][regular-stylesheet-imports] will remain as separate files. @@ -943,9 +945,10 @@ module.exports = { [styled-components-issue]: https://github.com/styled-components/styled-components/issues/3660 [tailwind]: https://tailwindcss.com [tailwind-intelli-sense-extension]: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss +[esbuild-css-tree-shaking-issue]: https://github.com/evanw/esbuild/issues/1370 [css modules]: https://github.com/css-modules/css-modules [regular-stylesheet-imports]: #regular-stylesheets [server-dependencies-to-bundle]: ../file-conventions/remix-config#serverdependenciestobundle [css-bundling]: #css-bundling [vanilla-extract]: https://vanilla-extract.style -[sprinkles]: https://vanilla-extract.style/documentation/packages/sprinkles +[sprinkles]: https://vanilla-extract.style/documentation/packages/sprinkles \ No newline at end of file diff --git a/docs/pages/gotchas.md b/docs/pages/gotchas.md index 837b55ae4d3..a3381dea9da 100644 --- a/docs/pages/gotchas.md +++ b/docs/pages/gotchas.md @@ -168,4 +168,19 @@ This is a hydration warning from React, and is most likely due to one of your br Check out the page in incognito mode, the warning should disappear. +## CSS bundle being incorrectly tree-shaken + +When using [CSS bundling features][css-bundling] in combination with `export *` (e.g. when using an index file like `components/index.ts` that re-exports from all sub-directories) you may find that styles from the re-exported modules are missing from the build output. + +This is due to an [issue with esbuild's CSS tree shaking][esbuild-css-tree-shaking-issue]. As a workaround, you should use named re-exports instead. + +```diff +-export * from "./Button"; ++export { Button } from "./Button"; +``` + +Note that, even if this issue didn't exist, we'd still recommend using named re-exports! While it may introduce a bit more boilerplate, you get explicit control over the module's public interface rather than inadvertently exposing everything. + [remix-upload-handlers-like-unstable-create-file-upload-handler-and-unstable-create-memory-upload-handler]: ../utils/parse-multipart-form-data#uploadhandler +[css-bundling]: ../guides/styling#css-bundling +[esbuild-css-tree-shaking-issue]: https://github.com/evanw/esbuild/issues/1370