Skip to content

Commit 1f4dcce

Browse files
titouanmathistitouanmathis
committed
Clarify runtime-specific storage providers in docs
1 parent 4ff32ce commit 1f4dcce

7 files changed

Lines changed: 26 additions & 16 deletions

File tree

‎packages/docs/api/html/data-component.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,10 +51,14 @@ The previous HTML example can be rewritten to:
5151
<title>App</title>
5252
</head>
5353
<body>
54-
<div data-component="Component"></div> // [!code --]
55-
<div data-component="CustomName"></div> // [!code --]
56-
<tk-component></tk-component> // [!code ++]
57-
<tk-custom-name></tk-custom-name> // [!code ++]
54+
<div data-component="Component"></div>
55+
// [!code --]
56+
<div data-component="CustomName"></div>
57+
// [!code --]
58+
<tk-component></tk-component>
59+
// [!code ++]
60+
<tk-custom-name></tk-custom-name>
61+
// [!code ++]
5862
</body>
5963
</html>
6064
```

‎packages/docs/utils/storage/createLocalStorage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# createLocalStorage
22

3-
Create a storage instance backed by `localStorage`. Values persist across page reloads and are synced across tabs via the `storage` event.
3+
Create a storage instance backed by `globalThis.localStorage`. The underlying storage is resolved lazily from `globalThis` when the instance is used, so it can be imported before a browser-like global exists. Values persist across page reloads and are synced across tabs via the `storage` event when available.
44

55
## Usage
66

‎packages/docs/utils/storage/createSessionStorage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# createSessionStorage
22

3-
Create a storage instance backed by `sessionStorage`. Values persist for the duration of the page session.
3+
Create a storage instance backed by `globalThis.sessionStorage`. The underlying storage is resolved lazily from `globalThis` when the instance is used, so it can be imported before a browser-like global exists. Values persist for the duration of the page session when available.
44

55
## Usage
66

‎packages/docs/utils/storage/createUrlSearchParamsInHashStorage.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Create a storage instance backed by URL hash params (`#key=value`). Useful for client-side state that shouldn't be sent to the server, like tab selection or UI mode.
44

5+
This storage is browser-only: it requires `window.location` and `window.history`. The browser context is checked when the provider is created. In non-browser environments, it falls back to a no-op provider.
6+
57
By default, changes use `replaceState` to avoid polluting browser history. Use `{ push: true }` to create history entries instead.
68

79
## Usage

‎packages/docs/utils/storage/createUrlSearchParamsStorage.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Create a storage instance backed by URL search params (`?key=value`). Useful for shareable UI state like filters, pagination, or sort order.
44

5+
This storage is browser-only: it requires `window.location` and `window.history`. The browser context is checked when the provider is created. In non-browser environments, it falls back to a no-op provider.
6+
57
By default, changes use `replaceState` to avoid polluting browser history. Use `{ push: true }` to create history entries instead.
68

79
## Usage

‎packages/docs/utils/storage/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Storage
22

3-
Utilities to manage browser storage with a unified API. Supports `localStorage`, `sessionStorage`, URL search params and URL hash params, with automatic serialization, reactive subscriptions, cross-tab sync and key namespacing.
3+
Utilities to manage browser storage with a unified API. Supports `localStorage`, `sessionStorage`, URL search params and URL hash params, with automatic serialization, reactive subscriptions, cross-tab sync and key namespacing. Storage backends are resolved safely from the current global/browser context, and URL-based storages no-op outside browser environments.
44

55
- [createStorage](./createStorage.html)
66
- [createLocalStorage](./createLocalStorage.html)

‎packages/docs/utils/storage/providers.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,18 @@ Storage providers are the low-level adapters that read and write to a specific s
44

55
## Built-in providers
66

7-
| Provider | Backend | Sync event |
8-
| ------------------------------- | ----------------- | --------------------- |
9-
| `localStorageProvider` | `localStorage` | `storage` (cross-tab) |
10-
| `sessionStorageProvider` | `sessionStorage` | none |
11-
| `urlSearchParamsProvider` | URL search params | `popstate` |
12-
| `urlSearchParamsInHashProvider` | URL hash params | `hashchange` |
7+
| Provider | Backend | Sync event |
8+
| ------------------------------- | --------------------------- | --------------------- |
9+
| `localStorageProvider` | `globalThis.localStorage` | `storage` (cross-tab) |
10+
| `sessionStorageProvider` | `globalThis.sessionStorage` | none |
11+
| `urlSearchParamsProvider` | URL search params | `popstate` |
12+
| `urlSearchParamsInHashProvider` | URL hash params | `hashchange` |
13+
14+
`localStorageProvider` and `sessionStorageProvider` resolve their `globalThis.*Storage` backend lazily on each access instead of capturing it when the module is imported. This makes them safe to import before a browser-like global is available, and lets tests or non-DOM runtimes provide storage later.
1315

1416
### Provider factories
1517

16-
For URL-based providers, factory functions allow customizing the history behavior:
18+
For URL-based providers, factory functions allow customizing the history behavior. These providers check for a browser context when the provider is created. If `window.location` or `window.history` is unavailable, they return a no-op provider instead of throwing.
1719

