@joggr/config

Configuration SDK for Joggr using c12.

Supports TypeScript, JSON, JSONC, and YAML config files with Zod validation.

Installation

npm install @joggr/config zod

Usage

Joggr Configuration (jog.config.*)

For configuring Joggr CLI and tools, use the global defineConfig helper:

TypeScript

// jog.config.ts
import { defineConfig } from '@joggr/config'

export default defineConfig({
  workspace: {
    copy: ['.env', '.turbo'],
    run: ['pnpm install'],
    command: 'zsh',
  },
})

JSON/JSONC with $schema

// jog.config.json
{
  "$schema": "https://joggr.io/schemas/jog-config.json",
  "workspace": {
    "copy": [".env", ".turbo"],
    "run": ["pnpm install"],
    "command": "zsh"
  }
}

// jog.config.jsonc
{
  "$schema": "https://joggr.io/schemas/jog-config.json",
  "workspace": {
    // Comments supported in JSONC
    "copy": [".env", ".turbo"],
    "run": ["pnpm install"],
    "command": "zsh",
  },
}

YAML with $schema

# jog.config.yaml
$schema: https://joggr.io/schemas/jog-config.json
workspace:
  copy:
    - .env
    - .turbo
  run:
    - pnpm install
  command: zsh

Custom Config Clients

import { createConfigClient } from '@joggr/config'
import { z } from 'zod'

// Define your config schema
const MyConfigSchema = z.object({
  apiKey: z.string(),
  debug: z.boolean().default(false),
  port: z.number().default(3000),
})

// Create a config client
const config = createConfigClient({
  name: 'myapp',
  schema: MyConfigSchema,
})

// Load config
const result = await config.load()
if (result) {
  console.log(result.config.apiKey) // Type-safe!
  console.log(result.filePath) // Path to loaded config
  console.log(result.format) // 'ts' | 'mts' | 'json' | 'jsonc' | 'yaml'
}

Config File Locations

The config client searches for {name}.config.{ts,mts,json,jsonc,yaml} in:

1. Custom paths (if provided via customPaths option)
2. Current working directory (./myapp.config.ts)
3. .joggr/ in CWD (./.joggr/myapp.config.ts)
4. ~/.joggr/ in home directory (~/.joggr/myapp.config.ts)

Supported Formats

TypeScript

// myapp.config.ts
export default {
  apiKey: 'secret',
  debug: true,
}

JSON

// myapp.config.json
{
  "apiKey": "secret",
  "debug": true
}

JSONC (JSON with comments)

// myapp.config.jsonc
{
  "apiKey": "secret",
  // Enable debug mode
  "debug": true,
}

YAML

# myapp.config.yaml
apiKey: secret
debug: true

API

createConfigClient<T>(options)

Create a typed config client.

Options

• name (string): Config file name prefix
• schema (ZodTypeAny): Zod schema for validation
• customPaths? (string[]): Additional search paths (highest priority)
• searchPaths? (string[]): Override default search paths entirely

Returns

Config client with load() method.

config.load(cwd?)

Load and validate config.

Parameters

• cwd? (string): Working directory to search from (default: process.cwd())

Returns

• ConfigResult<T> | null: Config result or null if no file found

Throws

• ConfigValidationError: If validation fails

Global Joggr Config

defineConfig(config)

Type-safe helper for defining Joggr configuration.

import { defineConfig } from '@joggr/config'

export default defineConfig({
  workspace: {
    copy: ['.env'],
    run: ['pnpm install'],
    command: 'zsh',
  },
})

Schema and Types

import { JogConfigSchema, WorkspaceConfigSchema } from '@joggr/config'
import type { JogConfig, WorkspaceConfig } from '@joggr/config'

// JSON Schema also available
import schema from '@joggr/config/schema'

Config Structure

interface JogConfig {
  workspace?: {
    copy?: string[] // Files/directories to copy to new worktrees
    run?: string[] // Commands to run after worktree creation
    command?: string // Command to launch after setup (e.g. 'claude', 'code .', 'zsh')
  }
}

License

MIT