Skip to main content
Veryfront follows convention over configuration. Start with the default directories and runtime behavior. Add veryfront.config.ts when a project needs to deviate from those conventions. Use environment variables for secrets and deployment-specific values. The framework reads config and environment variables automatically.

​
Prerequisites

  • A project created with veryfront init (see Create project).
  • Write access to veryfront.config.ts when you need to override conventions.
  • Write access to the project’s .env file or deployment environment when you need secrets or deployment-specific values.

​
When to use config

Use veryfront.config.ts for stable project choices:
  • Change directory conventions.
  • Select app-router or pages-router mode.
  • Change build output or trailing-slash behavior.
  • Add a custom layout or app wrapper.
  • Tune discovery paths for agents, tools, skills, prompts, resources, workflows, or tasks.
  • Set project-level provider or MCP defaults.
Do not add config just to mirror defaults. Keep the file small and add options when the project has a concrete reason to deviate.

​
Config file

// veryfront.config.ts
import { defineConfig } from "veryfront";

export default defineConfig({
  title: "My App",
  description: "A Veryfront application",
});
defineConfig provides TypeScript autocompletion but doesn’t transform the config. It is a pass-through for type safety.

​
Options

​
Project metadata

defineConfig({
  projectSlug: "my-app", // Project identifier
  title: "My App", // Default page title
  description: "A great app", // Default meta description
});

​
Directories

Override the default directory conventions: 
defineConfig({
  directories: {
    app: "src/app", // Override page/route directory
    pages: "src/pages", // Override pages-router directory
    components: ["src/components"],
    ai: "src/ai",
  },
});

​
Router mode

defineConfig({
  router: "app", // "app" (default) | "pages"
});

​
Build

defineConfig({
  build: {
    outDir: "dist", // Output directory
    trailingSlash: false, // Add trailing slashes to URLs
  },
});

​
Layout

defineConfig({
  layout: "components/layout.tsx", // Custom layout path
  // layout: false,                 // Disable layout
});

​
App wrapper

defineConfig({
  app: "components/app.tsx", // Custom app wrapper
  // app: false,                // Disable app wrapper
});

​
React version

defineConfig({
  react: {
    version: "19.1.1", // Override detected React version
  },
});

​
Experimental features

defineConfig({
  experimental: {
    rsc: true, // React Server Components
    precompileMDX: true, // Pre-compile MDX at build time
  },
});

​
AI discovery

Control which directories are scanned for AI primitives: 
defineConfig({
  ai: {
    tools: {
      discovery: {
        enabled: true,
        paths: ["tools", "packages/shared-tools"],
      },
    },
    agents: {
      discovery: {
        enabled: true,
        paths: ["agents"],
      },
    },
    skills: {
      discovery: {
        enabled: true,
        paths: ["skills", "team-skills"],
      },
    },
    prompts: {
      discovery: {
        paths: ["prompts"],
      },
    },
    resources: {
      discovery: {
        paths: ["resources"],
      },
    },
    workflows: {
      discovery: {
        paths: ["workflows"],
      },
    },
    tasks: {
      discovery: {
        paths: ["tasks"],
      },
    },
  },
});
Notes:
  • paths are relative to your project root.
  • Defaults are tools, agents, skills, prompts, resources, workflows, and tasks.
  • Set enabled: false to disable discovery for that primitive.

​
AI providers and MCP

Configure provider defaults or the app-facing MCP surface: 
defineConfig({
  ai: {
    providers: {
      openai: {
        defaultModel: "gpt-4o-mini",
      },
    },
    mcp: {
      enabled: true,
      port: 3002,
      expose: ["tools", "prompts", "resources"],
    },
  },
});

​
Environment variables

Set secrets and deployment-specific values in .env files or your deployment platform. Keep stable project structure in veryfront.config.ts. Common groups:
  • Cloud bootstrap: VERYFRONT_API_TOKEN, VERYFRONT_PROJECT_ID, VERYFRONT_PROJECT_SLUG, and VERYFRONT_API_URL.
  • Agent services: VERYFRONT_AGENT_SERVICE_NAME, VERYFRONT_AGENT_SERVICE_URL, VERYFRONT_AGENT_SERVICE_KEY, VERYFRONT_AGENT_SERVICE_REGISTRATION, and VERYFRONT_AGENT_SERVICE_REGION.
  • Provider keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, and provider-specific base URLs.
  • Runtime: PORT, NODE_ENV, REDIS_URL, request timeouts, SSR limits, and VERYFRONT_EXPERIMENTAL_RSC.
  • Observability: VERYFRONT_OTEL, OTEL_TRACES_ENABLED, OTEL_METRICS_ENABLED, OTLP endpoints, and OTEL_SERVICE_NAME.
Use Providers for model-provider setup. Use Agent service runtime for the registration variables used by standalone agent services.

​
Environment-based config

Use getEnv to read environment variables inside your config: 
import { defineConfig, getEnv } from "veryfront";

const isProd = getEnv("NODE_ENV") === "production";

export default defineConfig({
  title: isProd ? "My App" : "My App (Dev)",
  build: {
    outDir: isProd ? "dist" : ".dev",
  },
});

​
Reading config at runtime

The framework reads veryfront.config.ts automatically. Your config values are available to the build system and dev server. Pages and API routes access config indirectly through the features it enables (port, build output, router mode, etc.).

​
Verify it worked

After editing veryfront.config.ts, restart veryfront dev. The dev banner prints the resolved title, output directory, and router mode. Set a distinctive title and check that the document title in the browser matches. For environment variables, read them back from a temporary API route. For example, return getEnv("VERYFRONT_API_TOKEN") from a debug route and remove it once you have confirmed the value resolves.