verdaccio-google-cloud

Google Cloud Storage + Datastore storage plugin for Verdaccio.

Uses Google Cloud Storage for package tarballs and metadata, and Cloud Datastore for the registry database (package list, secrets, tokens).

Built with Google Cloud SDK for Node.js (@google-cloud/storage v7, @google-cloud/datastore v10).

Requirements

• Node.js >= 24
• Verdaccio >= 7.x
• Google Cloud Storage Bucket — stores package tarballs and package.json metadata
• Cloud Datastore — stores the registry state (package list, secret, auth tokens)
• Google Cloud Credentials — via service account key file, Workload Identity, Application Default Credentials, or environment variables

IAM Permissions

The plugin requires the following IAM roles or equivalent permissions:

Cloud Storage:

• storage.objects.get
• storage.objects.create
• storage.objects.delete
• storage.objects.list

Cloud Datastore:

• datastore.entities.get
• datastore.entities.create
• datastore.entities.update
• datastore.entities.delete
• datastore.indexes.list

Recommended roles: roles/storage.objectAdmin (for GCS) and roles/datastore.user (for Datastore).

Installation

npm install verdaccio-google-cloud

Configuration

Add to your Verdaccio config.yaml:

store:
  google-cloud:
    bucket: your-gcs-bucket
    projectId: your-gcp-project-id # optional if using Application Default Credentials
    kind: VerdaccioDataStore # optional, Datastore entity kind (default: VerdaccioDataStore)
    keyFilename: /path/to/service-account.json # optional, for local development
    validation: crc32c # optional, file validation method (default: crc32c)
    resumable: true # optional, enable resumable uploads (default: true)

    # Emulator endpoints (optional, for local development)
    apiEndpoint: http://localhost:5050 # custom GCS endpoint (fake-gcs-server)
    datastoreEndpoint: http://localhost:8081 # custom Datastore endpoint (emulator)

Environment variable support

The plugin supports configuration via environment variables. If you omit a config field, the plugin checks for the corresponding environment variable:

| Config field | Environment variable | Description | | ------------- | ----------------------------------- | -------------------------------- | | projectId | GOOGLE_CLOUD_VERDACCIO_PROJECT_ID | Google Cloud project ID | | keyFilename | GOOGLE_CLOUD_VERDACCIO_KEY | Path to service account key file |

Environment variables reference

The following environment variables are used by the Docker image and the plugin:

Google Cloud Storage

| Variable | Required | Description | | ---------------------- | -------- | ------------------------------------------------------------------------ | | GCS_BUCKET | Yes | GCS bucket name for storing packages | | GCS_API_ENDPOINT | No | Custom GCS endpoint URL. Required for fake-gcs-server. Omit for real GCP | | GOOGLE_CLOUD_PROJECT | No | Google Cloud project ID. Default: from Application Default Credentials |

Cloud Datastore

| Variable | Required | Description | | ------------------------- | -------- | -------------------------------------------------------------------------------------- | | DATASTORE_EMULATOR_HOST | No | Datastore emulator host:port. When set, the SDK automatically connects to the emulator | | DATASTORE_ENDPOINT | No | Custom Datastore endpoint URL. Required for the emulator. Omit for real GCP |

Authentication

| Variable | Required | Description | | ----------------------------------- | -------- | ---------------------------------------------------------------------------------- | | GOOGLE_APPLICATION_CREDENTIALS | No | Path to service account key file. Omit to use Workload Identity or metadata server | | GOOGLE_CLOUD_VERDACCIO_PROJECT_ID | No | Project ID override for the plugin | | GOOGLE_CLOUD_VERDACCIO_KEY | No | Key file path override for the plugin |

Debug

| Variable | Required | Description | | -------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | DEBUG | No | Enable debug output. Set to verdaccio:plugin* for all plugin namespaces |

Available debug namespaces:

• verdaccio:plugin:google-cloud — Datastore operations (add, remove, get, tokens, secret)
• verdaccio:plugin:google-cloud:storage — GCS package operations (read, write, create, delete, tarballs)

Custom storage per package scope

packages:
  '@scope/*':
    access: $all
    publish: $all
    storage: 'scoped' # stored under scoped/@scope/pkg/
  '**':
    access: $all
    publish: $all
    proxy: npmjs
    storage: 'public'

Architecture

                   +-----------+
                   | Verdaccio |
                   +-----+-----+
                         |
            +------------+------------+
            |                         |
   GoogleCloudDatabase      GoogleCloudStorageHandler
   (registry state)         (per-package storage)
            |                         |
       Datastore              Google Cloud Storage
   +-----------------+      +------------------+
   | Secret          |      | pkg/package.json |
   | VerdaccioData.. |      | pkg/tarball.tgz  |
   | Token           |      +------------------+
   +-----------------+

GoogleCloudDatabase handles registry operations via Cloud Datastore:

• Package list (add, remove, get)
• Secret management (getSecret, setSecret)
• Auth tokens (saveToken, deleteToken, readTokens)
• Search (search)

GoogleCloudStorageHandler handles per-package operations via Google Cloud Storage:

• Package metadata (readPackage, savePackage, createPackage, deletePackage)
• Tarballs (readTarball, writeTarball)

Datastore entity schema

The plugin uses the following Datastore entity kinds:

| Kind | Key | Properties | Description | | -------------------- | ------------------- | --------------------------------------------- | ------------------- | | Secret | secret | secret | Registry secret key | | VerdaccioDataStore | {packageName} | name | Package entry | | Token | {user}:{tokenKey} | user, key, token, readonly, created | Auth token |

The entity kind for packages is configurable via the kind config option (default: VerdaccioDataStore).

Setting up GCP resources (production)

Create a GCS bucket

gsutil mb -p your-project-id gs://verdaccio-storage

Enable Cloud Datastore

Cloud Datastore is automatically available in any GCP project with Firestore in Datastore mode enabled:

gcloud firestore databases create --type=datastore-mode --location=us-east1

Terraform

resource "google_storage_bucket" "verdaccio" {
  name     = "verdaccio-storage"
  location = "US"
}

resource "google_project_service" "datastore" {
  service = "datastore.googleapis.com"
}

Development

See LOCAL_DEV.md for the full local development guide, including:

• Setup, build, test, and lint commands
• Running Verdaccio + GCS/Datastore emulators via Docker Compose
• Inspecting GCS and Datastore data in emulators
• Debug logging namespaces
• Helm + emulators example for Kubernetes

Scaling & Production Deployment

The plugin is fully stateless and supports horizontal scaling. Run multiple Verdaccio instances behind a load balancer — all instances share the same GCS bucket and Datastore database.

• Helm example — deploy on Kubernetes using the official Verdaccio Helm chart with Workload Identity support

License

MIT