Application configuration

Use Node.js 20.19+ or 22.12+ and run commands from the project root. A generated project already contains both configuration files. Edit those files in place instead of replacing them with an example from another project.

defineConfig preserves literal types and catches unsupported top-level fields. Paths are relative to the project root. Keep every existing plugin and CSS entry when adding another integration. Tavo.js has one framework configuration file at the project root; imported and computed values are evaluated consistently by development, build, inspection, and production.

tsimport { defineConfig } from "@tavojs/core/config";
import { tavoUi } from "@tavojs/ui/plugin";

export default defineConfig({
  pagesDir: "src/pages",
  cssEntries: ["src/styles.css"],
  diagnostics: {
    devOverlay: true,
    traces: false
  },
  build: {
    prerenderStyles: "inline",
    budgets: {
      firstLoadJs: "150kb",
      routeJs: "40kb"
    }
  },
  ssr: {
    trustedHosts: ["example.com"],
    canonicalOrigin: "https://example.com"
  },
  plugins: [tavoUi()]
});

These are all accepted top-level TavoConfig properties in tavo.config.ts. defineConfig rejects any other top-level key at typecheck time. Every property is optional, but the file and its default defineConfig export are required.

tsimport { defineConfig } from "@tavojs/core/config";

export default defineConfig({
  pagesDir: "src/pages",
  cssEntries: ["src/styles/app.scss"],
  diagnostics: {
    devOverlay: true,
    traces: false
  },
  ssr: {
    canonicalOrigin: "https://example.com"
  }
});

Budget strings accept bytes or the case-insensitive units b, kb, kib, mb, and mib; decimal strings such as 1.5mb are valid. Numeric values are bytes. CLI flags override the file for one build.

bashnpx tavo build --max-first-load-js 150kb --max-route-js 40kb
npx tavo build --prerender-styles external

The ssr object accepts the following properties. The CLI supplies discovered route modules and compiles top-level plugins, so most applications configure only origin security, rendering, caches, or images here.

Configure ssr.csrActions when a statically hosted CSR application should submit Tavo.js forms to a separate action server. resolveUrl takes precedence over baseUrl.

tsimport { defineConfig } from "@tavojs/core/config";

export default defineConfig({
  ssr: {
    csrActions: {
      enabled: true,
      baseUrl: "https://actions.example.com",
      credentials: "include",
      headers: ({ pathname }) => ({
        "X-Tavo.js-Route": pathname
      })
    }
  }
});

ssr.document sets defaults for the server-rendered document shell. Route head exports and Tavo.js SEO components can refine metadata per route.

tsimport { defineConfig } from "@tavojs/core/config";

export default defineConfig({
  ssr: {
    images: {
      allowRemote: true,
      remotePatterns: [
        {
          protocol: "https:",
          hostname: "images.example.com",
          pathname: "/products"
        }
      ],
      defaultFormat: "avif",
      quality: 80
    }
  }
});

Server image transforms require the optional sharp dependency in the application that runs SSR. Remote requests are checked against the allowlist, redirects, DNS results, private-network addresses, timeout, and byte limit.

Use the public SsrStaticCache interface from @tavojs/core/server when rendered static and revalidated responses must be shared across processes or persisted outside Node memory. Methods may return values directly or through promises.

tsimport type {
  SsrStaticCache,
  SsrStaticCacheEntry
} from "@tavojs/core/server";

const entries = new Map<string, SsrStaticCacheEntry>();

export const staticCache: SsrStaticCache = {
  get(key) {
    return entries.get(key) ?? null;
  },

  set(key, entry) {
    entries.set(key, entry);
  },

  delete(key) {
    entries.delete(key);
  },

  invalidateTags(tags) {
    const requested = new Set(tags);
    let deleted = 0;

    for (const [key, entry] of entries) {
      if (entry.tags.some((tag) => requested.has(tag))) {
        entries.delete(key);
        deleted += 1;
      }
    }

    return deleted;
  },

  clear() {
    entries.clear();
  }
};

SsrStaticCacheEntry contains the rendered response, an absolute expiresAt timestamp or null, and its cache tags. The built-in createMemoryStaticCache is available from @tavojs/core/server. The Map above illustrates the contract; use a shared cache implementation for multi-process production deployments.

defineTavoViteConfig installs Tavo.js's TSX transform, file-route build guards, SVG support, localization splitting, and plugin build contributions. Pass your Vite settings into the wrapper rather than replacing it with Vite's defineConfig.

tsimport { defineTavoViteConfig } from "@tavojs/core/config";

export default defineTavoViteConfig(({ mode }) => ({
  server: {
    port: mode === "development" ? 4174 : undefined
  },
  build: {
    sourcemap: mode !== "production"
  }
}));

bashnpx tavo info
npx tavo check
npm run build

info shows the resolved pages and CSS configuration, check reports route and project-shape problems, and the production build exercises both client and server configuration. If a plugin was added, run npx tavo inspect plugins as well.