raclette Config

name

• Type: string
• Default: "raclette-app"

Title for the application.

services

• Type: object

Configuration of system services used in development and runtime.

services.client

Frontend development backend.

• enabled: boolean
  Whether the client service is enabled.
• port: number
  Port the client runs on.
• name?: string (optional)
  Custom name for the client container.
• nodeModulesVolume?: string (optional)
  Volume name for sharing node_modules.
• installPackages?: string[] (optional)
  Additional packages to install.
• volumes?: VolumeDefinition[] (optional)
  Additional volumes to mount.

services.backend

Backend service configuration.

• enabled: boolean
• port: number
• name?: string (optional)
• nodeModulesVolume?: string (optional)
• enableDebug?: boolean (optional)
  Enables debug mode.
• installPackages?: string[] (optional)
• volumes?: VolumeDefinition[] (optional)

services.mongodb

MongoDB container configuration.

• enabled: boolean
• port: number
• name?: string (optional)
• volume?: string (optional)
• databaseName?: string (optional)
• volumes?: VolumeDefinition[] (optional)

services.cache

Valkey/Redis cache service (used by app backend, workbench backend, and plugin cache layers).

• enabled: boolean
• port: number
• name?: string (optional)
  Custom container name (shared across stacks on the raclette_shared network).
• volume?: string (optional)
• db?: number (optional)
  Default Valkey database index for all stacks when no role-specific override is set.
  Defaults to 0. DB 0 is omitted from generated connection URLs (redis://cache:6379).
• dbs?: object (optional)
  Per-stack Valkey database index overrides. Configure these on the starting app's raclette.config.js — the workbench reads them via RACLETTE_APP_PATH, not from @raclettejs/workbench's own config.
  • app?: number — app backend container (services.backend).
  • workbench?: number — workbench backend container.
  • core?: number — reserved for future use when core and plugin caches can use separate in-process clients. Today, core plugins share the same Valkey connection as their host backend (app or workbench role).
• volumes?: VolumeDefinition[] (optional)

Cache DB resolution

For each stack, Raclette picks the Valkey DB index in this order:

1. RACLETTE_CACHE_URL environment variable — full override (host, port, and DB path). No DB suffix is appended when this is set.
2. services.cache.dbs[role] — role-specific override (app, workbench, or core).
3. services.cache.db — shared default for all roles.
4. 0 — implicit fallback.

The workbench backend uses the starting app's config (dbs.workbench / db), not the workbench package defaults.

Examples

Default — all stacks on DB 0 (typical setup; no config required):

services: {
  cache: {
    enabled: true,
    port: 6379,
  },
}

Explicit shared default:

services: {
  cache: {
    enabled: true,
    port: 6379,
    db: 0,
  },
}

Isolate app plugin cache from workbench (e.g. billing sync writes DB 2, workbench admin reads DB 0):

services: {
  cache: {
    enabled: true,
    port: 6379,
    db: 0,
    dbs: {
      app: 2,
    },
  },
}

Workbench on a separate DB:

services: {
  cache: {
    db: 0,
    dbs: {
      workbench: 1,
    },
  },
}

Full URL override (custom host, port, or DB — also the escape hatch for external or multiple Valkey instances):

RACLETTE_CACHE_URL=redis://my-cache:6379/3

Cache list widget

The workbench Cache list widget defaults to DB 0. When using non-zero dbs values, select the matching DB in the widget toolbar to inspect keys written by that stack.

services.redis

Legacy name

Use services.cache instead. Older docs and configs may refer to this service as redis.

• enabled: boolean
• port: number
• name?: string (optional)
• volume?: string (optional)
• db?: number (optional)
  Redis DB index to use.
• volumes?: VolumeDefinition[] (optional)

Additional Valkey services (kind: valkey)

Additional Valkey instances beyond the primary services.cache. Declare any service key that is not a built-in key (frontend, backend, workbench, mongodb, cache, redis) with kind: valkey.

In yarn raclette dev, raclette generates a Compose service, volume, and backend env var for each enabled entry. The backend registers the connection on fastify.valkeys.<serviceKey>.

Field	Type	Description
kind	"valkey"	Required marker for declarative Valkey infra.
enabled?	boolean	Default true. Set false to document an external instance without starting a dev container.
port?	number	Host port (default 6380, then 6381, …). Container listens on 6379.
name?	string	Docker container name (default <projectName>-<serviceKey>).
volume?	string	Named volume for /data (default <projectName>-<serviceKey>).
persistence?	"none" | "rdb" | "aof" | "rdb+aof"	Dev Compose valkey-server command (default "rdb+aof"). Independent of backend.cache.persistence on the primary cache.
RDB_OPTIONS?	string	RDB save schedule when persistence includes rdb. Falls back to backend.cache.RDB_OPTIONS.
envVar?	string	Override the generated env var name (default RACLETTE_VALKEY_<SERVICE_KEY_SNAKE>_URL).
volumes?	VolumeDefinition[]	Extra bind mounts, same as other services.

Env → instance id: CACHE_URL → cache. Each additional instance uses RACLETTE_VALKEY_<NAME>_URL where <NAME> is the service key in SNAKE_CASE (e.g. service key cachePersistent → RACLETTE_VALKEY_CACHE_PERSISTENT_URL → instance id cachePersistent on fastify.valkeys).

Example (playground-style second Valkey for persistent snapshots):

services:
  cache:
    enabled: true
    port: 6379
    db: 0
    dbs:
      workbench: 1
  cachePersistent:
    kind: valkey
    enabled: true
    port: 6380
    name: raclette-cache-persistent
    volume: raclette-cache-persistent
    persistence: rdb+aof

Guides: Valkey instances, Persistent external data, Config boilerplate.

Production / existing clusters

For an ops-managed Valkey that raclette must not start in dev, set enabled: false (or omit the block) and set RACLETTE_VALKEY_<NAME>_URL on the backend in your deployment environment.

services.workbench

workbench container (admin area)

• enabled: boolean
• port: number
• volumes?: VolumeDefinition[] (optional)

services.[custom]

Any additional custom service can be defined here. For extra Valkey servers, use Additional Valkey services (kind: valkey) instead of hand-written Compose.

volumes

• Type: Record<string, VolumeDefinition | null> (optional)

Global volumes for the Docker Compose setup.

modules

• Type: Array<string | [string, any]>
• Default: []

List of Raclette modules to load. You can pass config using [name, options].

env

• Type: object

Environment-specific values injected at runtime.

env.development

• Type: Record<string, any>
  Environment variables for development mode.

env.production

• Type: Record<string, any>
  Environment variables for production mode.

env.[custom]

You may define additional environments.

global

• Type: object

Global configuration for frontend and backend

global.requireAuthentication

• Type: boolean (optional)
  Defines if a login is required.

frontend

• Type: object

Frontend configuration.

frontend.framework

• Type: "vue" | "react"
  Defines the primary frontend framework.

frontend.vue.plugins?

• Type: string[] (optional)
  Vue plugins to register.

frontend.react.plugins?

• Type: string[] (optional)
  React plugins to register.

frontend.custom?

• Type: Record<string, any> (optional)
  Custom frontend options.

backend

• Type: object

Backend configuration.

backend.sockets

See SocketConfig for full details.

backend.custom?

• Type: Record<string, any> (optional)

backend.cacheTTL

• Type: number (optional)
  Defines a default time to live for backend cache entries.
  If a default TTL is set, a -1 TTL must be explicitly passed to cache.cache() to have no TTL.

backend.cache.persistence

• Type: "none" | "rdb" | "aof" | "rdb+aof" (optional, default "none")
  Docker/dev persistence mode for the primary services.cache container.

auth

Top-level authentication block (merged into generated backend config). See Authentication.

auth.valkeyInstances

Optional mapping of auth roles to registered instance ids (not three mandatory servers). Defaults: all roles use "cache".

Key	Default	Purpose
sessions	"cache"	Raclette session records
oauthState	"cache"	OAuth CSRF state
providerTokens	"cache"	OAuth provider token blobs when persistProviderTokens is enabled

Full guide: Valkey instances.

auth.valkey.keyPrefix

• Type: string (default "auth:")
  Prefix for session and OAuth state keys on the session/oauth Valkey connections.

typescript

• Type: object (optional)

TypeScript-specific overrides.

typescript.compilerOptions?

• Type: Record<string, any> (optional)
  Pass-through compiler options.

eslint

• Type: object (optional)

ESLint configuration.

eslint.rules?

• Type: Record<string, any> (optional)

eslint.plugins?

• Type: string[] (optional)

eslint.extends?

• Type: string[] (optional)

eslint.ignores?

• Type: string[] (optional)

eslint.useRecommended?

• Type: boolean (optional)
  Enable recommended ESLint config.

eslint.env?

• Type: Record<string, any> (optional)

VolumeDefinition

Defines a volume mount between host and container.

• source: string
  Named volume or host path.
• target: string
  Container path.
• type?: "bind" | "volume" | "tmpfs" (optional)
• readonly?: boolean (optional)
• volumeOptions?: object (optional)
  • nocopy?: boolean (optional)
• bindOptions?: object (optional)
  • propagation?: string (optional)
  • createHostPath?: boolean (optional)
• tmpfsOptions?: object (optional)
  • size?: number (optional)
  • mode?: number (optional)

SocketConfig

WebSocket configuration used by the backend.

sockets.autoSend

Automatically push data when client connects.

• compositions: boolean
• interactionLinks: boolean
• projectConfig: boolean
• additionalDatatypes: Record<string, boolean | undefined>
• customData?: Record<string, any> (optional)

sockets.security

WebSocket authentication config.

• requireAuth: boolean
• tokenValidation: "jwt"
• customValidator?: string (optional)

sockets.options

Advanced socket settings.

• adapter: "memory" | "redis" | "mongodb"
• connectionTimeout: number
• pingInterval: number
• pingTimeout: number

Type Declarations

Show Type Declarations

/**
 * Raclette Configuration with ESLint properties
 */
export interface RacletteConfig {
  name: string
  services: {
    client?: {
      enabled: boolean
      port: number
      name?: string
      nodeModulesVolume?: string
      installPackages?: string[]
      volumes?: VolumeDefinition[] // Add custom volumes property
    }
    backend?: {
      enabled: boolean
      port: number
      name?: string
      nodeModulesVolume?: string
      enableDebug?: boolean
      installPackages?: string[]
      volumes?: VolumeDefinition[] // Add custom volumes property
    }
    mongodb?: {
      enabled: boolean
      port: number
      name?: string
      volume?: string
      databaseName?: string
      volumes?: VolumeDefinition[] // Add custom volumes property
    }
    redis?: {
      enabled: boolean
      port: number
      name?: string
      volume?: string
      db?: number
      volumes?: VolumeDefinition[] // Add custom volumes property
    }
    cache?: {
      enabled: boolean
      port: number
      name?: string
      volume?: string
      /** Default Valkey DB index for all roles (default: 0). */
      db?: number
      /** Per-stack Valkey DB overrides. */
      dbs?: {
        app?: number
        workbench?: number
        core?: number
      }
      volumes?: VolumeDefinition[]
    }
    workbench?: {
      enabled: boolean
      port: number
      volumes?: VolumeDefinition[] // Add custom volumes property
    }
    [key: string]: any
  }
  // Additional global volumes definition for the compose file (top-level named volumes)
  volumes?: Record<string, VolumeDefinition | null>
  modules: Array<string | [string, any]>
  env: {
    development: Record<string, any>
    production: Record<string, any>
    [key: string]: Record<string, any>
  }
  frontend: {
    framework: "vue" | "react"
    vue?: {
      plugins: string[]
    }
    react?: {
      plugins: string[]
    }
    custom?: {
      [key: string]: any
    }
  }
  backend: {
    sockets: SocketConfig
    custom?: {
      [key: string]: any
    }
  }
  typescript?: {
    compilerOptions?: {
      // Allow for any compiler option to be overridden
      [key: string]: any
    }
  }
  eslint?: {
    rules?: Record<string, any>
    plugins?: string[]
    extends?: string[]
    ignores?: string[]
    // Whether to use recommended rules
    useRecommended?: boolean
    // For environment-specific configurations
    env?: Record<string, any>
  }
}

/**
 * Volume Definition for Docker Compose
 */
export interface VolumeDefinition {
  // Source can be a named volume, host path, or volume specification
  source: string
  // Target is the path inside the container
  target: string
  // Optional volume type (bind, volume, tmpfs)
  type?: "bind" | "volume" | "tmpfs"
  // Optional read-only flag
  readonly?: boolean
  // Optional volume driver-specific options
  volumeOptions?: {
    // Populate on service creation when volume doesn't exist
    nocopy?: boolean
    // Any other driver-specific options
    [key: string]: any
  }
  // Optional bind-specific options
  bindOptions?: {
    // Propagation mode for bind mounts
    propagation?:
      | "private"
      | "rprivate"
      | "shared"
      | "rshared"
      | "slave"
      | "rslave"
    // Create host path if it doesn't exist
    createHostPath?: boolean
    // Any other bind-specific options
    [key: string]: any
  }
  // Optional tmpfs-specific options
  tmpfsOptions?: {
    // Size of the tmpfs mount in bytes
    size?: number
    // File mode of the tmpfs in octal
    mode?: number
  }
}

/**
 * Socket Configuration
 */
export type SocketConfig = {
  /** Configure what data is automatically sent when a client joins */
  autoSend: {
    /** Send compositions data on join */
    compositions: boolean
    /** Send interaction links data on join */
    interactionLinks: boolean
    /** Send project configuration on join */
    projectConfig: boolean
    /** Additional custom data types to send (must be in the DB and registered via stream) */
    additionalDatatypes: {
      [key: string]: boolean | undefined
    }
    customData?: {
      /** Key is the property name in the response, value is the static data */
      [key: string]: any
    }
  }

  /** Socket security configuration */
  security: {
    /** Whether authentication is required for socket connections */
    requireAuth: boolean
    /** Token validation method */
    tokenValidation: "jwt"
    /** Custom validation handler path */
    customValidator?: string
  }

  /** Advanced socket options */
  options: {
    /** Socket.io adapter configuration */
    adapter: "memory" | "redis" | "mongodb"
    /** Connection timeout in milliseconds */
    connectionTimeout: number
    /** Ping interval in milliseconds */
    pingInterval: number
    /** Ping timeout in milliseconds */
    pingTimeout: number
  }
}

/**
 * Raclette Module Definition
 */
export interface RacletteModule {
  name: string
  services?: Record<string, any>
  extendConfig?: (config: RacletteConfig, options: any) => RacletteConfig
  backendExtensions?: {
    plugins?: string[]
    routes?: string[]
  }
  clientExtensions?: {
    components?: string[]
    plugins?: string[]
  }
  hooks?: Record<string, (...args: any[]) => Promise<void>>
}