Plugins System
Relevant source files
The following files were used as context for generating this wiki page:
The Plugins System provides an extensibility layer for the Farm.js framework. It enables you to modify framework behavior, intercept requests, transform HTML output, and hook into the build process. The system uses a centralized PluginManager to orchestrate execution across development and production environments.
Sources: ARCHITECTURE.md:213-219, README.md:188-193, skills/farmjs/SKILL.md:212-225
Architecture and Orchestration
The PluginManager is the core component that manages the registration and execution of plugins. It maintains an internal list of plugins and provides methods to trigger hooks either serially or in parallel.
Plugin Manager Lifecycle
In production, the PluginManager is initialized within the server entry point. It manages the runtime state through dedicated start and close hooks.
Hook Execution Modes
The system executes hooks in two primary modes:
- Parallel: Hooks run simultaneously using
runHookParallel. This is typical for informational hooks likebeforeRouteMatch. - Serial: Hooks run one after another using
runHookSerial. This is required for transformation hooks liketransformHTMLwhere one plugin's output is the input for the next.
Sources: packages/farm/src/nitro/universal-build.ts:1864-1875, packages/farm/src/nitro/universal-build.ts:1888-1890
Plugin Definition and Configuration
You define plugins using the definePlugin helper. Every plugin requires a unique name and can optionally specify an execution order.
Plugin Structure
| Field | Type | Description |
|---|---|---|
name | string | Unique identifier for the plugin. |
enforce | "pre" | "post" | Controls whether the plugin runs before or after others. |
setup | Function | Runs during the initial setup phase. |
transformHTML | Function | Asynchronous function to modify the final HTML response. |
beforeRequest | Function | Intercepts incoming requests before processing. |
Sources: README.md:195-204, skills/farmjs/SKILL.md:223-225
Ordering Logic
Plugins run in the order they are defined in farm.config.ts. You use the enforce property to prioritize critical operations like logging or security headers.
Sources: skills/farmjs/SKILL.md:224-225
Hook Categories
The system categorizes hooks based on the application lifecycle: Build, Runtime, and Request.
Request and Rendering Lifecycle
These hooks execute during the active handling of a Web Standard request.
Build Lifecycle
Plugins can influence the Nitro build process and the final deployment output.
- beforeNitroBuild: Modifies the Nitro configuration before the server is built.
- afterNitroBuild: Executes logic after the deployment artifact is generated.
Sources: packages/farm/src/nitro/universal-build.ts:1210-1212, packages/farm/src/nitro/universal-build.ts:1330-1335
Integration with Vite
The Farm.js plugin system benefits from Vite's existing ecosystem. The framework leverages Vite's fast development server and its optimized build process. Custom Vite plugins can be provided directly through the vite field in the main configuration.
Sources: ARCHITECTURE.md:121-125, ARCHITECTURE.md:214
Built-in Server Plugins
Farm.js includes standard server plugins for common tasks. You import these from @farm.js/core/plugin/server.
- Logger: Provides request and event logging.
- Compression: Handles Gzip or Brotli encoding for server responses.
Sources: skills/farmjs/SKILL.md:224-225, packages/farm/src/nitro/universal-build.ts:1484-1485
Conclusion
The Plugins System provides a unified interface to extend Farm.js across the entire stack. By combining the PluginManager for custom runtime logic with the underlying Vite system for build-time transforms, it ensures a flexible environment for product-specific integrations.
Sources: ARCHITECTURE.md:15-18, AGENTS.md:59-62