Actions: support React 19 useActionState() with progressive enhancement

packages/astro/e2e/actions-react-19.test.js

@@ -9,6 +9,11 @@ test.beforeAll(async ({ astro }) => {
 	devServer = await astro.startDevServer();
 });
 
+test.afterEach(async ({ astro }) => {
+	// Force database reset between tests
+	await astro.editFile('./db/seed.ts', (original) => original);
+});
+
 test.afterAll(async () => {
 	await devServer.stop();
 });
@@ -21,6 +26,7 @@ test.describe('Astro Actions - React 19', () => {
 		await expect(likeButton).toBeVisible();
 		await likeButton.click();
 		await expect(likeButton, 'like button should be disabled when pending').toBeDisabled();
+		await expect(likeButton).not.toBeDisabled();
 	});
 
 	test('Like action - server progressive enhancement', async ({ page, astro }) => {
@@ -30,7 +36,26 @@ test.describe('Astro Actions - React 19', () => {
 		await expect(likeButton, 'like button starts with 10 likes').toContainText('10');
 		await likeButton.click();
 
-		// May contain "12" after the client button test.
-		await expect(likeButton, 'like button increments').toContainText(/11|12/);
+		await expect(likeButton, 'like button increments').toContainText('11');
+	});
+
+	test('Like action - client useActionState', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/blog/first-post/'));
+
+		const likeButton = page.getByLabel('likes-action-client');
+		await expect(likeButton).toBeVisible();
+		await likeButton.click();
+
+		await expect(likeButton, 'like button increments').toContainText('11');
+	});
+
+	test('Like action - server useActionState progressive enhancement', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/blog/first-post/'));
+
+		const likeButton = page.getByLabel('likes-action-server');
+		await expect(likeButton, 'like button starts with 10 likes').toContainText('10');
+		await likeButton.click();
+
+		await expect(likeButton, 'like button increments').toContainText('11');
 	});
 });

packages/astro/e2e/fixtures/actions-blog/src/actions/index.ts

