### Scoped Package Install Example

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Example of a scoped package installation triggered by a publish event, updating a specific package version in the consumer's package.json.

```bash
npm install @clerk/backend@0.0.0-pkglab.1707500000000
```

--------------------------------

### Install Pkglab Globally

Source: https://github.com/clerk/pkglab/blob/main/README.md

Install the Pkglab binaries globally on your system.

```bash
# Globally install the binaries
npm install -g pkglab
```

--------------------------------

### Start Local Registry

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Starts the local pkglab registry service. This is the first step in the publishing workflow.

```bash
pkglab up
```

--------------------------------

### Bun Workspace Catalog Example

Source: https://github.com/clerk/pkglab/blob/main/README.md

Example of a catalog configuration for Bun workspaces, typically found in the root package.json.

```json
{
  "catalog": {
    "@clerk/backend": "^3.0.0",
    "@clerk/shared": "^2.0.0"
  }
}
```

--------------------------------

### Run Pkglab Registry Benchmark

Source: https://github.com/clerk/pkglab/blob/main/README.md

Execute the benchmark suite for the Pkglab registry server. Ensure you have Bun installed and the project cloned.

```bash
bun run benchmarks/registry-benchmark.ts
```

--------------------------------

### Install Pkglab Package

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Installs a pkglab package into a consumer repository. This command should be run from within the consumer repository's directory.

```bash
pkglab add <pkg>
```

--------------------------------

### Install pkglab packages

Source: https://github.com/clerk/pkglab/blob/main/README.md

Installs pkglab packages into the current repository. Supports batch installs, automatic catalog detection, and workspace scanning. Can pin to specific tags or apply a tag to all packages.

```bash
pkglab add [name[@tag]...]
```

```bash
pkglab add @clerk/pkg@feat1
```

```bash
pkglab add pkg --tag feat1
```

```bash
pkglab add --scope clerk
```

```bash
pkglab add --scope @clerk
```

```bash
pkglab add -p apps/dashboard
```

```bash
pkglab add --dry-run
```

```bash
pkglab add -v
```

--------------------------------

### pnpm Workspace Catalog Example

Source: https://github.com/clerk/pkglab/blob/main/README.md

Example of a catalog configuration for pnpm workspaces, typically found in pnpm-workspace.yaml.

```yaml
catalog:
  '@clerk/backend': '^3.0.0'
  '@clerk/shared': '^2.0.0'
```

--------------------------------

### Example Cascade Publish Scenarios

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Illustrates the cascade publish algorithm for different package changes within a dependency chain. Shows which packages are affected and the timestamp assigned for each publish.

```text
Change in shared:
  reverse deps: backend, nextjs, react
  closure + forward deps: shared, backend, react, nextjs
  publish all with timestamp 1707500000000

Change in backend:
  reverse deps: nextjs
  closure + forward deps: shared, backend, nextjs
  publish all with timestamp 1707500000001

Change in nextjs:
  no reverse deps
  closure + forward deps: shared, backend, nextjs
  publish all with timestamp 1707500000002
```

--------------------------------

### Install Pkglab Globally

Source: https://github.com/clerk/pkglab/blob/main/README.md

Installs the pkglab command-line tool globally using npm. This provides a native binary that does not require a Node.js or Bun runtime to execute, though npm is used for distribution.

```bash
npm install -g pkglab
```

--------------------------------

### Automate Publishing with Dev Server

Source: https://github.com/clerk/pkglab/blob/main/README.md

Wire `pkglab pub --ping` into your dev server's success hook for automatic publishing on rebuilds. This example uses pnpm's `--onSuccess` hook.

```bash
# Watch builds with auto-publish on each successful rebuild
pnpm dev -- --onSuccess 'pkglab pub --ping'
```

--------------------------------

### Automate Publishing with Turbo Build Runner

Source: https://github.com/clerk/pkglab/blob/main/README.md

Integrate `pkglab pub --ping` into your build runner's completion hook for automatic publishing after every rebuild. This example uses turbo's `--on-complete` hook.

```bash
turbo dev --on-complete 'pkglab pub --ping'
```

--------------------------------

### Configure pkglab check in Lefthook

Source: https://github.com/clerk/pkglab/blob/main/README.md

Example configuration to integrate 'pkglab check' into Lefthook's pre-commit hooks.

