Developer Tools & Analytics
Relevant source files
The following files were used as context for generating this wiki page:
Developer Tools & Analytics in Farm.js provide runtime inspection, performance monitoring, and system diagnostics for full-stack applications. The system consists of a built-in DevTools inspector for development mode and an observability framework for production and development analytics. These tools help you track route matching, cache performance, and integration status.
Sources: ARCHITECTURE.md:160-170, packages/farm/src/vite.ts:397-400, examples/basic/README.md:46-56
Farm DevTools
Farm DevTools provides a navigable inspector for monitoring the application state during development. It collects metadata about routes, middleware, and integrations to present a comprehensive snapshot of the framework runtime.
DevTools Architecture
The DevTools system operates via a dedicated Vite middleware that intercepts requests to a specific internal path. It generates a system snapshot and renders a floating UI panel for the developer.
The DevTools flow shows how the system intercepts requests to gather runtime metadata before rendering the inspector panel.
Sources: packages/farm/src/vite.ts:1140-1175, packages/farm/src/tests/devtools.test.ts:133-160
Snapshot Data Collection
The DevTools snapshot captures the effective application runtime state. It aggregates counts and configurations for various framework primitives.
| Data Category | Monitored Components |
|---|---|
| Routing | Pages, Layouts, API Routes, Middleware |
| Logic | Integrations, Workflows, Cron Jobs |
| Infrastructure | Storage Mounts, Environment Variables, Deployment Target |
| Features | OpenAPI status, Server Components, Optimized Boundaries |
Sources: packages/farm/src/tests/devtools.test.ts:77-100
Diagnostics and Warnings
The DevTools inspector identifies configuration issues through automated diagnostics. It reports errors such as:
- CRON_ROUTE_MISSING: Scheduled tasks lacking a corresponding API route.
- CRON_SECRET_NOT_SET: Missing security credentials for cron execution.
- EPHEMERAL_PRODUCTION_STORAGE: Production environments using volatile memory storage instead of persistent drivers.
Sources: packages/farm/src/tests/devtools.test.ts:115-119
Observability Framework
The observability system emits runtime events for system-level actions. It allows you to monitor internal framework behavior such as caching efficiency and Partial Prerendering (PPR) status.
Event Logging and Handling
You configure observability in farm.config.ts. You can enable default logs or provide a custom onEvent handler to process specific event types.
// Example configuration in farm.config.ts
export default defineConfig({
observability: {
logs: true,
onEvent(event) {
if (event.type.startsWith("ppr.") || event.type.startsWith("cache.")) {
console.log(event);
}
},
},
});
Sources: examples/basic/README.md:49-56
Event Types
The framework emits events across multiple subsystems:
- Cache & PPR: Tracks
ppr.hit,ppr.miss, and cache invalidation. - Routing: Logs
route.matchedand API request durations. - Integrations: Monitors provider-owned route execution and failures.
- Middleware: Tracks execution flow through custom and first-party middleware.
Sources: packages/farm/src/vite.ts:1300-1310, examples/basic/README.md:46-48
Performance Analytics
Farm.js integrates performance tracking into the request lifecycle. The system measures durations for API routes and page rendering, exposing them through the development console.
The sequence shows how the observability system hooks into the API lifecycle to measure performance metrics.
Sources: packages/farm/src/vite.ts:1290-1320
Analytics in Documentation
The documentation system within Farm.js includes specialized analytics for search and SEO performance.
- Social Images: The system generates OpenGraph images dynamically for each documentation page.
- Search Discovery: The Docs API handler provides search results via
/api/docs?query=<term>. - Metadata Validation: SEO headers, including
og:titleandtwitter:card, are automatically verified during development.
Sources: packages/farm/src/tests/docs-handler.test.ts:244-275, packages/farm/src/tests/docs-handler.test.ts:500-515
Developer Tools and Analytics ensure that Farm.js applications remain observable and performant. By combining the DevTools snapshot system with a flexible observability framework, you can diagnose configuration errors and monitor runtime events effectively.