Documentation

Everything you need to know about publishing and using packages with pkg.vc

Installation

Install the CLI globally:

npm install -g pkg.vc

Or use it directly with npx:

npx pkg.vc auth <org> <key>
npx pkg.vc publish --organization <org>

CLI Usage

First, authenticate with your organization:

pkg.vc auth YOUR_ORG YOUR_API_KEY

Then publish your package:

pkg.vc publish --organization YOUR_ORG [path]

Auth Commands

  • auth <org> <key>: Store API key
  • auth --list: List stored organizations
  • auth <org>: View stored key (masked)
  • auth <org> --remove: Remove API key

Publish Options

  • --organization: Your organization name (required)
  • path: Path to your package directory (defaults to current directory)

Environment Variables (Optional)

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

Environment variables take precedence over stored API keys for backward compatibility.

Complete Example:

# Store your API key once
pkg.vc auth YOUR_ORG your_secret_key

# Publish your package
pkg.vc publish --organization YOUR_ORG ./my-package

# List stored organizations
pkg.vc auth --list

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

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

GitHub Actions

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

Setup:

Create a file at .github/workflows/pkg-vc.yml with the following content:

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

      # add your build step here if needed

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

Configuration Options

  • organization: Your organization name
  • directory: Path to your package directory
  • secret: Your pkg.vc API key (stored as a GitHub Secret)
  • github-token: GitHub token for posting comments with the package URL to the PR

Setting up the Secret

Add your pkg.vc API key as a repository secret named PKG_VC_SECRET in your GitHub repository (Settings → Secrets and variables → Actions → New repository secret).

Note: GitHub Actions use environment variables for authentication, which take precedence over stored API keys.

Using Published Packages

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

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

Or with other package managers:

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

Using Private Packages

When trying to use a private package, you need to provide an API key. You can add this to your .npmrc file:

//pkg.vc/-/@your-organization/:_authToken=[MY_API_KEY]

Make sure to replace [MY_ORG] and [MY_API_KEY] with your values.