Provider versions

Each built-in service runs a provider package, such as @deploybaseline/stripe, in its own process. The CLI finds that package before it starts the service, pins the exact version in baseline.lock, and prints where it came from:

  stripe  http://localhost:4009
    Source: stripe
    Provider: @deploybaseline/stripe 0.14.1 (cache)

Where a provider comes from

For each built-in service, the CLI takes the first of these that has a version in range:

Order	Source	Printed as
1	The project’s `node_modules` (`npm install -D @deploybaseline/stripe`)	`project`
2	The exact version `baseline.lock` pins, from the cache or a pull	`cache`, `pull`
3	The newest version in range already in the provider cache	`cache`
4	A pull of the newest version in range from the npm registry	`pull`
5	In a checkout of the Baseline repository only, the workspace package	`workspace`

A pull is a plain registry fetch: the CLI reads the package’s metadata, downloads its tarball, checks the tarball’s SHA-512 integrity, and unpacks it into the cache. No install scripts run and no dependencies are installed, because a provider’s entry is a self-contained bundle. The CLI package itself ships no providers. The first start on a machine downloads each provider it runs and says so once: Pulled @deploybaseline/github 0.14.0, ... into ~/.cache/baseline. Later starts use the cache. Every later start runs them from the cache, even with no network. When the registry cannot be reached and no version in range is cached, start fails for that service and says how to get it: connect once, run npx @deploybaseline/cli pull, or install the provider as a dev dependency.

Pick a version

Each CLI release names a default range for every built-in provider (CLI 0.14.0 runs ^0.14.0 for each), so a CLI picks up compatible releases of its providers without a CLI release. Providers release on their own, so their versions drift apart over time. Set version on a service to choose another range:

{
  "stripe": {
    "version": "^0.14",
    "customers": [
      {
        "email": "[email protected]"
      }
    ]
  }
}

Or under services:

{
  "services": {
    "billing": {
      "emulator": "stripe",
      "version": "0.14.1"
    }
  }
}

version takes an exact version, ^, ~, x wildcards, comparators such as >=0.14.0 <0.16, and ||. It applies to built-in providers only; a custom emulator is your own code.

baseline.lock

With a config file, start writes baseline.lock next to it once every service is running. Commit it: every machine and CI run then starts the same provider versions.

lockfileVersion: 1
providers:
  stripe:
    package: "@deploybaseline/stripe"
    version: 0.14.1
    integrity: sha512-...

start adds a service that is not in the lockfile, and never changes an entry whose version is still in range. A failed start leaves the lockfile alone.
An entry from the project’s node_modules has source: project and no integrity: npm already checked it. In the Baseline repository itself, the workspace package gives source: workspace. A lockfile from an earlier CLI that says source: bundled still reads: the next start pulls that pinned version and records its integrity.
A cached copy that does not match the lockfile’s integrity is pulled again. A registry tarball that does not match is refused.
With no config file there is no lockfile, and the cache and range decide.
A provider: service (a provider package that is not built in) has trusted: true once you have trusted that version. Trust covers that version and integrity only.

Commands

Command	What it does
`npx @deploybaseline/cli pull`	Put every configured provider in the cache and pin it in `baseline.lock`
`npx @deploybaseline/cli update [services...]`	Move providers to the newest version in their range and rewrite `baseline.lock`
`npx @deploybaseline/cli providers`	List cached providers and the projects whose `baseline.lock` uses them (`--json` for scripts)
`npx @deploybaseline/cli prune`	Remove cached providers that no known `baseline.lock` uses (`--dry-run` to preview)
`npx @deploybaseline/cli trust [services...]`	Trust `provider:` services and pin them in `baseline.lock` with `trusted: true`

pull and update take --config and --service like start.

Offline and CI

--offline (or BASELINE_OFFLINE=1) never touches the network: providers come from the project or the cache, and a provider that is in neither fails with a message naming it. Run npx @deploybaseline/cli pull once (or any start with the network) before going offline.

CI: cache the provider cache directory keyed on baseline.lock, run npx @deploybaseline/cli pull, then npx @deploybaseline/cli start --offline.
Docker: run pull during the image build with BASELINE_CACHE_DIR inside the image.
Vendored dependencies: install the providers you use as dev dependencies. They resolve from node_modules with no cache at all.

The cache and the registry

The cache lives in BASELINE_CACHE_DIR, else $XDG_CACHE_HOME/baseline, else ~/.cache/baseline (%LOCALAPPDATA%\baseline on Windows). Registry metadata is reused for an hour, and a registry that could not be reached is left alone for five minutes. Pulls follow npm’s own settings: registry, scoped registries (@acme:registry=), and auth (//host/path/:_authToken=, _auth, username and _password) from the project’s .npmrc, your user .npmrc, and npm_config_* environment variables, with ${VAR} expanded. A token is only ever sent to URLs under the registry it is set for.

The programmatic API

createEmulator resolves its provider the same way, from the current directory, without a lockfile:

import { createEmulator } from "@deploybaseline/cli";

const stripe = await createEmulator({ service: "stripe", version: "^0.14", offline: true });

Getting started

Configuration

Custom emulators

Reference

Provider versions

Where a provider comes from

Pick a version

baseline.lock

Commands

Offline and CI

The cache and the registry

The programmatic API

​Where a provider comes from

​Pick a version

​baseline.lock

​Commands

​Offline and CI

​The cache and the registry

​The programmatic API

Where a provider comes from

Pick a version

baseline.lock

Commands

Offline and CI

The cache and the registry

The programmatic API