#Frontend Configuration

This page is a decision guide, not a second copy of every type member. Start with the defaults, configure only the behavior that changes for your product, and use the canonical VextFrontendConfig API reference when you need an exact field, default, or nested option.

#Table of Contents

• Minimal Config
• Choose What to Configure
• Complete Example
• Production Delivery Profiles
• Core Fields
• Build Fields
• Deploy Fields
• SEO Fields
• I18n Fields
• Dev Fields
• SPA Fallback Fields
• Verify a Configuration Change

#Choose What to Configure

Avoid adding a field merely because it exists. The defaults deliberately keep the runtime small: React + esbuild, SSR on, buffered streaming, browser code splitting on, production browser minification on, and no CDN/upload adapter.

#Minimal Config

export default {
  frontend: true,
};

Use false to disable frontend completely:

export default {
  frontend: false,
};

frontend: true uses src/frontend, pages, components, styles/index.css, and public conventions. It creates dist/client in a production build; browser minification is enabled and browser source maps are disabled by default. The SSR renderer is a separate Node bundle and stays unminified by default for diagnostics.

#Complete Example

export default {
  frontend: {
    enabled: true,
    framework: "react",
    root: "src/frontend",
    publicDir: "public",
    publicPath: "/",
    styles: {
      jscss: { enabled: true },
    },
    dev: {
      hot: true,
      fastRefresh: true,
      renderRefresh: "prompt",
    },
    build: {
      target: "es2022",
      minify: true,
      sourcemap: false,
      client: {
        external: [],
        externalRuntime: {},
      },
      vendorChunks: {
        enabled: true,
        packages: ["react", "react-dom", "react-dom/client"],
      },
      assets: {
        inlineLimit: 0,
      },
      css: {
        modules: true,
      },
      budgets: {
        maxInitialJsBrotliBytes: 60_000,
        maxRouteInitialJsBrotliBytes: 80_000,
        maxAppOwnedInitialJsBrotliBytes: 40_000,
      },
      diagnostics: {
        leakScan: true,
        performanceReport: true,
      },
    },
    deploy: {
      assetBaseUrl: "https://cdn.example.com/my-app/",
      crossOrigin: "anonymous",
      integrity: true,
      upload: {
        enabled: true,
        adapter: "filesystem",
        targetDir: ".vext/frontend-cdn",
        publicBaseUrl: "https://cdn.example.com/my-app/",
        prefix: "my-app",
        stateFile: ".vext/deploy/frontend-assets-state.json",
        exclude: ["**/*.map"],
      },
    },
    i18n: {
      enabled: true,
      defaultLocale: "en-US",
      clientLoad: "current",
    },
    spaFallback: {
      scopes: [],
    },
    apiClient: true,
  },
};

#Production Delivery Profiles

#Same-origin (default)

Do not configure a CDN for the first production deployment:

export default {
  frontend: true,
};

vext build writes the frontend closure to dist/client; vext start validates it and serves assets plus SSR from the same Node service. This is the baseline to keep when a separate static origin provides no material value.

#CDN plus incremental upload

Add only the delivery fields required by the CDN path:

export default {
  frontend: {
    deploy: {
      assetBaseUrl: "https://cdn.example.com/my-app/",
      integrity: true,
      upload: {
        enabled: true,
        adapter: "filesystem",
        targetDir: ".vext/frontend-cdn",
        stateFile: ".vext/deploy/frontend-assets-state.json",
        exclude: ["**/*.map"],
      },
    },
  },
};

filesystem only stages a deploy tree. Use a custom adapter for a real provider; no cloud SDK or bundler-plugin ecosystem is implicitly installed. Keep the state file outside frontend.outDir, run vext deploy assets --dry-run, then deploy the matching Node dist/ output.

#Core Fields

#Style Fields

#Build Fields

React-related browser externals must define externalRuntime mappings. Otherwise the build fails with a friendly diagnostic.

Browser output is directory-based and uses frontend.outDir; frontend.build.client.outFile is not supported. Vext always emits the frontend manifest family required by SSR, preload, deploy, and verification, so build.client.manifest / build.server.manifest are not configuration fields.

For a normal product, keep browser code splitting, hashed names, and the Vext-managed vendor entry enabled. Start with budgets as warnings, inspect the complete route closure in size-report.json, and only then turn the budget into a release-blocking gate.

#Deploy Fields

assetBaseUrl must be an absolute URL. deploy-manifest.json uploads JS, CSS, imported media, and copied public files; it does not upload SSR HTML or source maps by default. Use vext deploy assets --dry-run before every new adapter, prefix, or include/exclude rule.

#SEO Fields

frontend.seo is the framework-level SEO entry point. It is disabled when omitted; when the object is present, enabled defaults to true.

frontend: {
  seo: {
    publicOrigin: process.env.PUBLIC_ORIGIN ?? "https://www.example.com",
    titleTemplate: "%s | Example",
    defaults: { description: "Example application" },
    sitemap: {},
    robots: {},
  },
}

publicOrigin identifies the deployment origin. Vext combines it with each request pathname, so dynamic pages do not share one fixed URL. Use route-level frontend.seo for static metadata and res.render(..., { seo }) for metadata derived from page data. sitemap and robots can use "build" or "runtime" mode; named origins support a finite multi-domain deployment.

See SEO, Sitemap, and Robots for dynamic canonical, provider, host-selection, output, and no-hydration examples. The exact nested field list is in the API reference.

#I18n Fields

#Dev Fields

frontend.dev.overlay only controls frontend browser development UI. Backend exception HTML overlays are configured separately through top-level dev.errorOverlay.

#SPA Fallback Fields

Declare individual scopes instead of a site-wide catch-all. API, OpenAPI, and documentation routes stay excluded by default so a client-router shell cannot hide an operational endpoint.

#Verify a Configuration Change

# Compile the backend, browser, and SSR closure.
vext build

# Required only when configuring an upload path; inspect before writing.
vext deploy assets --dry-run

# Verify the production closure and start the Node runtime.
vext start

For a build or budget change, inspect dist/client/size-report.json. For a CDN change, request one SSR page and one hashed browser asset and confirm they belong to the same release. For SPA fallback, also request a deliberately excluded API path. The API reference is the canonical source for less-common nested fields.