Server Actions in Litro 0.11: Typed RPC, Forms Without JavaScript, and Streaming

@beatzball/litro 0.11.0 introduces Server Actions: a typed function-call boundary between the browser and your server. Export an async function from a *.server.ts module and call it from anywhere — no API route files, no fetch wrappers, no duplicated types. The release includes the full feature set in one go: the RPC core, progressive-enhancement forms with a no-JS path, and streaming returns.

New projects scaffolded with npm create @beatzball/litro (@beatzball/create-litro 0.7.0+) come with everything pre-wired.

One import, two execution paths

// posts/posts.server.ts — runs only on the server
export async function getPost(id: string) {
  return db.posts.findById(id); // db driver never enters the client bundle
}

// pages/posts/[id].ts — the SAME import works in both worlds
import { getPost } from '../../posts/posts.server.js';

// SSR: an in-process function call, no network hop
export const pageData = definePageData(async (event) => {
  return { post: await getPost(event.context.params?.id ?? '') };
});

// Browser: the same call becomes a typed POST /__litro/action/<id>
const fresh = await getPost(this.postId);

At build time, Litro's Vite plugin replaces every .server.ts module in the client graph with a generated stub, so server code and its transitive dependencies are structurally absent from the browser bundle. TypeScript resolves the import to the real file either way — the call is fully typed with no schema duplication. Rich values round-trip: Date, Map, Set, BigInt, and circular references all survive serialization.

Validation is built in. Wrap a handler with defineAction and any Standard Schema validator (Zod, Valibot, ArkType, or hand-rolled) becomes the parse boundary for hostile input:

import { defineAction } from '@beatzball/litro/actions';

export const createPost = defineAction({
  input: postSchema,
  async handler(input, ctx) {
    return db.posts.create(input);
  },
});

Forms that work with JavaScript disabled

Point a plain HTML form at an action with actionUrl(). The markup is identical in all three adapters — it is ordinary attribute interpolation:

import { actionUrl } from '@beatzball/litro/actions/client';
import { createPost } from '../posts/posts.server.js';

html`
  <form method="post" action=${actionUrl(createPost)}>
    <input name="title" required />
    <textarea name="body"></textarea>
    <button>Publish</button>
  </form>`;

Without JavaScript, the browser posts the form natively and the server answers with a classic Post/Redirect/Get flow: success redirects with a 303, validation failures bounce back with a one-shot cookie your page reads via getFormErrors(event) and renders above the form. With JavaScript, one call to enhanceForms() upgrades the same form to a typed RPC and reports the outcome through litro:action-success / litro:action-error events — the page decides what to do with them.

Form posts are guarded by Origin and Sec-Fetch-Site checks by default, and actions that want defense in depth can opt into a double-submit cookie token with defineAction({ csrf: 'token' }). Form targets must declare an input schema — form fields are untrusted strings, and the schema is where they become data.

Streaming returns

Any handler that returns an async iterable streams its chunks as they are produced:

export const tail = defineAction({
  input: jobSchema,
  async *handler({ jobId }) {
    for await (const line of logStream(jobId)) yield line;
  },
});

// client — chunks arrive incrementally, rich values revived per chunk
for await (const line of await tail({ jobId })) {
  render(line);
}

The transport is newline-delimited JSON of seroval nodes with a shared reference space, so object identity is preserved across chunks and a Date yielded mid-stream arrives as a Date. Mid-stream errors surface on the client as a thrown LitroActionError, and abandoning the loop cancels the underlying response instead of downloading it forever.

Security posture

Every export of a .server.ts module is a public HTTP endpoint — the docs lead with that, and the defaults are built around it: CSRF gates on by default, no stack traces in production error payloads, schema validation as the documented path for anything touching data, and a build-time error for non-function exports that would otherwise leak.

Getting it

Upgrade to @beatzball/litro 0.11.0. The feature is opt-in — nothing changes in an existing app until you wire it, and there are no breaking changes. Adding actions to an existing project is six one-time config edits; the Server Actions guide walks through each one, including the upgrade checklist for apps coming from 0.10.x or earlier. Or scaffold a fresh app and let the template do the wiring:

npm create @beatzball/litro my-app

The full guide — including the worked form error-handling example and the streaming protocol details — lives at /docs/server-actions.

Posts tagged: #rpc