Ossido

Guides
Docs
Reference
Benchmarks
News

⌘K

Ecosystem

Macros

#[action]
#[api]
#[client_ws_event]
#[Environment]
#[handler]
#[middleware]
#[Props]
#[public]
#[server_ws_event]
#[static_paths]
#[Type]
#[ws]
get_env!

Functions

set_error_handler
sockets

Structs

ActionError
Connection
ErrorContext
Files
Logger
PrevState
Request
SocketGroup
SocketHandle
SocketManager
StaticParams
StaticPaths
UploadedFile

Enums

Response
SegmentValue

Traits

Key

Loading...

On this page

Rust
Macros
Functions
Structs
Enums
Traits
React
Components
Hooks
Functions
Classes
Constants
Types

Ossido

A Rust powered React framework for server-side rendering, built on Axum.

Product

Documentation
Guides
News

Resources

crates.io
Changelog
Getting started

Community

GitHub
Discord
Discussions

© 2026 Chris Schofield & Ossido. Released under the MIT License.

Built withRustReact

API Reference

Every important Ossido symbol on its own page - signature, description, and worked examples - across both ecosystems. Pick one below, or use the Rust/React switcher in the sidebar.

Rust

Macros

#[action]#[ossido::action] - a Next.js-style server action. Marks a function whose typed TypeScript counterpart the build generates (importable, passable to <form action={fn}>, and usable with useActionState). The first non-state, non-logger, non-PrevState argument is the input (decoded from the request body); a PrevState<T> argument opts into the useActionState (prevState, formData) contract.
#[api]Defines an HTTP API endpoint under src/routes/api, with the method as the macro argument (GET/POST/PUT/PATCH/DELETE). Returns JSON or any axum response.
#[client_ws_event]#[ossido::client_ws_event("name")] - a JSON event the **client sends** to the server. Applies #[ossido::Type] (serde + TypeScript) and marks the struct as a ClientWsEvent.
#[Environment]#[ossido::Environment] - mark the project's typed environment schema. See environment::environment_attr for the full contract (typed FromStr parsing, required vs Option fields, the #[public] helper, and the generated from_env / public-JSON methods). Read fields in Rust via ossido::get_env!; TypeScript types for the public fields are generated only when this struct exists.
#[handler]Turns an async function into a page/route data handler. The first argument is the Request; remaining arguments are injected application state or a Logger. Its return becomes the page's props.
#[middleware]Marks a function in a middleware.rs that returns a Tower Layer applied to its route segment. A function returns a single Layer; compose several with a ServiceBuilder.
#[Props]#[ossido::Props] - bundle serde::{Serialize, Deserialize} and register the struct for TypeScript generation (everything #[Type] does), plus a From<Self> for ossido::Response impl so it can be returned directly from a #[ossido::handler]. The struct must be 'static.
#[public]An inert helper attribute on an Environment field that exposes it to the frontend. Public fields are serialized into the SSR payload and the browser global that getEnv reads; every other field stays server-only.
#[server_ws_event]#[ossido::server_ws_event("name")] - a JSON event the **server sends** to the client. Applies #[ossido::Type] (serde + TypeScript) and marks the struct as a ServerWsEvent.
#[static_paths]Mark the function in a dynamic route's page.rs that enumerates the pages to statically generate for that route (Ossido's getStaticPaths). See ossido::StaticPaths.
#[Type]#[ossido::Type] - bundle serde::{Serialize, Deserialize} onto a struct or enum and generate its TypeScript type (exported from the "@ossido-labs/ossido/types" module). Replaces the old #[derive(Serialize, Deserialize, Type)].
#[ws]#[ossido::ws] - the project's single WebSocket handler. Must live in src/ws.rs; the build fails if it appears under src/routes/**. Generates the axum upgrade handler that hands the raw socket + SocketManager to the annotated function. See ossido::ws.
get_env!Reads a field from the typed Environment singleton, returning a parsed copy of its value. A second argument provides a fallback that collapses an Option<T> field to a concrete T. If the project defines no Environment struct the accessor is never generated, so the macro fails to compile at the call site.

Functions

set_error_handlerRegister the process-wide error handler. Call this once, early (typically from src/app.rs main()); a later call is ignored (the first registration wins). The handler runs on every error thrown by a request handler. Return Some(response) to send a custom HTTP response, or None to fall back to Ossido's default error page / JSON. See the module docs.
socketsThe process-global SocketManager handle.

Structs

