morsel

Appearance

morselCome for the lean. Stay for the watch.

The only zero-dep config loader that does discovery, hierarchical merge, live-reload, and plugins.

Quick Start
Reference
morsel logo

Interactive Playground

Edit the base or local configuration files to see hierarchical merging and live events in real-time.

morsel
Live
~/config/your-app/your-app.jsonBase Config
./your-app.jsonLocal Config
Events0 events
Your Merged Config

Lean & Zero-dep

JSON parsing and native file watching packed into less than 8 KB gzipped. No transitive dependencies.

Reactive

store.on('database.port', callback) — listen to specific keys using dotted notation, not the entire config object.

Live-reload

watchConfig attaches fs.watch to directories with per-file debouncing and automatic re-merging. The returned Proxy remains stable.

Layered Cascade

defaults → global (~/.config/morsel/) → project (./myapp.config.json) → overrides. Each layer is resolved independently then deep-merged.

Self-healing & Resilience

If fs.watch drops (Linux/Windows OS limits), it polls existsSync every second to re-attach automatically and catch up.

ENOENT-safe

If a config file is deleted mid-watch, morsel retains the last valid state instead of crashing your process.

Recursive Extends

Config files can inherit settings via an extends property. Path resolution relative to parent files, deep-merging, cycle detection.

Type-safe

Pass your schema or interface — defineConfig infers types from your defaults with zero required type assertions.

Lifecycle Hooks

Tap into 8 lifecycle stages (before:defaults, after:project, etc.) to inject dynamic runtime config and declare custom watchPaths.

Installation ​

bash
pnpm add @oclio/morsel
bash
npm install @oclio/morsel
bash
yarn add @oclio/morsel

One-shot load ​

ts
import { defineConfig, loadConfig } from '@oclio/morsel';

const myApp = defineConfig({
  name: 'myapp',
  defaults: { port: 3000, host: 'localhost' },
});

const { config } = await loadConfig(myApp);
console.log(config.port); // 3000, or overridden by ./myapp.config.json

Live-reload with key-level events ​

ts
import { defineConfig, watchConfig } from '@oclio/morsel';

const myApp = defineConfig({
  name: 'myapp',
  defaults: { port: 3000, host: 'localhost' },
});

const store = await watchConfig(myApp);

store.on('port', (next, prev) => {
  console.log(`port: ${prev} → ${next}`);
});

// Edit ./myapp.config.json → the event fires automatically

store.stop();