@lilith/dev-publish

Fast local build+publish utility for the @packages workspace. Publishes TypeScript packages with dev versions directly to local Verdaccio (localhost:4874), bypassing Forgejo CI/CD delays during co-development.

Note

: The default registry is now localhost:4874 (local Verdaccio). Use --remote to explicitly publish to npm.black.lan (requires Verdaccio authentication, not Forgejo token).

Installation

cd ~/Code/@packages/@cli/dev-publish
pnpm install
pnpm build

Usage

Basic Usage

# From package directory
cd @config/yaml-config
npx @lilith/dev-publish

# From anywhere
npx @lilith/dev-publish @config/yaml-config

Options

npx @lilith/dev-publish [options] [package-path]

Options:
  -d, --dry-run              Show what would be done without executing
  -s, --skip-build           Skip build step, only publish
  -v, --verbose              Detailed logging
  --registry <url>           Override registry URL
  --local                    Publish to local Verdaccio (localhost:4874) - default
  --remote                   Publish to remote Verdaccio (npm.black.lan) - requires Verdaccio auth
  --skip-version-check       Don't check if version already exists
  -h, --help                 Show help
  --version                  Show version

Examples

# Dry run - see what would happen
npx @lilith/dev-publish --dry-run

# Skip build if already built
npx @lilith/dev-publish --skip-build

# Verbose output for debugging
npx @lilith/dev-publish --verbose

# Custom registry
npx @lilith/dev-publish --registry http://localhost:4873

# Combine options
npx @lilith/dev-publish --dry-run --verbose

How It Works

1. Detects TypeScript package and validates structure
2. Reads package.json metadata and validates
3. Creates dev version: {version}-dev.{timestamp}
4. Transforms workspace:* dependencies to actual versions
5. Builds package using tsc (if not skipped)
6. Publishes to registry with dev version

Dev Version Format

Dev versions follow this pattern:

{base_version}-dev.{timestamp}

Examples:
1.0.0 → 1.0.0-dev.1737713234
2.3.5 → 2.3.5-dev.1737713456

The timestamp ensures each build gets a unique version.

Workspace Dependency Transformation

The utility automatically transforms workspace dependencies:

{
  "dependencies": {
    "@lilith/ui-core": "workspace:*"
  }
}

Becomes:

{
  "dependencies": {
    "@lilith/ui-core": "1.2.3"
  }
}

Configuration

dev-publish supports .env file configuration for persistent settings. Configuration is loaded from multiple locations with the following priority (highest to lowest):

1. CLI flags (always win)
2. Environment variables
3. .env in current directory
4. .env in package directory
5. ~/.config/dev-publish/.env (global config)

.env File Example

# ~/.config/dev-publish/.env (global config)

# Registry URLs
DEV_PUBLISH_REGISTRY=http://localhost:4874/
DEV_PUBLISH_REMOTE_REGISTRY=http://npm.black.lan/

# Authentication (only needed for --remote)
DEV_PUBLISH_AUTH_TOKEN=your-verdaccio-token

# Default flags
DEV_PUBLISH_VERBOSE=false
DEV_PUBLISH_SKIP_BUILD=false
DEV_PUBLISH_SKIP_VERSION_CHECK=false
DEV_PUBLISH_DRY_RUN=false
DEV_PUBLISH_REMOTE=false

Configuration Options

Variable	Description	Default
DEV_PUBLISH_REGISTRY	Default registry URL	http://localhost:4874/
DEV_PUBLISH_REMOTE_REGISTRY	Remote registry URL (for --remote)	http://npm.black.lan/
DEV_PUBLISH_AUTH_TOKEN	Auth token for remote publishing	(none)
DEV_PUBLISH_VERBOSE	Enable verbose logging	false
DEV_PUBLISH_SKIP_BUILD	Skip build step	false
DEV_PUBLISH_SKIP_VERSION_CHECK	Skip version existence check	false
DEV_PUBLISH_DRY_RUN	Dry run mode	false
DEV_PUBLISH_REMOTE	Use remote registry by default	false

Legacy Environment Variables

These are still supported for backwards compatibility:

• LOCAL_PUBLISH_NPM_REGISTRY - Same as DEV_PUBLISH_REGISTRY
• REMOTE_NPM_REGISTRY - Same as DEV_PUBLISH_REMOTE_REGISTRY
• FORGEJO_NPM_TOKEN - Same as DEV_PUBLISH_AUTH_TOKEN

Note

: Local registry (localhost:4874) allows anonymous publishing, so no auth token is needed for normal dev workflow.

Exit Codes

Code	Meaning
0	Success
1	Invalid arguments
2	Package detection failed
3	Metadata validation failed
4	Build failed
5	Publish failed
10	Registry error (auth, network, etc.)

Co-Development Workflow

Scenario: Updating a library while working on a consumer application

1. Make changes to library:

   cd ~/Code/@packages/@config/yaml-config
   # Edit src/index.ts
   

2. Fast publish with dev version (~10 seconds):

   npx @lilith/dev-publish
   # Output: Published @lilith/yaml-config@1.0.12-dev.1737713234
   

3. Update consumer application:

   cd ~/Code/@applications/my-app
   pnpm add @lilith/yaml-config@1.0.12-dev.1737713234
   

4. Test changes immediately (no 2-5 minute wait for CI/CD)

5. Iterate (repeat steps 1-4 as needed)

6. When satisfied, publish stable version:

   cd ~/Code/@packages/@config/yaml-config
   pnpm version patch  # → 1.0.13
   git add . && git commit -m "feat: add new feature"
   git push  # Forgejo publishes stable 1.0.13
   

7. Update consumer to stable version:

   cd ~/Code/@applications/my-app
   pnpm add @lilith/yaml-config@^1.0.13
   

Performance

• TypeScript build+publish: < 15 seconds
• vs Forgejo CI/CD: 2-5 minutes
• Speedup: 10-20x faster iteration

Troubleshooting

Missing Auth Token (only with --remote)

Error: FORGEJO_NPM_TOKEN environment variable not set

This only occurs when using --remote to publish to npm.black.lan.

Solution: Either:

• Use local registry (default): npx @lilith/dev-publish (no auth needed)
• Set up Verdaccio authentication for remote publishing

Note

: The FORGEJO_NPM_TOKEN is a Forgejo access token and does NOT work with Verdaccio's htpasswd/JWT auth system. For remote Verdaccio publishing, you need to create a Verdaccio user with npm adduser --registry http://npm.black.lan/.

Build Failed

Error: Build failed: [TypeScript errors]

Solution: Fix TypeScript errors and try again. Use --verbose for detailed output.

Package Not Found

Error: No package.json found at: /path/to/package

Solution: Verify you're in the correct directory or provide the correct path.

See Also

• PROTOCOL.md - Shared specification for API parity with Python version
• Python version - lilith-dev-publish

License

MIT