← back

*Building a custom React UI library with Verdaccio

December 27, 2025 · 6 min read

At SoftTech Engineers, as our React architecture scaled, we faced a classic challenge: sharing standardized UI components across multiple distinct web properties. Publishing on public npm registry was not an option for internal core libraries, and configuring local monorepos became messy.

We built a custom React UI design system and hosted it privately using Verdaccio. It is a lightweight, zero-config, self-hosted npm registry that works out of the box. Here is a walkthrough of how to spin up Verdaccio, pack your library, and configure consumers to securely draw from it.

Step 1: Spinning up Verdaccio

Verdaccio is node-based and can be installed globally via npm, but the cleanest deployment path is Docker. Running it inside a container keeps registries isolated and deployments reproducible.

# Pull and run Verdaccio locally on port 4873
docker run -it --detach --name local-verdaccio -p 4873:4873 verdaccio/verdaccio

Once spun up, navigating to http://localhost:4873 serves a clean dashboard showing your published packages.

Step 2: Preparing your UI package

For a library to distribute correctly, it should bundle into standard formats (esm/cjs) with types included. Configure your library's package.json file to declare entry points and direct npm to target your local server during publishing:

{
  "name": "@myorg/ui-library",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "publishConfig": {
    "registry": "http://localhost:4873"
  },
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0"
  }
}

Step 3: Registering users and publishing

To lock packages down, Verdaccio secures publishes using standard registry credentials. Add an admin account to your local registry using npm command endpoints:

# Add registry credentials locally
npm adduser --registry http://localhost:4873

# Pack assets and publish
npm run build
npm publish

Step 4: Consuming private packages

To let consumer apps pull the package without breaking standard npm registries, configure a scoped registry inside a local project root .npmrc file:

# Scopes your local library requests to the private registry
@myorg:registry=http://localhost:4873/

Now, when a developer runs npm install @myorg/ui-library, npm resolves standard public packages through the default npm registry, and routes scoped organization packages dynamically to your custom Verdaccio registry.

Wrapping Up

Setting up private packages doesn't require expensive enterprise registry subscriptions or complex monorepo tooling. Verdaccio lets you securely publish, version, and share react elements in minutes.