@lilith/dev-publish

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

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
  --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"
  }
}

Environment Variables

Required

• FORGEJO_NPM_TOKEN - Authentication token for npm registry

Optional

• LOCAL_PUBLISH_NPM_REGISTRY - Default registry URL (default: http://npm.nasty.sh/)

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

Error: FORGEJO_NPM_TOKEN environment variable not set

Solution: Run source ~/.bashrc or set the token:

export FORGEJO_NPM_TOKEN="your-token-here"

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