Skip to content
Cloudwerk

Configuration

The cloudwerk.config.ts file is the central configuration for your Cloudwerk application.

Basic Configuration

Section titled “Basic Configuration”
// cloudwerk.config.ts
import { defineConfig } from '@cloudwerk/core';


export default defineConfig({
  // Configuration options
});

Options Reference

Section titled “Options Reference”

appDir

Section titled “appDir”

The directory containing your application routes.

export default defineConfig({
  appDir: 'app', // default
});

publicDir

Section titled “publicDir”

The directory for static assets.

export default defineConfig({
  publicDir: 'public', // default
});

outDir

Section titled “outDir”

The output directory for builds.

export default defineConfig({
  outDir: '.cloudwerk', // default
});

dev

Section titled “dev”

Development server configuration.

export default defineConfig({
  dev: {
    port: 8787,        // default
    host: 'localhost', // default
    https: false,      // Enable HTTPS locally
    open: true,        // Open browser on start
  },
});

build

Section titled “build”

Build configuration options.

export default defineConfig({
  build: {
    minify: true,           // Minify output
    sourcemap: true,        // Generate sourcemaps
    treeshake: true,        // Tree shake unused code
    target: 'es2022',       // ES target
    external: [],           // External dependencies
  },
});

database

Section titled “database”

D1 database configuration.

export default defineConfig({
  database: {
    binding: 'DB',          // Wrangler binding name
    migrationsDir: 'migrations', // Migrations directory
  },
});

auth

Section titled “auth”

Authentication configuration.

export default defineConfig({
  auth: {
    session: {
      storage: 'kv',           // 'kv' | 'durable-object'
      namespace: 'SESSIONS',   // KV namespace binding
      maxAge: 60 * 60 * 24 * 7, // 7 days in seconds
      cookie: {
        name: 'session',
        httpOnly: true,
        secure: true,
        sameSite: 'lax',
        path: '/',
        domain: undefined,     // Auto-detect
      },
    },
    providers: {
      github: {
        clientId: process.env.GITHUB_CLIENT_ID,
        clientSecret: process.env.GITHUB_CLIENT_SECRET,
        scopes: ['user:email'],
      },
      google: {
        clientId: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
        scopes: ['email', 'profile'],
      },
    },
  },
});

queues

Section titled “queues”

Queue configuration.

export default defineConfig({
  queues: {
    EMAIL_QUEUE: {
      handler: './workers/email-queue.ts',
    },
    WEBHOOK_QUEUE: {
      handler: './workers/webhook-queue.ts',
    },
  },
});

durableObjects

Section titled “durableObjects”

Durable Objects configuration.

export default defineConfig({
  durableObjects: {
    COUNTER: {
      class: './workers/counter.ts',
      className: 'Counter',
    },
    CHAT_ROOM: {
      class: './workers/chat-room.ts',
      className: 'ChatRoom',
    },
  },
});

triggers

Section titled “triggers”

Cron trigger configuration.

export default defineConfig({
  triggers: {
    handler: './workers/triggers.ts',
  },
});

middleware

Section titled “middleware”

Global middleware configuration.

export default defineConfig({
  middleware: {
    // Apply to all routes
    global: ['./middleware/logging.ts', './middleware/cors.ts'],


    // Apply to specific paths
    paths: {
      '/api/*': ['./middleware/auth.ts'],
      '/admin/*': ['./middleware/admin.ts'],
    },
  },
});

rendering

Section titled “rendering”

Server-side rendering configuration.

export default defineConfig({
  rendering: {
    streaming: true,        // Enable streaming SSR
    renderer: 'hono-jsx',   // 'hono-jsx' | 'react' | 'preact'
  },
});

experimental

Section titled “experimental”

Experimental features.

export default defineConfig({
  experimental: {
    // Enable experimental features
    parallelLoaders: true,
    edgeCaching: true,
  },
});

Full Example

Section titled “Full Example”
// cloudwerk.config.ts
import { defineConfig } from '@cloudwerk/core';


export default defineConfig({
  appDir: 'app',
  publicDir: 'public',
  outDir: '.cloudwerk',


  dev: {
    port: 8787,
    open: true,
  },


  build: {
    minify: true,
    sourcemap: true,
    treeshake: true,
  },


  database: {
    binding: 'DB',
    migrationsDir: 'migrations',
  },


  auth: {
    session: {
      storage: 'kv',
      namespace: 'SESSIONS',
      maxAge: 60 * 60 * 24 * 7,
      cookie: {
        name: 'session',
        httpOnly: true,
        secure: true,
        sameSite: 'lax',
      },
    },
  },


  queues: {
    EMAIL_QUEUE: {
      handler: './workers/email-queue.ts',
    },
  },


  durableObjects: {
    RATE_LIMITER: {
      class: './workers/rate-limiter.ts',
      className: 'RateLimiter',
    },
  },


  triggers: {
    handler: './workers/triggers.ts',
  },


  rendering: {
    streaming: true,
    renderer: 'hono-jsx',
  },
});

TypeScript Support

Section titled “TypeScript Support”

The defineConfig helper provides full TypeScript support:

import { defineConfig, type CloudwerkConfig } from '@cloudwerk/core';


// Full type inference
export default defineConfig({
  // TypeScript will show available options
});


// Or define separately
const config: CloudwerkConfig = {
  appDir: 'app',
};


export default defineConfig(config);

Environment-Specific Config

Section titled “Environment-Specific Config”

Use environment variables for environment-specific configuration:

export default defineConfig({
  build: {
    sourcemap: process.env.NODE_ENV !== 'production',
    minify: process.env.NODE_ENV === 'production',
  },
});

Next Steps

Section titled “Next Steps”