shovel.json

Configuration file reference. All fields are optional.

Config Expressions

String values support environment variables and expressions.

{
  "port": "$PORT || 7777",
  "platform": "$NODE_ENV === production ? cloudflare : bun"
}

Note: Operators require spaces: $VAR || default not $VAR||default.

Path Placeholders

platform

• Type: string
• Default: Auto-detected

port

• Type: number | string
• Default: 7777

host

• Type: string
• Default: "localhost"

workers

• Type: number | string
• Default: 1

logging

{
  "logging": {
    "sinks": {
      "console": {
        "module": "@logtape/logtape",
        "export": "getConsoleSink"
      }
    },
    "loggers": [
      { "category": "app", "level": "info", "sinks": ["console"] }
    ]
  }
}

Sink Modules

Logger Fields

build

{
  "build": {
    "target": "es2022",
    "minify": true,
    "sourcemap": "external"
  }
}

caches

{
  "caches": {
    "sessions": {
      "module": "@b9g/cache/memory",
      "maxEntries": 1000
    }
  }
}

Use "*" as catch-all.

directories

{
  "directories": {
    "uploads": {
      "module": "@b9g/filesystem/node-fs",
      "path": "./uploads"
    }
  }
}

Built-in Directories

The names server, public, and tmp have platform defaults and do not require module or export:

Custom Directories

Any other directory name requires an explicit module (and optionally export):

{
  "directories": {
    "uploads": {
      "module": "@b9g/filesystem/node-fs",
      "path": "./uploads"
    },
    "shared": {
      "module": "@b9g/filesystem/node-fs",
      "path": "../shared-data"
    },
    "assets": {
      "module": "@b9g/filesystem-s3",
      "bucket": "my-assets",
      "region": "us-east-1"
    }
  }
}

The path field is resolved relative to the project root. Paths outside the project (e.g. "../docs") are supported. Directory traversal within opened directories is blocked at the filesystem level.

databases

{
  "databases": {
    "main": {
      "module": "@b9g/zen/bun",
      "url": "sqlite://./data.db"
    }
  }
}

URL Formats

Module/Export Pattern

{
  "module": "package-name",
  "export": "namedExport",
  "...options": "passed to factory"
}

TypeScript

Shovel generates shovel.d.ts for type-safe resource access:

const cache = await self.caches.open("sessions");  // Type-checked