Deployment Presets & Edge
Relevant source files
The following files were used as context for generating this wiki page:
Deployment Presets & Edge define how Farm.js applications are bundled, optimized, and delivered to various hosting providers. The framework produces production-ready output through Nitro-backed deployment targets, allowing a single codebase to run across Node.js servers, serverless functions, and Edge runtimes.
Sources: AGENTS.md:6, ARCHITECTURE.md:65-69
Deployment Terminology
Farm.js distinguishes between deployment "targets" and "presets" to manage platform compatibility and Nitro-specific configurations.
- Target: A first-class Farm deployment target representing a specific hosting platform (e.g., Vercel, Cloudflare, Netlify).
- Preset: A direct Nitro preset pass-through that determines the final output format and adapter.
Sources: AGENTS.md:54, packages/farm/src/config.ts:168-171
Target to Preset Mapping
Farm.js automatically maps targets to their corresponding Nitro presets:
| Target | Nitro Preset | Default Output Directory |
|---|---|---|
vercel | vercel | .vercel/output |
cloudflare | cloudflare-pages | .farm/.output |
netlify | netlify | .farm/.output |
node | node-server | .farm/.output |
Sources: packages/farm/src/config.ts:251-274, packages/farm/src/config.ts:333-336
Configuration and Platform Detection
The framework resolves deployment settings using the deploy object in farm.config.ts. If no configuration exists, Farm.js detects the platform via environment variables during CI builds.
Platform Detection Flow
The diagram illustrates the priority of configuration: explicit user settings always override automated platform detection.
Sources: packages/farm/src/config.ts:318-361
Deployment Configuration Options
Users configure deployment behavior via FarmDeployConfig:
target: Sets the deployment platform.preset: Overrides the inferred Nitro preset.outputDir: Specifies where deployable assets are written.projectName: Defines the project name for provider-specific CLI tools (e.g., Cloudflare Pages).
Sources: packages/farm/src/config.ts:166-193
Edge Runtime Adaptation
Farm.js optimizes applications for Edge runtimes by swapping Node.js dependencies with Web-standard alternatives and modifying the rendering pipeline.
Detection and Runtime Classification
The framework classifies runtimes as either node or edge based on the selected preset.
- Edge Presets:
vercel-edge,cloudflare-pages,cloudflare-module,netlify-edge. - Node Presets:
node-server,vercel,netlify.
Sources: packages/farm/src/deployment.ts:47-60
React Edge Optimization
If an application targets an Edge runtime, Farm.js aliases react-dom/server to use specific Web-stream builds. This enables streaming SSR in environments that lack Node.js polyfills.
Build Pipeline and Nitro Integration
The production build process consists of three major steps: generating the client bundle, building the SSR bundle in memory, and executing the Nitro build.
- Client Build: Bundles browser-side assets and hydration code.
- SSR Build: Compiles React Server Components (RSC) and API routes into a virtual entry.
- Nitro Build: Packages the SSR entry with a provider-specific adapter (e.g., Vercel Functions, Cloudflare Workers).
Sources: packages/farm/src/nitro/universal-build.ts:466-550
Universal Handler Adapter
Farm.js uses a virtual entry to adapt its Web Standard fetch handler to Nitro's event contract. This allows the framework to maintain a consistent internal API while supporting diverse runtime environments.
Sources: packages/farm/src/nitro/universal-build.ts:1330-1410
Provider-Specific Logic
Vercel
Farm.js post-processes Vercel builds to comply with the Build Output API v3. It moves server files to functions/__nitro.func/ and updates config.json with route runtime functions.
Sources: packages/farm/src/nitro/universal-build.ts:1821-1870
Cloudflare
The framework supports both Cloudflare Pages and Cloudflare Workers (module preset). For Workers, Farm.js bundles dependencies that would otherwise be externalized in Node environments, as Workers do not provide a node_modules runtime.
Sources: packages/farm/src/config.ts:257, packages/farm/src/nitro/universal-build.ts:1225-1235
Netlify
Netlify deployments use Nitro's Netlify preset, which organizes output into .netlify/functions-internal or the directory specified in netlify.toml.
Sources: packages/farm/src/config.ts:261, tests/deploy-runtimes/provider-runtime.test.ts:310-318
Summary
Deployment Presets & Edge allow Farm.js to remain renderer-neutral and platform-agnostic. By leveraging Nitro, the framework automates platform detection, optimizes React for Edge environments via Web-stream aliasing, and ensures that builds comply with provider-specific standards like Vercel's Build Output API.