```yaml
# lefthook.yml
pre-commit:
  commands:
    pkglab-check:
      run: npx pkglab check

```

--------------------------------

### Workspace Structure Example

Source: https://github.com/clerk/pkglab/blob/main/TRADEOFFS.md

Illustrates a typical workspace dependency structure involving shared and specific packages. This context is crucial for understanding the cascade's scope.

```text
@clerk/shared
  ├── @clerk/backend ── @clerk/nextjs
  ├── @clerk/react ──── @clerk/nextjs
  ├── @clerk/express
  └── @clerk/remix
```

--------------------------------

### Pkglab CLI: Daemon Management

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Commands to start, stop, and check the status of the Verdaccio daemon.

```bash
pkglab up                        start Verdaccio daemon
pkglab down                      stop Verdaccio
pkglab status                    server info, active repos, published packages
```

--------------------------------

### Diagnose setup issues

Source: https://github.com/clerk/pkglab/blob/main/README.md

Diagnoses setup issues including directory structure, daemon health, registry connectivity, and .npmrc content. Auto-repairs .npmrc blocks and detects dirty states.

```bash
pkglab doctor
```

```bash
pkglab doctor --lockfile
```

```bash
pkglab doctor --prune
```

--------------------------------

### Add Package with Tag

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Installs a pkglab package into a consumer repository, pinning it to a specific tag. This ensures consumers receive updates for that particular tag.

```bash
pkglab add pkg@feat1
```

--------------------------------

### Add Packages to Consumer Repo

Source: https://github.com/clerk/pkglab/blob/main/README.md

Install packages from the local registry into a consumer repository. Supports interactive prompts, specific package additions, targeting sub-packages, and scope-based additions.

```bash
# From a consumer repo, install a package from the local registry
# Run from workspace root to auto-update all sub-packages that use it
pkglab add # interactive prompt
pkglab add <name> # specific package
pkglab add <name> -p apps/dashboard # target a single sub-package instead
pkglab add --scope clerk # Or replace all packages of a scope at once
```

--------------------------------

### Monorepo Dependency Structure Example

Source: https://github.com/clerk/pkglab/blob/main/README.md

Illustrates a monorepo dependency graph where pkgD depends on pkgB, which depends on pkgA. This structure is used to explain the two-phase cascade.

```text
pkgA (shared utility)
  ├── pkgB ── pkgD (target)
  └── pkgC
```

--------------------------------

### Pkglab Repo State File Example

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

This YAML file stores the state for a single repository managed by Pkglab. It includes the path, active status, and version information for packages within the repository.

```yaml
# ~/.pkglab/repos/my-app.yaml
path: /Users/nikos/Projects/my-app
active: false
packages:
  '@clerk/backend':
    original: '^4.1.0'
    current: '0.0.0-pkglab.1707500000000'
  '@clerk/shared':
    original: '^4.0.0'
    current: '0.0.0-pkglab.1707500000000'
```

--------------------------------

### Reset Repository State

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Resets a repository to its original state, including restoring versions and running `pm install`. Use `--all` to reset all repositories or `--stale` to remove directories that no longer exist.

```bash
pkglab repo reset [name]
```

```bash
pkglab repo reset --all
```

```bash
pkglab repo reset --stale
```

--------------------------------

### Restore pkglab packages

Source: https://github.com/clerk/pkglab/blob/main/README.md

Restores pkglab packages to their original versions across all targets. Can restore all packages, packages matching a scope, or packages installed with a specific tag.

```bash
pkglab restore <name...>
```

```bash
pkglab restore --all
```

```bash
pkglab restore --scope <scope>
```

```bash
pkglab restore -t <tag>
```

--------------------------------

### Pkglab Publish Update Notification

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Notification displayed after a `pkglab pub` command, indicating which packages were published and which active repositories received updates. It shows the installed package version.

```bash
Published 3 packages (ts: 1707500000000):
  @clerk/shared@0.0.0-pkglab.1707500000000
  @clerk/backend@0.0.0-pkglab.1707500000000
  @clerk/nextjs@0.0.0-pkglab.1707500000000

Updated active repos:
  my-app       npm install @clerk/backend@0.0.0-pkglab.1707500000000 ... done
  test-suite   npm install @clerk/backend@0.0.0-pkglab.1707500000000 ... done
```

--------------------------------

