Configuration options

Rakkas looks for a configuration file named rakkas.config.js (or .ts) in your project root. This file is bundled with esbuild before loading, so you can use modern EcmaScript and TypeScript features.

The configuration file is not needed if you're happy with the defaults.

This file should default export a configuration object or a function that returns one (possibly asynchronously). Supported options are:

PropertyDescriptionDefault value
pageExtensionsFile extensions for pages and layouts["jsx", "tsx"]
pagesDirDirectory that contains pages and layouts relative to /src"pages"
endpointExtensionsFile extensions for endpoints and middleware["js", "ts"]
apiDirDirectory that contains API routes relative to /src"api"
apiRootBase URL for API routes"/api"
trustForwardedOriginSet to true to trust x-forwarded-* headers during development¹false
prerenderAn array of paths to be pre-rendered.[] (["/"] for static)
vite Vite configuration (not all options are supported){}
babel Babel options passed to Vite's React plugin{}
modifyEsbuildOptionsHook to modify ESBuild options used when bundling serverless functionsundefined
locales.defaultDefault locale"en"
locales.detectSet to true to enable locale detectionfalse
locales.cookieNameName of the locale override cookieundefined

¹ See the TRUST_FORWARDED_ORIGIN environment variable for production use.


You can import the defineConfig function from @rakkasjs/cli to ensure TypeScript IDE completion.

Conditional configuration

You can provide a function (can be async) instead of a configuration object. The function will be called with the following info:

export interface ConfigFactoryInfo {
    /** Rakkas command that is being executed */
    command: "dev" | "build";

    /** Deployment target (only available for the "build" command) */
        | "node"
        | "static"
        | "vercel"
        | "netlify"
        | "cloudflare-workers";

You can also provide a function for Vite configuration. In build mode, it will be called with an argument specifying whether the configuration will be used for "ssr" or "client".