Server Actions & Queries
Relevant source files
The following files were used as context for generating this wiki page:
Server Actions and Queries are full-stack primitives in Farm.js that enable secure data mutations and optimized data fetching. These features integrate directly with React Server Components (RSC) and the framework's file-based routing system to provide a typed developer experience.
Server Actions allow you to write mutations next to your components using the "use server" directive, supporting form actions and encrypted bound arguments. Server Queries handle typed data reads, providing built-in support for deduplication, prefetching, and stale-while-revalidate (SWR) patterns.
Sources: README.md:21-22, AGENTS.md:5-7, skills/farmjs/SKILL.md:195-200
Server Actions
Server Actions are asynchronous functions that execute on the server. You define them using the "use server" directive at the top of a file or function. Farm.js utilizes these actions to handle form submissions and other data mutations without requiring manual API endpoint creation.
Mutation Primitives
The framework provides the createServerFn utility for creating typed mutations and actions. These functions are often used in conjunction with useMutation on the client.
- Form Actions: Direct integration with HTML
<form>elements allows for progressive enhancement. - Bound Arguments: Farm.js supports optional encrypted bound arguments, ensuring that sensitive data passed from the client remains secure.
- Security: You can configure request security, including trusted origins and action body limits, within the framework configuration.
Sources: README.md:21-22, skills/farmjs/SKILL.md:215-220, skills/farmjs/SKILL.md:143-145
Server Action Flow
The following diagram illustrates how a Server Action moves from a client-side trigger to server-side execution and updates the UI.
This diagram shows the execution path of a Server Action from the client trigger to the server-side logic and the subsequent UI update via the RSC payload.
Sources: README.md:21-22, ARCHITECTURE.md:65-70
Server Queries
Server Queries are designed for data retrieval. They use the createServerQuery primitive to manage data fetching logic. This system ensures that data is fetched efficiently by deduplicating requests and supporting advanced caching strategies.
Query Features
Server Queries include several built-in optimizations:
- Deduplication: Prevents the same data from being requested multiple times in a single render pass.
- Prefetching: Allows the server to start fetching data before the client requests it.
- Stale-While-Revalidate (SWR): Serves cached data while fetching a fresh version in the background.
- Structured Invalidation: Provides mechanisms to invalidate specific queries when related data changes.
- Focus/Reconnect Refresh: Automatically refreshes data when the browser window regains focus or the network reconnects.
Sources: skills/farmjs/SKILL.md:215-220, README.md:31-33
Comparison of Primitives
| Primitive | Purpose | Key Features |
|---|---|---|
createServerFn | Mutations / Actions | "use server", Form actions, Encrypted arguments |
createServerQuery | Data Fetching / Reads | Deduplication, SWR, Prefetch, Invalidation |
Sources: skills/farmjs/SKILL.md:215-222
Configuration and Security
Server Actions and Queries must be explicitly enabled in the framework configuration. Security is managed through origin validation and body size limits.
Enabling Features
You enable these features in farm.config.ts under the experimental flag:
import { defineConfig } from "@farm.js/core";
export default defineConfig({
experimental: {
serverComponents: true,
serverActions: true,
},
serverActions: {
// Configure trusted origins and body limits here
}
});
Sources: examples/basic/README.md:22-30, skills/farmjs/SKILL.md:143-145
Security Constraints
- Server Function Transform: Browser references to server queries or actions require Farm's internal server-function transform. If this is not active, handlers must stay server-only, or developers must expose them via standard API routes.
- Trusted Origins: The framework allows restricting Server Action calls to specific trusted origins to prevent CSRF attacks.
- Secret Management: Server-only SDKs, credentials, and private environment variables are kept out of client modules and browser-reachable paths.
Sources: skills/farmjs/SKILL.md:220-224, AGENTS.md:75-78, skills/farmjs/SKILL.md:143-145
Integration with RSC and Routing
Server Actions and Queries are part of the React Server Components pipeline. When a Server Action is executed, it can trigger a refresh of the current route, causing the Server Renderer to re-load and re-render the RSC tree.
This sequence diagram shows how Server Actions interact with the Server Renderer to update the application state.
Sources: ARCHITECTURE.md:65-75, README.md:21-23
Summary
Server Actions and Queries provide a unified, typed interface for full-stack communication in Farm.js. By utilizing createServerFn for mutations and createServerQuery for data retrieval, developers can build applications that leverage RSC streaming and high-performance data fetching. These primitives ensure that server logic remains isolated from the client while maintaining type safety across the network boundary.
Sources: AGENTS.md:5-10, skills/farmjs/SKILL.md:215-225