Documentation menu

Flog documentation

Flog is a predictable JavaScript package manager for individual packages and multi-package workspaces. It uses npm-compatible package.json manifests and registries, but makes dependency resolution, installation, builds, and publication separate, reviewable steps.

Start here#

Install Flog, then install an existing project's committed dependency graph:

curl -fsSL https://flog.run/install | sh
flog install

flog install never resolves newer versions or rewrites flog.lock. The same command is suitable for development and CI: it validates the current manifests and platform against the lock, then materializes that exact graph.

For a fresh project whose current directory has no package.json, initialize the manifest, lock, and installed graph together:

flog init

flog init creates a minimal module manifest named after the current directory, then runs the normal flog lock and flog install behavior. It leaves an existing package.json untouched. Commit flog.lock after reviewing it. Later dependency changes should use flog add, flog remove, or flog upgrade; each command makes the requested manifest and lock changes deliberate. See the command reference for the complete public CLI.

Packages and workspaces#

A package is a directory with a package.json. A workspace is a package rooted at a package.json whose workspaces field selects other packages:

{
  "name": "example",
  "private": true,
  "workspaces": ["apps/*", "packages/*"]
}

Flog builds one deterministic dependency graph from the root and selected workspace packages. Local workspace: dependencies stay local, and selectors can identify workspaces by name, path, owned file, or glob. The package and workspace model documents discovery, specifiers, graph ordering, and validation.

Lock first, install exactly#

flog lock is the network-aware resolution operation. It records exact package versions, integrity, dependency edges, workspace links, and supported targets in flog.lock. Plain flog install is intentionally strict: a missing or stale lock fails instead of being silently repaired.

This split keeps reviews meaningful and makes an accepted lock reusable in local development, CI, and offline installs. Read dependency installation for cache, lifecycle, production, and activation behavior, and resolution and flog.lock for the lock format and target model.

Scripts and builds#

Run a package script with its arguments:

flog run test -- --watch

For workspace source builds, use the graph-aware build command. From the root it builds required workspace dependencies before the selected application:

flog install
flog build --workspace apps/website

Use scripts and binaries for recursive script selection and local executables, or workspace builds for build graph behavior and parallel reporting.

Where to go next#

  • Browse the command reference when you know the operation you need.
  • Use the workflow guides for dependency changes, peer audits, packing, and publishing.
  • Use the operations guides for Flog releases, installer channels, and the flog.run website; these are maintainer procedures rather than everyday package-management steps.