docs: document the new getDefaultEcosystem util for v2

Omnistac · bowheart · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025
commit 50a09219827167a8bd735b200b02aa557b527e72
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>`](../components/EcosystemProvider) without passing an `ecosystem` prop:
+Ecosystems are also created automatically when using an [`<EcosystemProvider>`](../components/EcosystemProvider.mdx) without passing an `ecosystem` prop:
 
 ```tsx
 import { EcosystemProvider } from '@zedux/react'
@@ -44,15 +44,15 @@ function App() {
 
 ### Default Ecosystem
 
-The [default ecosystem](../../../walkthrough/ecosystems#global) will be created automatically if atoms are used in React outside any `<EcosystemProvider>` or the first time you call [`getDefaultEcosystem()`](/not-done?path=../utils/getDefaultEcosystem).
+The [default ecosystem](../../../walkthrough/ecosystems.mdx#global) will be created automatically if atoms are used in React outside any `<EcosystemProvider>` or the first time you call [`getDefaultEcosystem()`](../utils/getDefaultEcosystem.mdx).
 
 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()`](../factories/createEcosystem.mdx) and provide them to your app via [`<EcosystemProvider>`](../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()`](../factories/createEcosystem.mdx) and provide them to your app via [`<EcosystemProvider>`](../components/EcosystemProvider.mdx) 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>`](../components/EcosystemProvider).
+Ecosystems can take control of all atom usages in a React component tree by wrapping the tree in [`<EcosystemProvider>`](../components/EcosystemProvider.mdx).
 
 ```tsx
 function App() {
@@ -1091,12 +1091,11 @@ ecosystem.reset({ context: { redux: otherReduxStore } }) // replaces context
 
 ## See Also
 
-- [the Ecosystems walkthrough](../../../walkthrough/ecosystems)
+- [the Ecosystems walkthrough](../../../walkthrough/ecosystems.mdx)
 - [the `createEcosystem()` factory](../factories/createEcosystem.mdx)
-- [the Overrides walkthrough](../../../walkthrough/overrides)
-- [the Plugins guide](../../../advanced/plugins)
-- [`getDefaultEcosystem()`](/not-done?path=../utils/getDefaultEcosystem)
-- [`setDefaultEcosystem()`](/not-done?path=../utils/setDefaultEcosystem)
-- [the `<EcosystemProvider>` component](../components/EcosystemProvider)
+- [the Overrides walkthrough](../../../walkthrough/overrides.mdx)
+- [the Plugins guide](../../../advanced/plugins.mdx)
+- [`getDefaultEcosystem()`](../utils/getDefaultEcosystem.mdx)
+- [the `<EcosystemProvider>` component](../components/EcosystemProvider.mdx)
 - [the `useEcosystem` hook](../hooks/useEcosystem.mdx)
 - [the `injectEcosystem` injector](../injectors/injectEcosystem.mdx)
diff --git a/docs/docs/v2/api/hooks/useEcosystem.mdx b/docs/docs/v2/api/hooks/useEcosystem.mdx
@@ -57,4 +57,4 @@ function App() {
 
 - [The `Ecosystem` class](../classes/Ecosystem.mdx)
 - [The `<EcosystemProvider>` component](../components/EcosystemProvider.mdx)
-- [The `getDefaultEcosystem()` utility](/not-done?path=../utils/getDefaultEcosystem.mdx)
+- [The `getDefaultEcosystem` utility](../utils/getDefaultEcosystem.mdx)
diff --git a/docs/docs/v2/api/utils/getDefaultEcosystem.mdx b/docs/docs/v2/api/utils/getDefaultEcosystem.mdx
@@ -0,0 +1,46 @@
+---
+id: getDefaultEcosystem
+title: getDefaultEcosystem
+---
+
+import { Legend, Item, Link, Tabs, Ts, tab1, tab2 } from '@site/src/all'
+
+```ts
+import { getDefaultEcosystem } from '@zedux/react'
+```
+
+Returns the [default ecosystem](../classes/Ecosystem.mdx#default-ecosystem). Creates it if it doesn't exist yet.
+
+## Example
+
+```tsx live ecosystemId=example/getDefaultEcosystem resultVar=id version=2
+import { getDefaultEcosystem } from '@zedux/react'
+
+const ecosystem = getDefaultEcosystem()
+const { id } = ecosystem
+```
+
+## Signature
+
+<Tabs>
+  {tab1(`getDefaultEcosystem = () => Ecosystem`)}
+  {tab2(`declare const getDefaultEcosystem: () => Ecosystem<any>`)}
+</Tabs>
+
+<Legend>
+
+  <Item name="Returns">
+    An [Ecosystem](../classes/Ecosystem.mdx) instance.
+
+    The first time this is called, the default ecosystem will be created and cached in Zedux's module state. Subsequent calls will return the cached instance.
+  </Item>
+
+</Legend>
+
+## See Also
+
+- [The Ecosystems walkthrough](../../../walkthrough/ecosystems.mdx)
+- [The `Ecosystem` class](../classes/Ecosystem.mdx)
+- [The `<EcosystemProvider>` component](../components/EcosystemProvider.mdx)
+- [The `createEcosystem()` factory](../factories/createEcosystem.mdx)
+- [The `useEcosystem()` hook](../hooks/useEcosystem.mdx)
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -232,7 +232,11 @@ module.exports = {
         {
           type: 'category',
           label: 'Utils',
-          items: ['v2/api/utils/As', 'v2/api/utils/inject'],
+          items: [
+            'v2/api/utils/As',
+            'v2/api/utils/getDefaultEcosystem',
+            'v2/api/utils/inject',
+          ],
         },
         'v2/api/glossary',
       ],