@@ -7,7 +7,7 @@ export const server = {
 		like: defineAction({
 			input: z.object({ postId: z.string() }),
 			handler: async ({ postId }) => {
-				await new Promise((r) => setTimeout(r, 200));
+				await new Promise((r) => setTimeout(r, 1000));
 
 				const { likes } = await db
 					.update(Likes)

packages/astro/e2e/fixtures/actions-react-19/src/actions/index.ts

@@ -1,5 +1,6 @@
 import { db, Likes, eq, sql } from 'astro:db';
-import { defineAction, z } from 'astro:actions';
+import { defineAction, getApiContext, z } from 'astro:actions';
+import { experimental_getActionState } from '@astrojs/react/actions';
 
 export const server = {
 	blog: {
@@ -21,5 +22,26 @@ export const server = {
 				return likes;
 			},
 		}),
+		likeWithActionState: defineAction({
+			accept: 'form',
+			input: z.object({ postId: z.string() }),
+			handler: async ({ postId }) => {
+				await new Promise((r) => setTimeout(r, 200));
+
+				const context = getApiContext();
+				const state = await experimental_getActionState<number>(context);
+
+				const { likes } = await db
+					.update(Likes)
+					.set({
+						likes: state + 1,
+					})
+					.where(eq(Likes.postId, postId))
+					.returning()
+					.get();
+
+				return likes;
+			},
+		}),
 	},
 };

packages/astro/e2e/fixtures/actions-react-19/src/components/Like.tsx

@@ -1,5 +1,7 @@
 import { actions } from 'astro:actions';
+import { useActionState } from 'react';
 import { useFormStatus } from 'react-dom';
+import { experimental_withState } from '@astrojs/react/actions';
 
 export function Like({ postId, label, likes }: { postId: string; label: string; likes: number }) {
 	return (
@@ -10,6 +12,21 @@ export function Like({ postId, label, likes }: { postId: string; label: string;
 	);
 }
 
+
+export function LikeWithActionState({ postId, label, likes: initial }: { postId: string; label: string; likes: number }) {
+	const [likes, action] = useActionState(
+		experimental_withState(actions.blog.likeWithActionState),
+		10,
+	);
+
+	return (
+		<form action={action}>
+			<input type="hidden" name="postId" value={postId} />
+			<Button likes={likes} label={label} />
+		</form>
+	);
+}
+
 function Button({likes, label}: {likes: number; label: string}) {
 	const { pending } = useFormStatus();
 

packages/astro/e2e/fixtures/actions-react-19/src/pages/blog/[...slug].astro

@@ -2,7 +2,7 @@
 import { type CollectionEntry, getCollection, getEntry } from 'astro:content';
 import BlogPost from '../../layouts/BlogPost.astro';
 import { db, eq, Likes } from 'astro:db';
-import { Like } from '../../components/Like';
+import { Like, LikeWithActionState } from '../../components/Like';
 
 export const prerender = false;
 
@@ -23,13 +23,18 @@ const likesRes = await db.select().from(Likes).where(eq(Likes.postId, post.id)).
 ---
 
 <BlogPost {...post.data}>
+	<h2>Like</h2>
 	{
 		likesRes && (
 			<Like postId={post.id} likes={likesRes.likes} label="likes-client" client:load />
 			<Like postId={post.id} likes={likesRes.likes} label="likes-server" />
 		)
 	}
 
+	<h2>Like with action state</h2>
+	<LikeWithActionState postId={post.id} likes={10} label="likes-action-client" client:load />
+	<LikeWithActionState postId={post.id} likes={10} label="likes-action-server" />
+
 	<Content />
 
 </BlogPost>

packages/astro/src/@types/astro.ts

@@ -158,6 +158,25 @@ export interface AstroComponentMetadata {
 	componentUrl?: string;
 	componentExport?: { value: string; namespace?: boolean };
 	astroStaticSlot: true;
+	/**
+	 * Store the action result for use with React server actions.
+	 * This enables progressive enhancement when using React's `useActionState()`.
+	 */
+	reactServerActionResult?: {
+		/** The value returned by the action. */
+		value: any;
+		/**
+		 * The action name returned by an action's `toString()` property.
+		 * This matches the endpoint path.
+		 * @example "/_actions/blog.like"
+		 */
+		name: string;
+		/**
+		 * The key generated by React to identify each `useActionState()` call.
+		 * @example "k511f74df5a35d32e7cf266450d85cb6c"
+		 */
+		key: string;
+	};
 }
 
 /** The flags supported by the Astro CLI */
@@ -2674,7 +2693,7 @@ interface AstroSharedContext<
 		TInputSchema extends InputSchema<TAccept>,
 		TAction extends ActionClient<unknown, TAccept, TInputSchema>,
 	>(
-		action: TAction
+		action?: TAction
 	) => Awaited<ReturnType<TAction['safe']>> | undefined;
 	/**
 	 * Route parameters for this request if this is a dynamic route.
@@ -3187,6 +3206,7 @@ export interface SSRMetadata {
 	headInTree: boolean;
 	extraHead: string[];
 	propagators: Set<AstroComponentInstance>;
+	reactServerActionResult?: AstroComponentMetadata['reactServerActionResult'];
 }
 
 /* Preview server stuff */

packages/astro/src/actions/runtime/middleware.ts

@@ -40,6 +40,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
 	const actionsInternal: Locals['_actionsInternal'] = {
 		getActionResult: (actionFn) => {
+			if (!actionFn) return result;
 			if (actionFn.toString() !== actionPath) return Promise.resolve(undefined);
 			// The `action` uses type `unknown` since we can't infer the user's action type.
 			// Cast to `any` to satisfy `getActionResult()` type.

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

@@ -4,13 +4,13 @@ import type {
 	AstroGlobalPartial,
 	ComponentInstance,
 	MiddlewareHandler,
-	MiddlewareNext,
 	RewritePayload,
 	RouteData,
 	SSRResult,
 } from '../@types/astro.js';
 import type { ActionAPIContext } from '../actions/runtime/store.js';
 import { createGetActionResult } from '../actions/utils.js';
+import { hasContentType, formContentTypes } from '../actions/runtime/utils.js';
 import {
 	computeCurrentLocale,
 	computePreferredLocale,
@@ -276,6 +276,7 @@ export class RenderContext {
 
 	async createResult(mod: ComponentInstance) {
 		const { cookies, pathname, pipeline, routeData, status } = this;
+		const reactServerActionResult = await getReactServerActionResult(this);
 		const { clientDirectives, inlinedScripts, compressHTML, manifest, renderers, resolve } =
 			pipeline;
 		const { links, scripts, styles } = await pipeline.headElements(routeData);
@@ -317,6 +318,7 @@ export class RenderContext {
 			scripts,
 			styles,
 			_metadata: {
+				reactServerActionResult,
 				hasHydrationScript: false,
 				rendererSpecificHydrationScripts: new Set(),
 				hasRenderedHead: false,
@@ -521,3 +523,38 @@ export class RenderContext {
 		return (this.#preferredLocaleList ??= computePreferredLocaleList(request, i18n.locales));
 	}
 }
+
+async function getReactServerActionResult({
+	request,
+	locals,
+}: { request: Request; locals: APIContext['locals'] }): Promise<
+	SSRResult['_metadata']['reactServerActionResult']
+> {
+	if (!hasContentType(request.headers.get('Content-Type') ?? '', formContentTypes)) {
+		return;
+	}
+
+	const formData = await request.clone().formData();
+	const actionKey = formData.get('$ACTION_KEY')?.toString();
+	const actionName = formData.get('_astroAction')?.toString();
+	const actionResult = createGetActionResult(locals)();
+	if (!actionKey || !actionName || !actionResult) return;
+
+	const isUsingSafe = formData.has('_astroActionSafe');
+	if (!isUsingSafe && actionResult.error) {
+		throw new AstroError({
+			name: actionResult.error.name,
+			message: `Unhandled error calling action ${actionName.replace(/^\/_actions\//, '')}:\n${
+				actionResult.error.message
+			}`,
+			stack: actionResult.error.stack,
+			hint: 'use `.safe()` to handle from your React component.',
+		});
+	}
+
+	return {
+		value: isUsingSafe ? actionResult : actionResult.data,
+		key: actionKey,
+		name: actionName,
+	};
+}

packages/astro/src/runtime/server/astro-island.ts

@@ -2,6 +2,8 @@
 // Do not import this file directly, instead import the prebuilt one instead.
 // pnpm --filter astro run prebuild
 
+import type { AstroComponentMetadata } from '../../@types/astro.js';
+
 type directiveAstroKeys = 'load' | 'idle' | 'visible' | 'media' | 'only';
 
 declare const Astro: {
@@ -189,8 +191,10 @@ declare const Astro: {
 			let hydrationTimeStart;
 			const hydrator = this.hydrator(this);
 			if (process.env.NODE_ENV === 'development') hydrationTimeStart = performance.now();
+
 			await hydrator(this.Component, props, slots, {
 				client: this.getAttribute('client'),
+				reactServerActionResult: parseReactServerActionResult(this),
 			});
 			if (process.env.NODE_ENV === 'development' && hydrationTimeStart)
 				this.setAttribute(
@@ -215,3 +219,15 @@ declare const Astro: {
 		customElements.define('astro-island', AstroIsland);
 	}
 }
+
+function parseReactServerActionResult(
+	element: HTMLElement
+): AstroComponentMetadata['reactServerActionResult'] {
+	const result = element.getAttribute('action-result');
+	const key = element.getAttribute('action-key');
+	const name = element.getAttribute('action-name');
+	if (!result || !key || !name) return undefined;
+
+	const value = JSON.parse(result);
+	return { key, name, value };
+}

packages/astro/src/runtime/server/hydration.ts

@@ -164,6 +164,15 @@ export async function generateHydrateScript(
 
 	island.props['ssr'] = '';
 	island.props['client'] = hydrate;
+
+	if (renderer.name === '@astrojs/react' && metadata.reactServerActionResult) {
+		const { key, name, value } = metadata.reactServerActionResult;
+
+		island.props['action-result'] = JSON.stringify(value);
+		island.props['action-key'] = key;
+		island.props['action-name'] = name;
+	}
+
 	let beforeHydrationUrl = await result.resolve('astro:scripts/before-hydration.js');
 	if (beforeHydrationUrl.length) {
 		island.props['before-hydration-url'] = beforeHydrationUrl;

packages/astro/src/runtime/server/render/component.ts

@@ -90,6 +90,7 @@ async function renderFrameworkComponent(
 	const { renderers, clientDirectives } = result;
 	const metadata: AstroComponentMetadata = {
 		astroStaticSlot: true,
+		reactServerActionResult: result._metadata.reactServerActionResult,
 		displayName,
 	};
 

packages/astro/templates/actions.mjs

@@ -12,6 +12,8 @@ function toActionProxy(actionCallback = {}, aggregatedPath = '/_actions/') {
 			action.safe = (input) => {
 				return callSafely(() => action(input));
 			};
+			action.safe.toString = () => path;
+
 			// Add progressive enhancement info for React.
 			action.$$FORM_ACTION = function () {
 				const data = new FormData();
@@ -22,6 +24,16 @@ function toActionProxy(actionCallback = {}, aggregatedPath = '/_actions/') {
 					data,
 				}
 			};
+			action.safe.$$FORM_ACTION = function () {
+				const data = new FormData();
+				data.set('_astroAction', action.toString());
+				data.set('_astroActionSafe', 'true');
+				return {
+					method: 'POST',
+					name: action.toString(),
+					data,
+				}
+			}
 			// recurse to construct queries for nested object paths
 			// ex. actions.user.admins.auth()
 			return toActionProxy(action, path + '.');

packages/integrations/react/client.js

@@ -65,10 +65,13 @@ const getOrCreateRoot = (element, creator) => {
 };
 
 export default (element) =>
-	(Component, props, { default: children, ...slotted }, { client }) => {
+	(Component, props, { default: children, ...slotted }, { client, reactServerActionResult }) => {
 		if (!element.hasAttribute('ssr')) return;
 		const renderOptions = {
 			identifierPrefix: element.getAttribute('prefix'),
+			formState: reactServerActionResult
+				? [reactServerActionResult.value, reactServerActionResult.key, reactServerActionResult.name]
+				: undefined,
 		};
 		for (const [key, value] of Object.entries(slotted)) {
 			props[key] = createElement(StaticHtml, { value, name: key });

packages/integrations/react/package.json

@@ -21,6 +21,7 @@
   "homepage": "https://docs.astro.build/en/guides/integrations-guide/react/",
   "exports": {
     ".": "./dist/index.js",
+    "./actions": "./dist/actions.js",
     "./client.js": "./client.js",
     "./client-v17.js": "./client-v17.js",
     "./server.js": "./server.js",

packages/integrations/react/server.js

@@ -104,6 +104,13 @@ async function renderToStaticMarkup(Component, props, { default: children, ...sl
 	const vnode = React.createElement(Component, newProps);
 	const renderOptions = {
 		identifierPrefix: prefix,
+		formState: metadata.reactServerActionResult
+			? [
+					metadata.reactServerActionResult.value,
+					metadata.reactServerActionResult.key,
+					metadata.reactServerActionResult.name,
+				]
+			: undefined,
 	};
 	let html;
 	if ('renderToReadableStream' in ReactDOM) {