Getting Started & CLI

Relevant source files

The following files were used as context for generating this wiki page:

• packages/create-farm-app/src/index.ts
• ARCHITECTURE.md
• README.md
• CONTRIBUTING.md
• AGENTS.md
• SKILL.md

Getting Started with Farm.js involves using the interactive project generator to scaffold a new application and the Command Line Interface (CLI) to manage development and production lifecycles. The CLI (@farm.js/cli) serves as the primary entry point for developers, orchestrating the Vite-powered development server and Nitro-backed production builds.

The framework provides a unified experience across different renderers and deployment targets, ensuring that projects remain typed and predictable from initial creation to final deployment.

Project Scaffolding

You create new projects using @farm.js/create-app. This tool provides an interactive walkthrough to select project names, templates, and renderers.

Project Initialization Flow

The following diagram illustrates the logical steps performed by the createApp function when initializing a new project.

Scaffolding Logic

• Template Selection: You choose from various starters including basic, auth, ai, and specific provider integrations like stripe or supabase. Sources: packages/create-farm-app/src/index.ts:40-136
• Renderer Adaptation: While React is the default, the tool applies specific overlays for Preact, Solid, Vue, or Svelte if selected. This involves removing React-specific files and merging renderer-specific package.json dependencies. Sources: packages/create-farm-app/src/index.ts:241-260, packages/create-farm-app/src/index.ts:316-339
• Integration Injection: For templates with integrations, the tool automatically calls addFarmIntegration to configure providers and write environment variable examples. Sources: packages/create-farm-app/src/index.ts:297-308

CLI Commands

The CLI manages the execution modes of the framework. It bridges user commands to the core framework logic located in @farm.js/core.

Command	Action	Description
farm dev	Starts development server	Leverages Vite for instant startup and HMR.
farm build	Generates production build	Creates optimized server and client bundles via Nitro.
farm doctor	Diagnostic check	Verifies environment, configuration, and resolves issues.
farm upgrade	Updates packages	Aligns all @farm.js/* packages to latest or beta versions.
farm explain <path>	Debugs routing	Explains how a specific path is resolved by the runtime.
farm migrate	Data migration	Runs schema and provider commands (e.g., auth migration).

Sources: ARCHITECTURE.md:27-33, AGENTS.md:144-153, SKILL.md:465-475

Development and Production Modes

The CLI handles two distinct execution paths: the Vite-backed development path and the Nitro-backed production path.

Project Structure

A standard Farm.js project follows a specific directory layout designed for file-based routing and clear separation of concerns.

• src/app/: Contains the application routes, including layout.tsx, page.tsx, loading.tsx, and error.tsx.
• farm.config.ts: The central configuration file using defineConfig.
• src/lib/: Recommended location for shared logic, such as api.ts for typed clients and integrations.ts.
• .farm/: The default output directory for builds and generated metadata.

Sources: README.md:141-153, SKILL.md:17-26

Configuration

Farm.js projects are configured via farm.config.ts. This file controls rendering behavior, experimental features, and provider integrations.

import { defineConfig } from "@farm.js/core";

export default defineConfig({
  experimental: {
    serverComponents: true, // Enables React Server Components
  },
  deploy: {
    target: "vercel", // Sets the deployment target
  },
  renderer: "react", // Default renderer (can be vue, svelte, etc.)
});

Sources: README.md:121-127, SKILL.md:86-94

Summary

Starting with Farm.js requires using the @farm.js/create-app utility to initialize a project with a selected renderer and template. Once scaffolded, the farm CLI provides the necessary tools to run a high-performance development environment and generate production-ready artifacts compatible with various cloud platforms via Nitro adapters.