Allow Astro.locals to be set by adapters

.changeset/smooth-jokes-watch.md

@@ -0,0 +1,6 @@
+---
+'astro': minor
+'@astrojs/node': minor
+---
+
+Astro.locals are now exposed to the adapter API. Node Adapter can now pass in a `locals` object in the SSR handler middleware.

packages/astro/src/core/app/index.ts

@@ -115,7 +115,7 @@ export class App {
 			return undefined;
 		}
 	}
-	async render(request: Request, routeData?: RouteData): Promise<Response> {
+	async render(request: Request, routeData?: RouteData, locals?: object): Promise<Response> {
 		let defaultStatus = 200;
 		if (!routeData) {
 			routeData = this.match(request);
@@ -131,7 +131,7 @@ export class App {
 			}
 		}
 
-		Reflect.set(request, clientLocalsSymbol, {});
+		Reflect.set(request, clientLocalsSymbol, locals ?? {});
 
 		// Use the 404 status code for 404.astro components
 		if (routeData.route === '/404') {
@@ -227,15 +227,14 @@ export class App {
 					onRequest as MiddlewareResponseHandler,
 					apiContext,
 					() => {
-						return renderPage({ mod, renderContext, env: this.#env, apiContext });
+						return renderPage({ mod, renderContext, env: this.#env });
 					}
 				);
 			} else {
 				response = await renderPage({
 					mod,
 					renderContext,
 					env: this.#env,
-					apiContext,
 				});
 			}
 			Reflect.set(request, responseSentSymbol, true);

packages/astro/src/core/app/node.ts

@@ -40,11 +40,12 @@ export class NodeApp extends App {
 	match(req: NodeIncomingMessage | Request, opts: MatchOptions = {}) {
 		return super.match(req instanceof Request ? req : createRequestFromNodeRequest(req), opts);
 	}
-	render(req: NodeIncomingMessage | Request, routeData?: RouteData) {
+	render(req: NodeIncomingMessage | Request, routeData?: RouteData, locals?: object) {
 		if (typeof req.body === 'string' && req.body.length > 0) {
 			return super.render(
 				req instanceof Request ? req : createRequestFromNodeRequest(req, Buffer.from(req.body)),
-				routeData
+				routeData,
+				locals
 			);
 		}
 
@@ -53,7 +54,8 @@ export class NodeApp extends App {
 				req instanceof Request
 					? req
 					: createRequestFromNodeRequest(req, Buffer.from(JSON.stringify(req.body))),
-				routeData
+				routeData,
+				locals
 			);
 		}
 
@@ -74,13 +76,15 @@ export class NodeApp extends App {
 			return reqBodyComplete.then(() => {
 				return super.render(
 					req instanceof Request ? req : createRequestFromNodeRequest(req, body),
-					routeData
+					routeData,
+					locals
 				);
 			});
 		}
 		return super.render(
 			req instanceof Request ? req : createRequestFromNodeRequest(req),
-			routeData
+			routeData,
+			locals
 		);
 	}
 }

packages/astro/src/core/build/generate.ts

@@ -498,11 +498,11 @@ async function generatePath(
 					onRequest as MiddlewareResponseHandler,
 					apiContext,
 					() => {
-						return renderPage({ mod, renderContext, env, apiContext });
+						return renderPage({ mod, renderContext, env });
 					}
 				);
 			} else {
-				response = await renderPage({ mod, renderContext, env, apiContext });
+				response = await renderPage({ mod, renderContext, env });
 			}
 		} catch (err) {
 			if (!AstroError.is(err) && !(err as SSRError).id && typeof err === 'object') {

packages/astro/src/core/render/context.ts

@@ -6,9 +6,12 @@ import type {
 	SSRElement,
 	SSRResult,
 } from '../../@types/astro';
+import { AstroError, AstroErrorData } from '../errors/index.js';
 import { getParamsAndPropsOrThrow } from './core.js';
 import type { Environment } from './environment';
 
+const clientLocalsSymbol = Symbol.for('astro.locals');
+
 /**
  * The RenderContext represents the parts of rendering that are specific to one request.
  */
@@ -25,6 +28,7 @@ export interface RenderContext {
 	status?: number;
 	params: Params;
 	props: Props;
+	locals?: object;
 }
 
 export type CreateRenderContextArgs = Partial<RenderContext> & {
@@ -49,12 +53,29 @@ export async function createRenderContext(
 		logging: options.env.logging,
 		ssr: options.env.ssr,
 	});
-	return {
+
+	let context = {
 		...options,
 		origin,
 		pathname,
 		url,
 		params,
 		props,
 	};
+
+	// We define a custom property, so we can check the value passed to locals
+	Object.defineProperty(context, 'locals', {
+		get() {
+			return Reflect.get(request, clientLocalsSymbol);
+		},
+		set(val) {
+			if (typeof val !== 'object') {
+				throw new AstroError(AstroErrorData.LocalsNotAnObject);
+			} else {
+				Reflect.set(request, clientLocalsSymbol, val);
+			}
+		},
+	});
+
+	return context;
 }

packages/astro/src/core/render/core.ts

@@ -1,5 +1,5 @@
 import type { APIContext, ComponentInstance, Params, Props, RouteData } from '../../@types/astro';
-import { renderPage as runtimeRenderPage } from '../../runtime/server/index.js';
+import { render, renderPage as runtimeRenderPage } from '../../runtime/server/index.js';
 import { attachToResponse } from '../cookies/index.js';
 import { AstroError, AstroErrorData } from '../errors/index.js';
 import type { LogOptions } from '../logger/core.js';
@@ -107,25 +107,23 @@ export type RenderPage = {
 	mod: ComponentInstance;
 	renderContext: RenderContext;
 	env: Environment;
-	apiContext?: APIContext;
 };
 
-export async function renderPage({ mod, renderContext, env, apiContext }: RenderPage) {
+export async function renderPage({ mod, renderContext, env }: RenderPage) {
 	// Validate the page component before rendering the page
 	const Component = mod.default;
 	if (!Component)
 		throw new Error(`Expected an exported Astro component but received typeof ${typeof Component}`);
 
-	let locals = {};
-	if (apiContext) {
-		if (env.mode === 'development' && !isValueSerializable(apiContext.locals)) {
+	if (renderContext.locals) {
+		if (env.mode === 'development' && !isValueSerializable(renderContext.locals)) {
 			throw new AstroError({
 				...AstroErrorData.LocalsNotSerializable,
 				message: AstroErrorData.LocalsNotSerializable.message(renderContext.pathname),
 			});
 		}
-		locals = apiContext.locals;
 	}
+
 	const result = createResult({
 		adapterName: env.adapterName,
 		links: renderContext.links,
@@ -145,7 +143,7 @@ export async function renderPage({ mod, renderContext, env, apiContext }: Render
 		scripts: renderContext.scripts,
 		ssr: env.ssr,
 		status: renderContext.status ?? 200,
-		locals,
+		locals: renderContext.locals ?? {},
 	});
 
 	// Support `export const components` for `MDX` pages

packages/astro/src/core/render/dev/index.ts

@@ -191,7 +191,7 @@ export async function renderPage(options: SSROptions): Promise<Response> {
 
 			const onRequest = options.middleware.onRequest as MiddlewareResponseHandler;
 			const response = await callMiddleware<Response>(onRequest, apiContext, () => {
-				return coreRenderPage({ mod, renderContext, env: options.env, apiContext });
+				return coreRenderPage({ mod, renderContext, env: options.env });
 			});
 
 			return response;

packages/astro/src/core/request.ts

@@ -13,6 +13,7 @@ export interface CreateRequestOptions {
 	body?: RequestBody | undefined;
 	logging: LogOptions;
 	ssr: boolean;
+	locals?: object | undefined;
 }
 
 const clientAddressSymbol = Symbol.for('astro.clientAddress');
@@ -26,6 +27,7 @@ export function createRequest({
 	body = undefined,
 	logging,
 	ssr,
+	locals,
 }: CreateRequestOptions): Request {
 	let headersObj =
 		headers instanceof Headers
@@ -66,7 +68,7 @@ export function createRequest({
 		Reflect.set(request, clientAddressSymbol, clientAddress);
 	}
 
-	Reflect.set(request, clientLocalsSymbol, {});
+	Reflect.set(request, clientLocalsSymbol, locals ?? {});
 
 	return request;
 }

packages/astro/src/vite-plugin-astro-server/route.ts

@@ -19,6 +19,8 @@ import { matchAllRoutes } from '../core/routing/index.js';
 import { log404 } from './common.js';
 import { handle404Response, writeSSRResult, writeWebResponse } from './response.js';
 
+const clientLocalsSymbol = Symbol.for('astro.locals');
+
 type AsyncReturnType<T extends (...args: any) => Promise<any>> = T extends (
 	...args: any
 ) => Promise<infer R>
@@ -142,6 +144,7 @@ export async function handleRoute(
 		logging,
 		ssr: buildingToSSR,
 		clientAddress: buildingToSSR ? req.socket.remoteAddress : undefined,
+		locals: Reflect.get(req, clientLocalsSymbol), // Allows adapters to pass in locals in dev mode.
 	});
 
 	// Set user specified headers to response object.

packages/astro/test/fixtures/ssr-locals/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@test/ssr-locals",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "astro": "workspace:*"
+  }
+}

packages/astro/test/fixtures/ssr-locals/src/pages/api.js

@@ -0,0 +1,10 @@
+
+export async function get({ locals }) {
+	let out = { ...locals };
+
+	return new Response(JSON.stringify(out), {
+		headers: {
+			'Content-Type': 'application/json'
+		}
+	});
+}

packages/astro/test/fixtures/ssr-locals/src/pages/foo.astro

@@ -0,0 +1,4 @@
+---
+const { foo } = Astro.locals;
+---
+<h1 id="foo">{ foo }</h1>

packages/astro/test/ssr-locals.test.js

@@ -0,0 +1,40 @@
+import { expect } from 'chai';
+import * as cheerio from 'cheerio';
+import { loadFixture } from './test-utils.js';
+import testAdapter from './test-adapter.js';
+
+describe('SSR Astro.locals from server', () => {
+	/** @type {import('./test-utils').Fixture} */
+	let fixture;
+
+	before(async () => {
+		fixture = await loadFixture({
+			root: './fixtures/ssr-locals/',
+			output: 'server',
+			adapter: testAdapter(),
+		});
+		await fixture.build();
+	});
+
+	it('Can access Astro.locals in page', async () => {
+		const app = await fixture.loadTestAdapterApp();
+		const request = new Request('http://example.com/foo');
+		const locals = { foo: 'bar' };
+		const response = await app.render(request, undefined, locals);
+		const html = await response.text();
+
+		const $ = cheerio.load(html);
+		expect($('#foo').text()).to.equal('bar');
+	});
+
+	it('Can access Astro.locals in api context', async () => {
+		const app = await fixture.loadTestAdapterApp();
+		const request = new Request('http://example.com/api');
+		const locals = { foo: 'bar' };
+		const response = await app.render(request, undefined, locals);
+		expect(response.status).to.equal(200);
+		const body = await response.json();
+
+		expect(body.foo).to.equal('bar');
+	});
+});

packages/astro/test/test-adapter.js

@@ -34,17 +34,16 @@ export default function ({ provideAddress = true, extendAdapter } = { provideAdd
 													this.#manifest = manifest;
 												}
 
-												async render(request, routeData) {
+												async render(request, routeData, locals) {
 													const url = new URL(request.url);
 													if(this.#manifest.assets.has(url.pathname)) {
 														const filePath = new URL('../client/' + this.removeBase(url.pathname), import.meta.url);
 														const data = await fs.promises.readFile(filePath);
 														return new Response(data);
 													}
 
-													Reflect.set(request, Symbol.for('astro.locals'), {});
 													${provideAddress ? `request[Symbol.for('astro.clientAddress')] = '0.0.0.0';` : ''}
-													return super.render(request, routeData);
+													return super.render(request, routeData, locals);
 												}
 											}
 

packages/integrations/node/README.md

@@ -119,6 +119,25 @@ app.use(ssrHandler);
 app.listen({ port: 8080 });
 ```
 
+Additionally, you can also pass in an object to be accessed with `Astro.locals` or in Astro middleware:
+
+```js
+import express from 'express';
+import { handler as ssrHandler } from './dist/server/entry.mjs';
+
+const app = express();
+app.use(express.static('dist/client/'))
+app.use((req, res, next) => {
+  const locals = {
+    foo: 'bar'
+  };
+
+  ssrHandler(req, res, next, locals);
+);
+
+app.listen(8080);
+```
+
 Note that middleware mode does not do file serving. You'll need to configure your HTTP framework to do that for you. By default the client assets are written to `./dist/client/`.
 
 ### Standalone

packages/integrations/node/src/nodeMiddleware.ts

@@ -8,14 +8,15 @@ export default function (app: NodeApp, mode: Options['mode']) {
 	return async function (
 		req: IncomingMessage,
 		res: ServerResponse,
-		next?: (err?: unknown) => void
+		next?: (err?: unknown) => void,
+		locals?: object
 	) {
 		try {
 			const route =
 				mode === 'standalone' ? app.match(req, { matchNotFound: true }) : app.match(req);
 			if (route) {
 				try {
-					const response = await app.render(req);
+					const response = await app.render(req, route, locals);
 					await writeWebResponse(app, res, response);
 				} catch (err: unknown) {
 					if (next) {

packages/integrations/node/test/fixtures/locals/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@test/locals",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "astro": "workspace:*",
+    "@astrojs/node": "workspace:*"
+  }
+}

packages/integrations/node/test/fixtures/locals/src/pages/api.js

@@ -0,0 +1,10 @@
+
+export async function post({ locals }) {
+	let out = { ...locals };
+
+	return new Response(JSON.stringify(out), {
+		headers: {
+			'Content-Type': 'application/json'
+		}
+	});
+}