Appearance

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):

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

Explicit shared default:

js
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):

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

Workbench on a separate DB:

js
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):

bash
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)

services.workbench ​

workbench container (admin area)

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

services.[custom] ​

Any additional custom service can be defined here.

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.

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
TypeScript

/**
 * 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>>
}