ActionErrorA domain error returned from an action as Err(ActionError). Serialized into the { "error": ... } envelope (HTTP 422) and surfaced on the client as a thrown OssidoActionError. Distinct from a panic, which is caught and routed through the framework's ServerError overlay.
ConnectionThe read side of a stored socket, plus the means to reply to and re-key this connection. Returned by SocketManager::store. Dropping it unregisters the connection from the manager (its ConnId and every key index).
ErrorContextEverything a registered error handler is given about a failed request. Owned (not borrowed) so the handler may hold it across an .await.
FilesThe files uploaded by a multipart/form-data server action, keyed by form field name. Declare a Files parameter on an #[action] to receive them; it is empty for JSON / URL-encoded requests.
LoggerA request-scoped, handler-facing logger. Declare a logger parameter on a #[handler] / #[api] function and the framework provides it automatically - it does **not** need to be added to ApplicationState, and it works whether or not the app has custom state: ignore #[ossido::handler] async fn get_pokemon(req: Request, fetch: Client, logger: ossido::Logger) -> Response { logger.info("fetching a pokemon"); // ... } Its methods emit BE log lines (in the active pretty / json format) tagged with the request path, so a handler's logs are tied to the request.
PrevStateThe previous useActionState state, round-tripped from the client. None on the first render (or when the action is called imperatively without a prior state). A PrevState<T> parameter is how an action opts into React's (prevState, formData) => newState contract. The wrapped value is untrusted client input - never use it as authorization state.
RequestThe incoming HTTP request in a handler or action: URI, headers, route params, and typed body parsing - body::<T>() decodes a JSON body, form_data::<T>() decodes a url-encoded form. Both return Result<T, BodyParseError>.
SocketGroupThe connections currently stored under a key (0, 1, or many). Returned by SocketManager::get. Sending on the group fans out to every connection.
SocketHandleA cheap, cloneable sender for one live connection - the write side, safe to hold and use from anywhere. Obtained from SocketGroup / Connection.
SocketManagerA cheap, cloneable handle over the framework's keyed connection store. Reach it anywhere via sockets; it is also injectable as a #[ossido::ws] (or #[handler]/#[api]/#[action]) parameter. Store a socket with SocketManager::store under any Key (a u64 user id, a String room name, a custom enum, ...), then look connections back up with SocketManager::get and send on the returned SocketGroup.
StaticParamsThe parameters for a single generated page: a map from each dynamic slot name to its SegmentValue. Built through the closure passed to StaticPaths::register.
StaticPathsThe full set of pages to statically generate for a dynamic route. A #[ossido::static_paths] function receives this borrowed and registers one entry per page.
UploadedFileA file uploaded via a multipart/form-data server action.

Enums

ResponseA handler's return value: page Props, a redirect, or a custom axum response. Most handlers return a #[Props] struct and never build this directly.
SegmentValueThe value bound to one dynamic slot of a route: a single URL segment (param) or an ordered list of segments (...catchall). Serialised *untagged*, so a single value is a JSON string and a catch-all is a JSON array - matching how the build substitutes each into the route pattern (and how Next represents catch-all params).

Traits

KeyAnything usable as a connection key: cheap to store, compare, and hash, and safe to share across tasks. Blanket-implemented, so u64, String, a custom #[derive(Clone, PartialEq, Eq, Hash)] enum, etc. all qualify - no manual impl needed.

React

Components

FormA <form> wired to a server action with progressive enhancement. When hydrated, submission is intercepted and the action is called with FormData. With JS disabled, the rendered action={fn.url} makes it a native POST, and the server responds with a 303 Post/Redirect/Get.
LinkClient-side navigation link - preload-aware (loads the route on hover/viewport), with optional scroll, replace, and View Transition control. Keeps navigation within the SPA.
OssidoScriptsInjects the serialized server payload and the framework's client scripts. Render once in the root layout's <body>.

Hooks

useActionStateReact's hook for stateful actions, re-exported so there's one import site. Pass a stateful Ossido action (one with a PrevState argument) and its initial state.
useFormStatusReact DOM's hook for the pending state of the nearest parent <form>, re-exported for convenience inside action forms.
useRouterAccess the router instance for programmatic navigation and the current location.

Functions

connectOpen a connection to the project's WebSocket endpoint. Resolves the ws(s):// scheme from the current origin; forwards protocols (e.g. for subprotocol-based auth). Same-origin cookies are sent automatically on the handshake.
createApiClientCreate an ApiClient, optionally with a base URL and default options.
dynamicThis function lets you dynamically import a component. It uses React.lazy() with Suspense under the hood.
getEnvRead a public environment variable by key, returning a typed copy of its value. Throws if no public environment is available - i.e. the project defines no #[ossido::Environment] struct (the Rust equivalent, get_env!, is a compile error in that case) - or if the key is not a known public variable.

Classes

OssidoActionErrorThrown by an action call when the server returns an error (or panics).

Constants

apiClientThe default client - global fetch, relative paths.

Types

OssidoConfigThe ossido.config.ts shape: server options, Vite passthrough, logging, SSR render threads, output mode, build hooks, and view transitions.
OssidoErrorPropsProps passed to a user error.tsx component (and the default error UI).
OssidoLayoutPropsProps for a layout component - { children } for the wrapped subtree.
OssidoPageTypes a page component so its props are exactly the matching Rust handler's return type, keyed by the route path.