Config File Reference

rill-config.json configures a rill project: entry point, extensions, context schema, host options, and runtime constraints.

Top-Level Fields

A minimal valid config:

{
  "name": "my-project"
}

$schema Field

Include $schema to enable editor autocomplete via JSON Schema:

{
  "$schema": "https://cdn.jsdelivr.net/npm/@rcrsr/rill@latest/schema/rill-config.schema.json",
  "name": "my-project"
}

runtime Field

Specifies a semver range. The rill CLI checks the installed runtime version at startup.

{
  "runtime": ">=0.10.0"
}

If the installed version does not satisfy the range, the CLI exits with an error before execution. See Error Reference for the error code.

main Field

Module Mode

main points to a .rill file. The file executes as a script.

{
  "main": "script.rill"
}

Handler Mode

main uses colon syntax to name a specific exported handler in the file.

{
  "main": "script.rill:handleRequest"
}

The identifier after : must be a closure exported by the script.

extensions Block

extensions.mounts

Maps mount paths to package specifiers. Mount paths are dot-separated segments.

{
  "extensions": {
    "mounts": {
      "myext": "@scope/pkg",
      "myext.tools": "@scope/pkg@^1.0.0",
      "myext.tools.search": "./local/path"
    }
  }
}

Mount path rules: Each segment must match /^[a-zA-Z0-9_-]+$/. Examples: "myext", "myext.tools", "myext.tools.search".

Package specifier formats:

extensions.config

Maps mount paths to config objects passed to each extension at setup time.

{
  "extensions": {
    "mounts": {
      "myext": "@scope/pkg"
    },
    "config": {
      "myext": {
        "apiKey": "${API_KEY}",
        "region": "us-east-1"
      }
    }
  }
}

A key in extensions.config with no matching entry in extensions.mounts is an error. See Error Reference for the orphaned key error code.

Bundle-time restriction: extensions.config is prohibited during rill-agent bundle. Presence throws BundleRestrictionError.

extensions.bindings

Output path for the generated bindings file. Defaults to "bindings/ext.rill".

{
  "extensions": {
    "bindings": "generated/ext.rill"
  }
}

context Block

context defines a typed schema for values injected into scripts at runtime.

context.schema

Declares keys with a { type } entry. Supported types: "string", "number", "bool".

{
  "context": {
    "schema": {
      "userId":  { "type": "string" },
      "retries": { "type": "number" },
      "debug":   { "type": "bool" }
    }
  }
}

context.values

Static values for each key declared in context.schema.

{
  "context": {
    "schema": {
      "userId": { "type": "string" }
    },
    "values": {
      "userId": "${USER_ID}"
    }
  }
}

Bundle-time restriction: The entire context block is prohibited during rill-agent bundle. Presence throws BundleRestrictionError.

context.bindings

Output path for the generated context bindings file. Defaults to "bindings/context.rill".

{
  "context": {
    "bindings": "generated/context.rill"
  }
}

Environment Variable Interpolation

Use ${VAR_NAME} in any string value to reference an environment variable.

{
  "extensions": {
    "config": {
      "myext": {
        "apiKey": "${MYEXT_API_KEY}",
        "endpoint": "${API_ENDPOINT}"
      }
    }
  }
}

Behavior:

The CLI auto-loads a .env file from the project root before resolving variables. Embedded callers (using the host API) must supply pre-resolved env vars. See Error Reference for ConfigEnvError.

host Block

Runtime execution options. All fields are optional.

{
  "host": {
    "timeout": 10000,
    "maxCallStackDepth": 50,
    "setupTimeout": 5000
  }
}

modules Block

Configures module resolver behavior for use: imports. Keys and values depend on the resolver registered by the host.

{
  "modules": {
    "greetings": "./greet.rill",
    "utils": "./utils.rill"
  }
}

Paths are relative to the config file’s directory. See Resolver Registration for resolver-specific options.

Bundle-Time Restrictions

During rill-agent bundle, certain fields are prohibited. The bundler throws BundleRestrictionError if they appear.

These fields contain environment-specific data that must not be baked into a bundle.

Related