Configuration

When running a Vercube application, you can configure various aspects of your application using a configuration object. This page documents all available configuration options.

Config File

The most basic config file looks like this:

import { defineConfig } from '@vercube/core'

export default defineConfig({
  // config options
})

Attempting to read or modify other configuration properties during runtime will result in an error.

Config Options

Production Mode

{
  production?: boolean
}

Flag indicating if the application is running in production mode. When set to true, enables production optimizations.

Development Mode

{
  dev?: boolean
}

Flag indicating if the application is running in development mode. When set to true, enables development features like hot module replacement.

Log Level

{
  logLevel?: 'error' | 'warn' | 'info' | 'debug' | 'trace'
}

Controls the verbosity of logging output. Defaults to 'info' in production and 'debug' in development.

Server Options

{
  server?: {
    runtime?: 'node' | 'bun' | 'deno'
    host?: string
    port?: number
    https?: false | {
      key: string
      cert: string
    }
    static?: {
      dirs: string[]
      maxAge?: number
      immutable?: boolean
      etag?: boolean
    }
  }
}

Runtime

Specifies the JavaScript runtime environment for the server. Supported values:

• 'node' - Node.js runtime
• 'bun' - Bun runtime
• 'deno' - Deno runtime

Host

The hostname to bind the server to. Defaults to 'localhost'.

Port

The port number to listen on. Defaults to 3000.

HTTPS

Configuration for HTTPS server. When set to false, server runs in HTTP mode. When enabled, requires:

• key: Path to SSL key file
• cert: Path to SSL certificate file

Static

Configuration for serving static files:

• dirs: Array of directories to serve static files from
• maxAge: Cache duration in seconds
• immutable: Whether to mark files as immutable
• etag: Whether to enable ETag support

Runtime Configuration

IMPORTANT

Only the runtime configuration property is available to be read and modified during application execution. All other configuration properties are read-only and can only be set during application initialization.

{
  runtime?: {
    session?: {
      secret?: string
      name?: string
      duration?: number
    }
  }
}

Session

Configuration for session management:

• secret: Secret used to sign session ID cookie
• name: Name of the session ID cookie
• duration: Session duration in milliseconds

Build Options

{
  build?: {
    root?: string
    entry?: string
    output?: {
      dir?: string
      publicDir?: string
    }
    bundler?: 'rolldown'
  }
}

Root

The root directory for the application build.

Entry

The entry point file for the application build.

Output

Build output configuration:

• dir: Main output directory for build artifacts
• publicDir: Directory for public/client-side build artifacts

Bundler

The bundler to use for the application build. Currently supports:

• 'rolldown' - Rolldown bundler

Experimental Options

{
  experimental?: {
    // Experimental features configuration
  }
}

Configuration for experimental features. These options may change or be removed in future versions.

Type Definitions

All configuration types are available from the @vercube/core package:

import type { ConfigTypes } from '@vercube/core'

Environment Variables

You can use environment variables in your configuration. They are loaded from .env files in your project root:

VERCUBE_SERVER_PORT=3000
VERCUBE_SERVER_HOST=localhost
VERCUBE_LOG_LEVEL=debug

Environment variables are prefixed with VERCUBE_ to avoid conflicts with other applications.