### List Consumer Repositories

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Use this command to view all available consumer repositories managed by pkglab.

```bash
pkglab repo ls
```

--------------------------------

### Activate Repositories

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Activates specified consumer repositories. Accepts multiple repository names or `--all` to activate all. Ensure repositories are in the correct state before activation.

```bash
pkglab repo on [name...]
```

```bash
pkglab repo on --all
```

--------------------------------

### pkglab Architecture Overview

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Illustrates the interaction between publisher repos, the local Verdaccio instance managed by pkglab, and consumer repos. Shows the commands used for publishing and adding packages.

```text
Publisher repo (e.g. Clerk monorepo)
    |
    | pkglab pub @clerk/backend
    v
~/.pkglab/verdaccio/  <-- local Verdaccio instance (127.0.0.1:4873)
    |                    proxies unknown packages to npm
    | pkglab add @clerk/backend
    v
Consumer repo (e.g. test app)
    .npmrc: registry=http://localhost:4873
    package.json: "@clerk/backend": "0.0.0-pkglab.1707500000000"
```

--------------------------------

### Pkglab Up Command Output

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Output from the `pkglab up` command, showing linked repositories and their activation status. Use `pkglab repos activate <name>` to activate specific repositories for the session.

```bash
$pkglab up
pkglab running on http://localhost:4873

Linked repos (all inactive):
  my-app         /Users/nikos/Projects/my-app
  test-suite     /Users/nikos/Projects/test-suite
  demo-store     /Users/nikos/Projects/demo-store

Activate repos: pkglab repos activate <name>
```

--------------------------------

### Adding Packages with Catalog Support

Source: https://github.com/clerk/pkglab/blob/main/README.md

Add packages to consumer repositories that use the `catalog:` protocol. Pkglab automatically updates the catalog source directly.

```bash
# Auto-detects that these packages are in a catalog and updates the catalog source
pkglab add @clerk/backend @clerk/shared

# Use --catalog for strict mode (errors if a package is not in any catalog)
pkglab add --catalog @clerk/backend @clerk/shared

# Restore puts the original catalog versions back
pkglab restore --all
```

--------------------------------

### Pkglab CLI: Repository Management

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Commands for listing, activating, deactivating, and resetting repositories. Includes options to reset a specific repository or all repositories.

```bash
pkglab repos ls                  list linked repos
pkglab repos activate <name>     activate repo for auto-updates
pkglab repos deactivate <name>   deactivate repo
pkglab repos reset <name>        reset specific repo
pkglab repos reset --all         reset all repos
```

--------------------------------

### Pkglab CLI: Package Publishing

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Commands for publishing packages, including options for publishing all packages, publishing from a specific directory, skipping dependency checks, and performing dry runs.

```bash
pkglab pub [@scope/name]         publish package + cascade chain
                               no arg from workspace root: publish all
                               no arg from package dir: publish that package +
cascade
pkglab pub --fast                publish current dist, skip dep checks
pkglab pub --dry-run             show what would be published
```

--------------------------------

### Pkglab Per-Repo Configuration

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Per-repo state files, located under ~/.pkglab/repos/, define the path to the repository, its active status, and package-specific version information.

```yaml
# ~/.pkglab/repos/my-app.yaml
path: /Users/nikos/Projects/my-app
active: false
packages:
  '@clerk/backend':
    original: '^4.1.0'
    current: '0.0.0-pkglab.1707500000000'
```

--------------------------------

### Pkglab CLI: Maintenance and Utility

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Commands for listing packages, pruning old versions, running health checks, viewing logs, and performing pre-commit safety checks.

```bash
pkglab pkgs ls                   list packages in Verdaccio
pkglab prune                     clean old versions
pkglab doctor                    health check (env, registry, daemon, git state)
pkglab logs [-f]                 tail Verdaccio logs
pkglab check                     pre-commit safety check for pkglab artifacts
```

--------------------------------

### List Published Packages

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Lists all packages currently published to the local registry. This command checks if the registry is running.

```bash
pkglab pkg ls
```

--------------------------------

### Activate or deactivate consumer repos

Source: https://github.com/clerk/pkglab/blob/main/README.md

Activates or deactivates consumer repositories. Accepts multiple paths or '--all' to affect every repo. Uses an interactive picker if no name is given.

```bash
pkglab repo on/off [name...]
```