1820
```js twoslash
1921
// @twoslash-cache: {"v":1,"hash":"90ef5b3acd98c5ace6e14b8466f5416ce19de7d1fba0875819c96dfe5a9a7b0b","data":"N4Igdg9gJgpgziAXAbVAFwJ4AcZJACwgDcYAnEAGhDRgA808AKAQwBsBLZuASgAIAzAK5gAxmnYQwvEaRjMaAVVKsAynNIj8ABWalmAWzhbSxdrFKMsJombIB5LOMlwA/Il5LWx0+YdOwPO4qaBB6AOYw3jbmADpg7PpYoWjSsvIwnmq6mjp6hlG25FRQECIIiCAAwmk0vMweAEoAMlka2roGcLxWPmQAdJTUzGHlyMggWB36gz3R9o4SAbx+i138obxo+DDd1oUDALoU47JogqQBlGCCrKwHRyBwaLoMiACMb1SsMGBhW0gAJgAnFRnqQIq8QDI5IplK0clMjHtzIMOGBcO8qJoOmIyICAL4UdDYDEEYh40F0SEsDhcPhCUT+VIwjJw9QIvJwACSYAAElxtMiyJYhaQVs43B5lAVfAtnNwgiFwpFRXEEklSCloelMuz2pyefy4ILekUQCUynhqiy6o0Wnrcp1eOwpPgBbtTQNQcNRuNJnkZqLxUtg2sNlsdrN9iAjicYGcLggKNdbvcqE8XkgACxZr4/P74JAAZgArN7wfG8NrYaoHYjDQKZRSQGiMQCsW69LjyIgAYTiTg8IQSGaaPQq84UlhBMam6RFaFhirTQAeJ6kF1hAB8gwzmqQbwAHJ8W/n/u920MK5Dp7PRaiXRiAGwdnE0HtP/vUElD8mjqlMGwnA8MyOpstk+qdHOIqmqGkqeHOoYKrwwSLhEc5qokySgTW8KQfk97FKU5RVDUOz1AozR4Y6hgenMpBekMIxIGMExTIGsFyiGXFhqQmzbHR0axiApznJcyY3HcDx7q8bxAi+p6/OewLlhCVZkbqEE0UipoPuiSAKdiXbvoCbxfpgg4VMOzZjtSPQ4JqGB8AhQY8X0t74JKABGEAQN8zBSAAPrwwiwPwj5QIMFokQA6tsEZ8SEIVwDsAAGHnBOkqXOgENDMFAvAQPwvCpbIWCsMwIgwJlNCpYxzzMSg4xhcwNwMFQ/BsClMbSWCrwAgCh55kphaILmV5qRUHl6c+r7GXiiAlkW5k/lZf6DLZE65d0M74EaJr0QuypzmuaAbr8O7pn1gJZiCikFgeClgpNEy7ftc4zUgADsc2VSZiCfkS36WWSI4bQBFQ0sBfDVqytZafWfKNqKMH0XB7guZx/iBChSpLhh8RYZqOFw9RiPvYR5rEVaZG2pR9oI5yOW8G6xqCeY9U+ixfrsVQUaytjyw8QI4YCfz/QxscInxmJSYplJV2Zr2T5Dfd56lqplYVLDmltNpDZ3rpXyPt9v3doCJYrSD1n/uOkP2WQmDOdKrnY+5u3eb5/lBSFYBhRFUXUxUcXxtsiUQMlaUZc8tU5U8cgFUVJVlRVVU1TAdUbVzTXmjAnVtYMnWsN1aaPNdiBFgADAp3wjdmms3rtn2ID9UKdn9C1PstDwiNApLqthwBxLwJO6xyUGihQw+j+Bevk8jppT2A+ICCY+i8AA5AAAk8ghQBI+jxswAD0ABWcAALQhH5ADW7BoMfgjiMXG8ANxxHEx/Hx4KVdNH6RxzyonYqEZeAtTarwFOlVqoxxgHEXu20PJzl4AAXhnvDOenJoLAB2sadwZ1BA7HxNwd+ohJy4L2gveiqD0FkwNEjQ29FGA4I8vg0ghDeDENfoMQ+zwkCgCpD8OAiw8DnxAPifEQA=="}
@@ -79,7 +81,7 @@ const storage = createStorage({ provider: cookieProvider });
7981
Providers can declare a `syncEvent` string to indicate which DOM event should trigger re-reading values for subscribed keys. When set, `createStorage` will automatically listen to this event on `window` and notify subscribers.
8082

8183
- `'storage'` — for cross-tab sync (`localStorage`)
82-
- `'popstate'` — for back/forward navigation (URL search params)
83-
- `'hashchange'` — for hash changes (URL hash params)
84+
- `'popstate'` — for back/forward navigation (URL search params, browser-only)
85+
- `'hashchange'` — for hash changes (URL hash params, browser-only)
8486
- Any custom event name
8587
- `undefined` — no automatic sync (used by `sessionStorageProvider`)

0 commit comments

Comments
 (0)