Database & ORM Support
Relevant source files
The following files were used as context for generating this wiki page:
Farm.js provides a structured environment for integrating databases and Object-Relational Mappers (ORMs) within full-stack applications. The framework uses a typed integration model to connect to external providers and leverages React Server Components (RSC) for direct server-side data access. These features ensure that database credentials and server-only SDKs remain isolated from client-side code.
Sources: README.md:46-52, AGENTS.md:68-72, ARCHITECTURE.md:79-84
Data Integration Architecture
Farm.js manages database interactions through two primary mechanisms: first-party integrations and direct Server Component queries. The framework prioritizes type safety and predictable boundaries, ensuring that server-only SDKs and credentials never leak into client modules or browser-reachable paths.
Integration Model
Integrations provide a typed capability to mount databases, authentication, and other services. Developers add databases through a single typed integration model that handles the connection lifecycle and provides typed clients to the application.
Sources: README.md:52, AGENTS.md:76-80
Server-Side Data Flow
React Server Components (RSC) facilitate direct communication with databases. Because RSCs execute exclusively on the server, they can invoke database drivers or ORMs without exposing the implementation details to the client.
The diagram shows the flow of data from a storage provider through the server-only integration layer to the streamed client response.
Sources: ARCHITECTURE.md:48-55, AGENTS.md:68-72
Content Collections and Schemas
Farm.js includes a dedicated content system for managing typed data from local files or remote sources. This system acts as a high-level ORM for structured content, utilizing schemas to validate and transform data before it reaches the application logic.
Collection Configuration
The collection function defines how data is retrieved and structured. It requires a source (such as local files or a remote API) and a schema for validation.
| Feature | Description |
|---|---|
| Source | Defines the location of data, supporting local globs or remote fetch calls. |
| Schema | Validates the data structure (e.g., ensuring a "title" is a string). |
| Transform | Modifies the data after validation (e.g., calculating reading time). |
| Assets | Manages associated files like images or PDFs linked in the data. |
Sources: packages/farm-content/src/loader.test.ts:47-68, packages/farm-content/src/byo-source.test.ts:31-37
Schema Validation
Farm.js enforces strict validation using a parsing pipeline. If a data entry fails to match the defined schema, the framework rejects the entry during the loading phase.
const postSchema = {
async parseAsync(value: unknown) {
const data = value as Record<string, unknown>;
if (typeof data.title !== "string") {
throw { issues: [{ path: ["title"], message: "Expected string" }] };
}
return {
title: data.title,
publishedAt: new Date(String(data.publishedAt)),
};
},
};
Sources: packages/farm-content/src/loader.test.ts:35-45
Remote Data Sources (BYO CMS)
The framework supports "Bring Your Own" (BYO) data sources through the remote provider. This allows developers to treat external HTTP APIs or CMS platforms as managed collections with the same validation and typing benefits as local databases.
Remote Implementation Flow
The sequence diagram illustrates how Farm.js retrieves and validates data from an external CMS using the remote source model.
Sources: packages/farm-content/src/byo-source.test.ts:54-69
Mutation Support
Remote sources can implement update and delete methods to write back to the data provider. The collection handle in the Farm.js runtime exposes these methods, ensuring that mutations follow the same typed contract as read operations.
Sources: packages/farm-content/src/byo-source.test.ts:71-77, packages/farm-content/src/byo-source.test.ts:117-123
Security and Performance
Security Boundaries
Farm.js enforces strict security protocols for database interactions:
- Credential Isolation: Private environment variables and database keys must remain in server-only modules.
- Untrusted Input: The framework treats route parameters, headers, and query strings as untrusted input when used in database queries.
- Prototype Pollution: Serialization and deserialization processes reject prototype-polluting keys and unsafe origins.
Sources: AGENTS.md:72-76, AGENTS.md:88-92, packages/farm-content/src/loader.test.ts:140-150
Observability and Caching
The framework provides observability hooks to monitor database and storage events. Developers can configure an onEvent handler in farm.config.ts to log or process cache hits, misses, and storage errors.
Sources: examples/basic/README.md:63-75
Summary
Database and ORM support in Farm.js centers on maintaining clear boundaries between the server and the client. By using a typed integration model and content collections with schema validation, the framework provides a secure and developer-friendly way to manage complex data requirements while leveraging Vite's fast development cycle and Nitro's production-ready deployment targets.