```bash
pkglab repo on --all
```

--------------------------------

### Pkglab CLI: Package Management

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Commands to add or remove packages from the consumer repository, restoring the original version when removing.

```bash
pkglab add @scope/name           add package to consumer repo
pkglab rm @scope/name            remove package, restore original version
```

--------------------------------

### Pkglab Global Configuration

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

The global configuration file, typically located at ~/.pkglab/config.yaml, sets the port for the Verdaccio daemon and the number of old versions to keep.

```yaml
# ~/.pkglab/config.yaml
port: 4873
prune_keep: 3
```

--------------------------------

### Restore Original Package Versions

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Restores packages to their original versions. Use `--all` to restore all packages. This is typically done after development is complete.

```bash
pkglab restore <pkg...>
```

```bash
pkglab restore --all
```

--------------------------------

### Scaffold repo hooks

Source: https://github.com/clerk/pkglab/blob/main/README.md

Scaffolds .pkglab/hooks/ in the current repo with type definitions and hook stubs. Supports .ts, .sh, and extensionless formats for custom scripts at lifecycle moments.

```bash
pkglab hooks init
```

--------------------------------

### Publish with Tags

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Publishes workspace packages using a specific tag for version channels, useful for multi-worktree workflows. Auto-detects tags from branches with `-w`.

```bash
pkglab pub -t feat1
```

```bash
pkglab pub -w
```

--------------------------------

### Restore Original Package Versions

Source: https://github.com/clerk/pkglab/blob/main/README.md

When finished, restore original package versions in the consumer repository. Supports restoring single, multiple, or all packages.

```bash
# When done, restore original versions
pkglab restore @clerk/backend                # one package
pkglab restore @clerk/backend @clerk/shared  # multiple packages
pkglab restore --all                         # everything in this repo
```

--------------------------------

### Publishing from Git Worktrees

Source: https://github.com/clerk/pkglab/blob/main/README.md

Publish packages from different Git worktrees using unique tags to avoid version conflicts. Consumer repositories can pin to specific tags.

```bash
# From the main worktree
pkglab pub

# From a feature worktree
pkglab pub --tag feat-auth
# or auto-detect from branch name
pkglab pub --worktree

# Consumer repos pin to a specific tag
pkglab add @clerk/pkg@feat-auth
# or use --tag to apply a tag to all packages at once
pkglab add @clerk/pkg --tag feat-auth

# Replace all packages of a scope with their local versions
pkglab add --scope clerk --tag feat-auth

# Or use the interactive picker to browse packages and tags
pkglab add
```

--------------------------------

### Stop the Registry

Source: https://github.com/clerk/pkglab/blob/main/README.md

Stop the local Pkglab registry server.

```bash
# Stop the registry
pkglab down
```

--------------------------------

### Scenario 1: Editing Upstream Dependency (pkgA)

Source: https://github.com/clerk/pkglab/blob/main/README.md

When an upstream dependency like pkgA changes, the cascade propagates the new version to its dependents (pkgB, pkgC, pkgD) to maintain consistency.

```text
pkgA (shared utility)    ← changed
  ├── pkgB ── pkgD       ← propagated, propagated
  └── pkgC               ← pulled in as dependent of pkgA
```

--------------------------------

### Publish Workspace Packages

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Publishes packages from the library repository to the local registry. This command is used after making changes to library packages.

```bash
pkglab pub
```

--------------------------------

### Run pre-commit safety check

Source: https://github.com/clerk/pkglab/blob/main/README.md

Performs a pre-commit safety check for pkglab artifacts in package.json and .npmrc, and scans staged lockfiles for localhost registry URLs. Returns exit code 1 if issues are found.

```bash
pkglab check
```

--------------------------------

### Re-publish Changes

Source: https://github.com/clerk/pkglab/blob/main/README.md

Make changes to your library and re-publish. Pkglab fingerprints packages to skip unchanged ones and cascades through dependencies and dependents. Active consumer repos update automatically.

```bash
# Make changes to the library, then re-publish
# Fingerprints each package, skips unchanged ones, cascades through deps and dependents
# Active consumer repos update automatically (see Design decisions for details)
pkglab pub
```

--------------------------------

### Configure Global Registry Override (.npmrc)

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

Sets a global registry override in the consumer's .npmrc file to redirect package resolution through Verdaccio. This configuration is applied by `pkglab add`.

