Clarify preact/compat integration docs (#4267)

* Clarify preact/compat integration * Create long-lobsters-ring.md Co-authored-by: Fred K. Schott <[email protected]>
withastro · Aug 11, 2022 · 5b1facf · 5b1facf
1 parent 52068e2
commit 5b1facf
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 0 deletions.
diff --git a/.changeset/long-lobsters-ring.md b/.changeset/long-lobsters-ring.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/preact": patch
+---
+
+README: Clarify `compat` docs
diff --git a/packages/integrations/preact/README.md b/packages/integrations/preact/README.md
@@ -104,6 +104,23 @@ export default defineConfig({
 
 With the `compat` option enabled, the Preact integration will render React components as well as Preact components in your project and also allow you to import React components inside Preact components. Read more in [“Switching to Preact (from React)”](https://preactjs.com/guide/v10/switching-to-preact) on the Preact website.
 
+When importing React component libraries, in order to swap out the `react` and `react-dom` dependencies as `preact/compat`, you can use [`overrides`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides) to do so.
+
+```js
+// package.json
+{
+  "overrides": {
+    "react": "npm:@preact/compat@latest",
+    "react-dom": "npm:@preact/compat@latest"
+  }
+}
+```
+
+Check out the [`pnpm` overrides](https://pnpm.io/package_json#pnpmoverrides) and [`yarn` resolutions](https://yarnpkg.com/configuration/manifest#resolutions) docs for their respective overrides features.
+
+> **Note**
+> Currently, the `compat` option only works for React libraries that export code as ESM. If an error happens during build-time, try adding the library to `vite.ssr.noExternal: ['the-react-library']` in your `astro.config.mjs` file.
+
 
 ## Examples