Forms & Prerendering
Relevant source files
The following files were used as context for generating this wiki page:
Svelte Effect Runtime (SER) provides a robust infrastructure for handling effectful forms and prerendering within SvelteKit applications. It leverages the effect Vite plugin to transform standard Svelte syntax into async-rendering declarations that support Effect-based operations like Form and Prerender. These features allow developers to write declarative, type-safe remote interactions that integrate directly with SvelteKit's endpoint architecture.
Sources: skills/svelte-effect-runtime/SKILL.md:1-10, modules/svelte-effect-runtime/src/compiler.ts:40-55
Remote Form Architecture
Remote forms in SER are built upon SvelteKit's native form actions but are wrapped in Effect-aware adapters. This architecture enables client-side preflight validation and standardized error handling for remote HTTP requests. The system uses a transport layer to submit programmatic input as FormData to specialized SvelteKit endpoints.
Form Submission Flow
The submission process involves extracting an action ID from the native form, performing an optional preflight validation via a schema, and executing a POST request to the remote base URL.
The diagram shows the sequence of a remote form submission, including client-side validation and envelope decoding.
Sources: modules/svelte-effect-runtime/src/remote/client/form-transport.ts:79-114
Transport Logic and Action IDs
Action IDs are extracted from the action attribute of native form objects. These IDs are used to construct the target URL for remote requests. The transport layer also ensures that SvelteKit-specific headers, such as x-sveltekit-pathname, are included in the request to maintain routing context.
Sources: modules/svelte-effect-runtime/src/remote/client/form-transport.ts:121-137, modules/svelte-effect-runtime/src/remote/client/form-transport.ts:153-162
Data Models and Schemas
SER uses standardized envelopes to communicate between the client and server. These envelopes distinguish between successful results and various error states, including validation issues and HTTP errors.
Response Envelopes
Responses are categorized into two primary tags: RemoteFormErrorEnvelope and RemoteFormResultEnvelope.
| Field | Type | Description |
|---|---|---|
_tag | string | Discriminator: "RemoteFormErrorEnvelope" or "RemoteFormResultEnvelope". |
error | unknown | Present in error envelopes; contains the failure details. |
status | number | HTTP status code for errors. |
data / result | string | Encoded payload containing the successful operation result. |
Sources: modules/svelte-effect-runtime/src/remote/client/form-transport.ts:20-33, modules/svelte-effect-runtime/src/remote/client/form-transport.ts:51-64
Form Issues and Validation
Validation errors are returned as a collection of FormIssue objects. Each issue contains a human-readable message and a path segment (string or number) indicating where the validation failed in the input data structure.
Sources: modules/svelte-effect-runtime/src/remote/client/form-transport.ts:38-42, modules/svelte-effect-runtime/src/remote/client/form-transport.ts:182-192
Prerendering and Configuration
Prerendering in SER is enabled through SvelteKit's experimental features and the SER compiler's Vite plugin. This configuration allows Svelte components to execute effectful logic (via yield*) during the build or initial request phase.
Required Setup
To use Form and Prerender features, the Svelte compiler must be configured for async rendering, and SvelteKit must have remoteFunctions enabled.
/** svelte.config.js */
const config = {
compilerOptions: {
experimental: {
async: true,
},
},
kit: {
experimental: {
remoteFunctions: true,
},
},
};
Sources: skills/svelte-effect-runtime/references/setup.md:12-34
Compiler Integration
The effect() Vite plugin must be placed before sveltekit() in the plugin array. This ensures that the SER transformation pass happens before Svelte parses the source code, allowing it to correctly handle effectful syntax in markup and scripts.
Sources: modules/svelte-effect-runtime/src/compiler.ts:40-55, skills/svelte-effect-runtime/references/setup.md:39-50
Component Syntax for Forms
In SER, forms and remote interactions are typically initiated within <script effect> blocks or directly in markup using the yield* operator. This syntax is strictly enforced; for example, effectful event handlers must use a yield-first syntax rather than being wrapped in anonymous callbacks.
| Syntax Type | Correct Usage | Incorrect Usage |
|---|---|---|
| Event Handler | onclick={yield* save(id)} | onclick={() => yield* save(id)} |
| Declaration | {const data = yield* load()} | <Widget value={yield* load()} /> |
Sources: skills/svelte-effect-runtime/references/syntax.md:46-68, skills/svelte-effect-runtime/SKILL.md:23-35
The SER framework ensures that forms and prerendering logic remain declarative while providing the full power of the Effect ecosystem for managing lifecycles, cancellation, and errors within a SvelteKit environment.
Sources: modules/svelte-effect-runtime/src/compiler.ts:133-145, skills/svelte-effect-runtime/references/syntax.md:1-10