```ini
# pkglab-start
registry=http://localhost:4873
# pkglab-end
```

--------------------------------

### Manage Consumer Repository Updates

Source: https://github.com/clerk/pkglab/blob/main/README.md

Control which consumer repositories receive automatic updates. Supports interactive selection or specifying a path.

```bash
# Manage which consumer repos receive auto-updates
pkglab repo on              # interactive picker
pkglab repo on <path>       # specific repo
pkglab repo off             # interactive picker
```

--------------------------------

### Pkglab Version Format

Source: https://github.com/clerk/pkglab/blob/main/README.md

Pkglab generates versions in a specific format for untagged and tagged releases. The timestamp ensures monotonic increments, and the prefix helps identify pkglab-generated versions.

```text
0.0.0-pkglab.{timestamp} (untagged)
0.0.0-pkglab-{tag}.{timestamp} (tagged)
```

--------------------------------

### Pkglab Notice on First Add

Source: https://github.com/clerk/pkglab/blob/main/docs/design.md

A notice displayed by pkglab on the first `pkglab add` in a repository, informing the user about .npmrc changes and the injected pre-commit hook.

```text
notice: pkglab added registry entries to .npmrc
These entries point to localhost and will break CI if committed.
A pre-commit hook (pkglab check) has been injected to catch this.
Run pkglab restore --all to restore your .npmrc.
```

--------------------------------

### Wipe all pkglab data

Source: https://github.com/clerk/pkglab/blob/main/README.md

Wipes all pkglab data and registry storage, stopping the daemon if running.

```bash
pkglab reset --hard
```

--------------------------------

### Scenario 2: Editing Target Dependency (pkgB or pkgD)

Source: https://github.com/clerk/pkglab/blob/main/README.md

If an upstream dependency (pkgA) is unchanged, but a downstream package (pkgB or pkgD) changes, the cascade remains narrow, only updating the changed packages and their direct dependents.

```text
pkgA (shared utility)    ← unchanged, skipped
  ├── pkgB ── pkgD       ← changed (you edited pkgB or pkgD)
  └── pkgC               ← not in scope, stays on old version
```

--------------------------------

### Publish Packages

Source: https://github.com/clerk/pkglab/blob/main/README.md

Publish packages from your library monorepo. Supports publishing all packages, a specific package, or a package with cascading dependencies.

```bash
# Publish packages from your library monorepo
pkglab pub # all (from workspace root), or current (if inside package)
pkglab pub @clerk/backend # specific package and cascade
```

--------------------------------

### Remove Packages from Registry

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Removes specified packages from the local registry. Accepts multiple package names or `--all` to remove all packages.

```bash
pkglab pkg rm <name...>
```

```bash
pkglab pkg rm --all
```

--------------------------------

### Stop Local Registry

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Stops the local pkglab registry service. This is the final step in the publishing workflow.

```bash
pkglab down
```

--------------------------------

### Deactivate Repositories

Source: https://github.com/clerk/pkglab/blob/main/CLAUDE.md

Deactivates specified consumer repositories. Accepts multiple repository names or `--all` to deactivate all. This is useful for managing active development environments.

```bash
pkglab repo off [name...]
```

```bash
pkglab repo off --all
```

--------------------------------

### Clear fingerprint cache

Source: https://github.com/clerk/pkglab/blob/main/README.md

Clears the fingerprint cache. The next 'pub' command will republish all packages regardless of content changes.

```bash
pkglab reset --fingerprints
```

--------------------------------

### Update .env.local with Clerk API URL on Package Add

Source: https://github.com/clerk/pkglab/blob/main/README.md

This TypeScript hook runs after a package is added. It updates the .env.local file to point Clerk SDKs to a local API endpoint. Ensure the payload is correctly parsed from process arguments.

```typescript
// .pkglab/hooks/post-add.ts
import type { PkglabHookPayload } from './payload';
const payload: PkglabHookPayload = JSON.parse(process.argv[2]);

const envFile = Bun.file('.env.local');
const existing = (await envFile.exists()) ? await envFile.text() : '';
const cleaned = existing
  .split('\n')
  .filter(l => !l.startsWith('CLERK_API_URL='))
  .join('\n');
await Bun.write(envFile, cleaned.trimEnd() + '\nCLERK_API_URL=http://localhost:3100\n');
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.