docs: document EcosystemProvider component for v2

Omnistac · bowheart · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025
commit 66a18e6f87671c8acc26cacf91fc7f128c6b6faa
diff --git a/docs/docs/v2/api/classes/Ecosystem.mdx b/docs/docs/v2/api/classes/Ecosystem.mdx
@@ -28,7 +28,7 @@ import { createEcosystem } from '@zedux/react'
 const rootEcosystem = createEcosystem({ id: 'root' })
 ```
 
-Ecosystems are also created automatically when using an [`<EcosystemProvider>`](/not-done?path=../components/EcosystemProvider) without passing an `ecosystem` prop:
+Ecosystems are also created automatically when using an [`<EcosystemProvider>`](../components/EcosystemProvider) without passing an `ecosystem` prop:
 
 ```tsx
 import { EcosystemProvider } from '@zedux/react'
@@ -48,11 +48,11 @@ The [default ecosystem](../../../walkthrough/ecosystems#global) will be created
 
 The default ecosystem is great for simple apps. It's a full ecosystem, which means you can use features like [overrides](#overrides) and [ecosystem events](#events). However, it comes preconfigured with no (good) way to set config options like [`ssr`](#ssr) and [`onReady`](#onready).
 
-It's generally recommended to create your own ecosystem(s) via [`createEcosystem()`](/not-done?path=../factories/createEcosystem) and provide them to your app via [`<EcosystemProvider>`](/not-done?path=../components/EcosystemProvider) instead of using the default ecosystem. This is especially needed for SSR.
+It's generally recommended to create your own ecosystem(s) via [`createEcosystem()`](/not-done?path=../factories/createEcosystem) and provide them to your app via [`<EcosystemProvider>`](../components/EcosystemProvider) instead of using the default ecosystem. This is especially needed for SSR.
 
 ## Providing
 
-Ecosystems can take control of all atom usages in a React component tree by wrapping the tree in [`<EcosystemProvider>`](/not-done?path=../components/EcosystemProvider).
+Ecosystems can take control of all atom usages in a React component tree by wrapping the tree in [`<EcosystemProvider>`](../components/EcosystemProvider).
 
 ```tsx
 function App() {
@@ -1109,6 +1109,6 @@ ecosystem.reset({ context: { redux: otherReduxStore } }) // replaces context
 - [the Plugins guide](../../../advanced/plugins)
 - [`getDefaultEcosystem()`](/not-done?path=../utils/getDefaultEcosystem)
 - [`setDefaultEcosystem()`](/not-done?path=../utils/setDefaultEcosystem)
-- [the `<EcosystemProvider>` component](/not-done?path=../components/EcosystemProvider)
+- [the `<EcosystemProvider>` component](../components/EcosystemProvider)
 - [the `useEcosystem` hook](/not-done?path=../hooks/useEcosystem)
 - [the `injectEcosystem` injector](/not-done?path=../injectors/injectEcosystem)
diff --git a/docs/docs/v2/api/components/EcosystemProvider.mdx b/docs/docs/v2/api/components/EcosystemProvider.mdx
@@ -0,0 +1,144 @@
+---
+id: EcosystemProvider
+title: EcosystemProvider
+---
+
+import { Legend, Item, Link, Tabs, Ts, tab1, tab2 } from '@site/src/all'
+
+```ts
+import { EcosystemProvider } from '@zedux/react'
+```
+
+A React component that provides an [ecosystem](../classes/Ecosystem) to a component tree. The provided ecosystem will take control of all atom usages below it.
+
+You can pass either an existing [ecosystem](../classes/Ecosystem) via the `ecosystem` prop or any number of [EcosystemConfig properties](/not-done?path=../types/EcosystemConfig) via their respectively named props.
+
+When passing config properties, the EcosystemProvider will create an ecosystem for you.
+
+## Examples
+
+Passing an ecosystem:
+
+```tsx
+import { EcosystemProvider, createEcosystem } from '@zedux/react'
+
+function App() {
+  // this is the recommended way for most apps to create an ecosystem -
+  // memoized in a top-level component.
+  const ecosystem = useMemo(
+    () => createEcosystem({ id: 'root', overrides: [someAtom] }),
+    []
+  )
+
+  return (
+    <EcosystemProvider ecosystem={ecosystem}>
+      <Routes />
+    </EcosystemProvider>
+  )
+}
+```
+
+Passing configuration:
+
+```tsx
+import { EcosystemProvider } from '@zedux/react'
+
+function App() {
+  return (
+    <EcosystemProvider id="root" overrides={[someAtom]}>
+      <Routes />
+    </EcosystemProvider>
+  )
+}
+```
+
+All Zedux hooks in any child component will use the provided ecosystem.
+
+Live example:
+
+```tsx live ecosystemId=EcosystemProvider noProvide=true resultVar=App version=2
+import { useEcosystem, EcosystemProvider } from '@zedux/react'
+
+function Example() {
+  const ecosystem = useEcosystem()
+
+  return <div>{ecosystem.id}</div>
+}
+
+function App() {
+  const ecosystem = useMemo(() => createEcosystem({ id: 'root' }), [])
+
+  return (
+    <>
+      <EcosystemProvider ecosystem={ecosystem}>
+        <Example />
+      </EcosystemProvider>
+
+      <Example />
+    </>
+  )
+}
+```
+
+## Signature
+
+<Tabs>
+  {tab1(
+    `<EcosystemProvider ecosystem={ecosystem}>
+    {children}
+  </EcosystemProvider>
+  // or
+  <EcosystemProvider {...ecosystemConfig}>
+    {children}
+  </EcosystemProvider>`,
+    true
+  )}
+  {tab2(`declare const EcosystemProvider: ({
+    children,
+    ecosystem,
+    ...ecosystemConfig
+  }:
+    | (Partial<{ [k in keyof EcosystemConfig]: undefined }> & {
+        children?: ReactNode
+        ecosystem?: Ecosystem
+      })
+    | (Partial<EcosystemConfig> & {
+        children?: ReactNode
+        ecosystem?: undefined
+      })) => React.JSX.Element`)}
+</Tabs>
+
+## Props
+
+You must pass either an `ecosystem` prop or any combination of the ecosystem config props (no props is also fine) but not both.
+
+<Legend>
+
+  <Item name="children">
+    Pass a single ReactNode child. To pass multiple components, wrap them in a React Fragment.
+
+  </Item>
+  <Item name="ecosystem">
+    An ecosystem created via [`createEcosystem()`](/not-done?path=../factories/createEcosystem).
+
+    Passing this gives you the most control over the ecosystem, at the cost of being a little lower-level.
+
+    Make sure this ecosystem reference is stable. Changing the reference is supported, but is almost never what you want as it will recreate the entire cache for all atom usages below this component.
+
+  </Item>
+  <Item name="ecosystemConfig">
+    See [the EcosystemConfig type](/not-done?path=../types/EcosystemConfig) for all the other props and their types. The EcosystemConfig key names have a one-to-one mapping with props of this component.
+
+    If the `id` prop is changed, Zedux will completely destroy the previous ecosystem and create a new one using the id and the current value of all the other EcosystemConfig props. Changing any other props besides `id` will have no effect unless `id` is also changed.
+
+    This overload is for convenience when you don't need to configure the ecosystem much. If you need more power, pass an `ecosystem` and manage it yourself.
+
+  </Item>
+</Legend>
+
+## See Also
+
+- [The Ecosystems walkthrough](../../../walkthrough/ecosystems.mdx)
+- [The `EcosystemConfig` type](/not-done?path=../types/EcosystemConfig)
+- [The `Ecosystem` class](../classes/Ecosystem)
+- [The `useEcosystem` hook](/not-done?path=../hooks/useEcosystem)
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -177,7 +177,10 @@ module.exports = {
         {
           type: 'category',
           label: 'Components',
-          items: ['v2/api/components/AtomProvider'],
+          items: [
+            'v2/api/components/AtomProvider',
+            'v2/api/components/EcosystemProvider',
+          ],
         },
         {
           type: 'category',