Pass locals to render context and to React’s app entrypoint component

meyer · meyer · commit 216c18545303 · 2026-02-01T20:27:32.000-05:00
diff --git a/.changeset/good-tires-say.md b/.changeset/good-tires-say.md
@@ -0,0 +1,5 @@
+---
+'astro': minor
+---
+
+Exposes `locals` to the render context so integrations can access them
diff --git a/.changeset/twenty-glasses-cross.md b/.changeset/twenty-glasses-cross.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/react': minor
+---
+
+Passes `Astro.locals` through to `appEntrypoint` as `locals`
diff --git a/packages/astro/src/core/render-context.ts b/packages/astro/src/core/render-context.ts
@@ -566,6 +566,7 @@ export class RenderContext {
 			componentMetadata,
 			compressHTML,
 			cookies,
+			locals: this.locals,
 			/** This function returns the `Astro` faux-global */
 			createAstro: (props, slots) => this.createAstro(result, props, slots, ctx),
 			links,
diff --git a/packages/astro/src/types/public/internal.ts b/packages/astro/src/types/public/internal.ts
@@ -224,6 +224,7 @@ export interface SSRResult {
 	 */
 	pathname: string;
 	cookies: AstroCookies | undefined;
+	locals: App.Locals;
 	serverIslandNameMap: Map<string, string>;
 	trailingSlash: AstroConfig['trailingSlash'];
 	key: Promise<CryptoKey>;
diff --git a/packages/integrations/react/src/index.ts b/packages/integrations/react/src/index.ts
@@ -38,6 +38,10 @@ export interface AppEntrypointProps {
 	 * The React island being wrapped.
 	 */
 	children?: ReactNode;
+	/**
+	 * `Astro.locals`, available only in a server environment.
+	 */
+	locals?: App.Locals;
 }
 
 /**
diff --git a/packages/integrations/react/src/server-v17.ts b/packages/integrations/react/src/server-v17.ts
@@ -3,11 +3,12 @@ import type { AstroComponentMetadata, NamedSSRLoadedRendererValue } from 'astro'
 import React from 'react';
 import ReactDOM from 'react-dom/server';
 import StaticHtml from './static-html.js';
+import type { RendererContext } from './types.js';
 
 const slotName = (str: string) => str.trim().replace(/[-_]([a-z])/g, (_, w) => w.toUpperCase());
 const reactTypeof = Symbol.for('react.element');
 
-function check(Component: any, props: Record<string, any>, children: any) {
+function check(this: RendererContext, Component: any, props: Record<string, any>, children: any) {
 	// Note: there are packages that do some unholy things to create "components".
 	// Checking the $$typeof property catches most of these patterns.
 	if (typeof Component === 'object') {
@@ -32,12 +33,13 @@ function check(Component: any, props: Record<string, any>, children: any) {
 		return React.createElement('div');
 	}
 
-	renderToStaticMarkup(Tester, props, children, {} as any);
+	renderToStaticMarkup.call(this, Tester, props, children, {} as any);
 
 	return isReactComponent;
 }
 
 async function renderToStaticMarkup(
+	this: RendererContext,
 	Component: any,
 	props: Record<string, any>,
 	{ default: children, ...slotted }: Record<string, any>,
@@ -64,7 +66,7 @@ async function renderToStaticMarkup(
 	}
 	const componentElement = React.createElement(Component, newProps);
 	const vnode = AppEntrypoint
-		? React.createElement(AppEntrypoint, null, componentElement)
+		? React.createElement(AppEntrypoint, { locals: this?.result?.locals }, componentElement)
 		: componentElement;
 	let html: string;
 	if (metadata?.hydrate) {
diff --git a/packages/integrations/react/src/server.ts b/packages/integrations/react/src/server.ts
@@ -111,7 +111,7 @@ async function renderToStaticMarkup(
 	}
 	const componentElement = React.createElement(Component, newProps);
 	const vnode = AppEntrypoint
-		? React.createElement(AppEntrypoint, null, componentElement)
+		? React.createElement(AppEntrypoint, { locals: this?.result?.locals }, componentElement)
 		: componentElement;
 	const renderOptions = {
 		identifierPrefix: prefix,
diff --git a/packages/integrations/react/test/fixtures/react-app-entrypoint/src/layouts/Layout.astro b/packages/integrations/react/test/fixtures/react-app-entrypoint/src/layouts/Layout.astro
@@ -0,0 +1,12 @@
+---
+// Set data on Astro.locals - this will be passed to the wrapper component
+Astro.locals.serverData = 'from-locals';
+---
+<html>
+	<head>
+		<title>React App Entrypoint Test</title>
+	</head>
+	<body>
+		<slot />
+	</body>
+</html>
diff --git a/packages/integrations/react/test/fixtures/react-app-entrypoint/src/pages/with-locals.astro b/packages/integrations/react/test/fixtures/react-app-entrypoint/src/pages/with-locals.astro
@@ -0,0 +1,8 @@
+---
+import Layout from '../layouts/Layout.astro';
+import Counter from '../components/Counter';
+---
+<Layout>
+	<h1>React App Entrypoint with Locals</h1>
+	<Counter client:load />
+</Layout>
diff --git a/packages/integrations/react/test/react-app-entrypoint.test.js b/packages/integrations/react/test/react-app-entrypoint.test.js
@@ -32,6 +32,15 @@ describe('React App Entrypoint', () => {
 			// The counter should have access to the theme from context
 			assert.equal(counter.attr('data-theme'), 'dark');
 		});
+
+		it('Passes Astro.locals props to the wrapper', async () => {
+			const html = await fixture.readFile('/with-locals/index.html');
+			const $ = cheerioLoad(html);
+
+			// The wrapper should receive serverData from Astro.locals
+			const wrapper = $('[data-testid="wrapper"]');
+			assert.equal(wrapper.attr('data-server'), 'from-locals');
+		});
 	});
 
 	if (isWindows) return;
@@ -62,5 +71,14 @@ describe('React App Entrypoint', () => {
 			// The counter should have access to the theme from context
 			assert.equal(counter.attr('data-theme'), 'dark');
 		});
+
+		it('Passes Astro.locals props to the wrapper in dev mode', async () => {
+			const html = await fixture.fetch('/with-locals').then((res) => res.text());
+			const $ = cheerioLoad(html);
+
+			// The wrapper should receive serverData from Astro.locals
+			const wrapper = $('[data-testid="wrapper"]');
+			assert.equal(wrapper.attr('data-server'), 'from-locals');
+		});
 	});
 });

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'astro': minor
 +---
++
 +Exposes `locals` to the render context so integrations can access them
Original file line number	Diff line number	Diff line change
`@@ -111,7 +111,7 @@ async function renderToStaticMarkup(`
`111`	`111`	`}`
`112`	`112`	`const componentElement = React.createElement(Component, newProps);`
`113`	`113`	`const vnode = AppEntrypoint`
`114`		`- ? React.createElement(AppEntrypoint, null, componentElement)`
	`114`	`+ ? React.createElement(AppEntrypoint, { locals: this?.result?.locals }, componentElement)`
`115`	`115`	`: componentElement;`
`116`	`116`	`const renderOptions = {`
`117`	`117`	`identifierPrefix: prefix,`