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

npm

npx astro add @inox-tools/request-state@beta

yarn

yarn astro add @inox-tools/request-state@beta

pnpm

pnpm astro add @inox-tools/request-state@beta

Invalid Codemod

Installing the beta version of the this package using astro add generates an invalid code for your Astro Config. After installing, remove the @beta added in the import and integrations section.

astro.config.mjs

import inoxToolsRequestState@beta from '@inox-tools/request-state';
import inoxToolsRequestState from '@inox-tools/request-state';

export default defineConfig({
	integrations: [inoxToolsRequestState@beta()],
	integrations: [inoxToolsRequestState()],
});

Follow this issue for more information and updates.

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:

import { getState, setState } from '@it-astro:state';

setState('some key', 'some value');

const state = getState('some key');

Alternatively, provide an initial value to be used if not present in the state:

import { getState } from '@it-astro:state';

// `'initial value'` will be used if `'some key'` is not in the state
const state = getState('some key', 'initial value');

The state can be any value supported by the devalue library plus:

• Dates
• URLs
• Global symbols (Symbol.for)
• Well-known symbols (Symbol.XXX)

setState

Params:

• key (string): The key of a value in the state
• value (unknown): The value to be set

getState

Params:

• key (string): The key of a value in the state
• valueIfMissing (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:

1. You open page /one
2. Server state of page /one is loaded on the client
3. You modify the state one the client using setState
4. You navigate to /two
5. 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:

document.addEventListener('astro:before-preparation', () => {
  // State of the previous page is present
});
document.addEventListener('astro:after-preparation', () => {
  // State of the previous page is present
});
document.addEventListener('astro:before-swap', () => {
  // State of the previous page is present
});
document.addEventListener('astro:after-swap', () => {
  // State of the next page is set
  // If this listener was registered before the state loader,
  // the state of the previous page would still be present.
  // Otherwise, the state of the new page would be present.
});
document.addEventListener('astro:page-load', () => {
  // State of the next page is present
});

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.

document.addEventListener('@it-astro:server-state-loaded', (event) => {
  // A shallow copy of the current client state.
  // Modifying it won't affect the state already available to client modules.
  event.previousState.get('foo');

  // The state loaded from the server.
  // You can modify this state before it is made available to client modules.
  event.serverState.set('foo', 'bar');

  // The client state won't change at all if the default is prevented.
  event.preventDefault();
});

License

Astro Request State is available under the MIT license.