pkg.vc

A CLI tool for publishing npm packages to pkg.vc for preview, testing, and sharing.

Overview

pkg.vc allows you to easily share and preview npm packages without publishing them to the npm registry. It's ideal for testing packages in pull requests, sharing modules with teammates, or previewing changes before official releases.

Installation

# Install globally
npm install -g pkg.vc

# Or use with npx
npx pkg.vc publish [options]

Usage

Authentication

Before publishing packages, you need to authenticate with your organization's API key using the auth command:

# Store your API key for an organization
pkg.vc auth myorg your_api_key_here

# List stored organizations
pkg.vc auth --list

# View stored key for an organization (masked)
pkg.vc auth myorg

# Remove stored API key
pkg.vc auth myorg --remove

Publishing Packages

Once authenticated, you can publish packages using the publish command:

# Publish using stored credentials
pkg.vc publish --organization myorg [path]

Commands

• auth <organization> <api-key>: Store API key for an organization
• auth --list: List all stored organizations
• auth <organization>: View stored API key (masked)
• auth <organization> --remove: Remove stored API key
• publish --organization <org> [path]: Publish package to pkg.vc

Options

• --organization: Your organization name (required for publishing)
• --list, -l: List stored organizations (auth command)
• --remove, -r: Remove stored API key (auth command)
• path: Path to your package directory (defaults to current directory)

Environment Variables (Optional)

• PKG_VC_SECRET: Your API key for publishing (overrides stored credentials)

Examples

# Store API key once
pkg.vc auth myorg your_secret_key

# Publish using stored credentials
pkg.vc publish --organization myorg ./my-package

# Override with environment variable (backward compatibility)
PKG_VC_SECRET=your_secret pkg.vc publish --organization myorg ./my-package

# List all stored organizations
pkg.vc auth --list

# Remove stored credentials
pkg.vc auth myorg --remove

After successful publishing, the CLI will display a URL that can be used to install your package.

GitHub Actions Integration

You can automatically publish your package on pull requests using the provided GitHub Action.

name: Publish to pkg.vc

on:
  pull_request:

permissions:
  pull-requests: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Publish to pkg.vc
        uses: pkg-vc/publish-action@main
        with:
          organization: your-organization
          directory: ./path-to-package
          secret: ${{ secrets.PKG_VC_SECRET }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

Using Published Packages

After publishing, you'll receive a URL that can be used to install your package:

# With npm
npm install https://pkg.vc/-/your-organization/package-name@commit-hash

# With yarn
yarn add https://pkg.vc/-/your-organization/package-name@commit-hash

# With pnpm
pnpm add https://pkg.vc/-/your-organization/package-name@commit-hash

How It Works

The tool:

1. Detects your package manager (npm, yarn, pnpm)
2. Packs your module using npm pack
3. Uploads the package to pkg.vc using your API key
4. Returns a URL that can be used to install the package

For versioning, the tool automatically detects the environment and uses the appropriate commit hash:

• In GitHub Actions: Uses the commit SHA of the branch being built
• In GitLab CI: Uses the commit short SHA
• In a Git repository: Uses the current commit's short SHA
• Fallback: Uses the current timestamp if no commit information is available

License

ISC - Created by Torsten Dittmann