Request State
Astro provides Astro.locals
/context.locals
for shared state between different components being rendered in a page.
This state can only be accessed from an Astro component using the Astro
constant or from middlewares from the context. Sharing state between framework components is not provided and inconvenient. State using Astro.locals
is also not shared with the client after the request completes, resulting in problems with the server and the client rendering different contents.
This library provides a solution for those problems:
- You can share state between any component used in a request, even between frameworks.
- The final state formed in the server while rendering a request is available for all client code running in the rendered page.
- UI framework components can keep their state from server to client.
Installing the dependency
Prerequisites
When using the Cloudflare adapter, you’ll need to enable AsyncLocalStorage manually.
Demo
A demo showing values passing from prerendering to the client and from server to the client is available here:
- Deployed site: https://inox-tools-ex-request-state.pages.dev/
- Source code: https://github.com/Fryuni/inox-tools/tree/main/examples/request-state
How to use
Import the two functions anywhere in your code:
Alternatively, provide an initial value to be used if not present in the state:
The state can be any value supported by the devalue
library plus:
Date
sURL
s- Global symbols (
Symbol.for
) - Well-known symbols (
Symbol.XXX
)
setState
Params:
key
(string
): The key of a value in the statevalue
(unknown
): The value to be set
getState
Params:
key
(string
): The key of a value in the statevalueIfMissing
(unknown
): An optional value to set if there is no value in the state for the given key.
Returns the value of the state for the given key, if present. If now, sets the value to valueIfMissing
and returns it.
Using with View Transitions
If you are using Astro’s View Transitions, the client-side state will be cleared out and entirely replaced with the server state used to render the page the client is navigating to.
For example:
- You open page
/one
- Server state of page
/one
is loaded on the client - You modify the state one the client using
setState
- You navigate to
/two
- Server state of page
/two
is loaded on the client. All changes from step 3 are lost.
The state is loaded during the astro:after-swap
event, so:
State loaded event
On the client, after the server state is loaded but before it is made available to client modules an event @it-astro:server-state-loaded
is triggered on the document.
Caveats
Enabling Request State disables response streaming. The entire application state must be generated before shipping closing head tag to the client. This behavior prevents data race when client components start hydrating before entire document is loaded.
License
Astro Request State is available under the MIT license.