Verdaccio In-Memory Authentication Plugin

10.3.2 · active · verified Wed Apr 22

verdaccio-auth-memory is an authentication plugin for Verdaccio, a lightweight private npm proxy registry. It is designed to store user credentials and session data exclusively in runtime memory. This crucial design choice means that all user information, including registered users and active sessions, will be lost upon any restart of the Verdaccio server. The current stable version is 10.3.2. As part of the Verdaccio monorepo, it follows a coordinated release schedule with the main Verdaccio project and other associated plugins. Its primary differentiator is its ephemeral nature, making it explicitly unsuitable for production environments that require persistent user management. Instead, it is primarily intended for development, testing (e.g., unit tests, CI environments), or transient demonstration purposes where data loss on restart is acceptable and even desired for a clean state.

Common errors

```
ERROR: 'auth-memory' plugin is not loaded. Check your Verdaccio configuration.
```
cause The plugin is either not installed, misspelled in `config.yaml`, or another authentication plugin is overriding it.

fix Verify that `verdaccio-auth-memory` is installed (`npm list -g verdaccio-auth-memory`), ensure `auth-memory` is correctly nested under the `auth` section in `config.yaml`, and confirm no other auth plugins (like `htpasswd`) are active that might take precedence.
```
npm ERR! code E401 npm ERR! 401 Unauthorized - http://localhost:4873/-/user/org.couchdb.user:testuser
```
cause Authentication failed, likely due to incorrect username/password or the user not being defined in the `config.yaml`.

fix Double-check the username and password in your `npm login` command against the `users` section in your `config.yaml`. Remember that users must be pre-configured in the YAML for this in-memory plugin.

Warnings

gotcha All user accounts and session data stored by `verdaccio-auth-memory` are non-persistent and will be permanently lost every time the Verdaccio server restarts. This includes user registrations and any changes made during runtime.
Fix: This is by design. For persistent user storage, consider alternative Verdaccio authentication plugins such as `verdaccio-htpasswd`, `verdaccio-ldap`, or database-backed solutions.
gotcha This plugin is explicitly intended for 'unit testing' and development environments. It is not suitable for production use where user data persistence, reliability, or robust security features are required.
Fix: Do not deploy this plugin in production. Use production-ready authentication plugins that integrate with secure, persistent identity providers.
breaking Older Verdaccio versions (pre-v4) or pre-monorepo plugin structures might not be compatible. This plugin's API aligns with modern Verdaccio plugin specifications.
Fix: Ensure your Verdaccio installation is at version 4.x or higher to guarantee compatibility with this plugin's API. Always check the `engines.node` and Verdaccio compatibility matrix.

Install

npm install verdaccio-auth-memory npm
yarn add verdaccio-auth-memory yarn
pnpm add verdaccio-auth-memory pnpm

Imports

AuthMemoryPlugin

wrong:

const AuthMemoryPlugin = require('verdaccio-auth-memory');
// While `require` works, the default export pattern for plugins is typically consumed directly as a function.

correct:

import AuthMemoryPlugin from 'verdaccio-auth-memory';
// In a Verdaccio plugin context, it's typically required and then called.
// import type { IPluginAuth } from '@verdaccio/types';
// const pluginInstance: IPluginAuth = AuthMemoryPlugin(config, appConfig);

The plugin is exported as a default function that takes `config` and `appConfig` as arguments, rather than exporting a class or named functions directly. This is common for Verdaccio plugins. While `require` is shown in the README, modern Node.js (`>=18`) and TypeScript environments prefer `import` for modules that ship types.

IPluginAuth
```
import type { IPluginAuth } from '@verdaccio/types';
```
When developing Verdaccio plugins or working with the plugin's API, you would import the `IPluginAuth` interface from `@verdaccio/types` for type safety, as `verdaccio-auth-memory` implements this interface.

Quickstart

This quickstart demonstrates how to install Verdaccio and the `verdaccio-auth-memory` plugin, then configure a basic `config.yaml` to enable in-memory authentication with predefined users. It then shows how to start Verdaccio and use `npm adduser` to interact with the in-memory registry.

# 1. Install Verdaccio globally (if not already installed)
npm install -g verdaccio

# 2. Install the in-memory authentication plugin
npm install -g verdaccio-auth-memory

# 3. Configure Verdaccio to use the plugin.
#    Create or edit your Verdaccio config.yaml (usually in ~/.config/verdaccio/config.yaml)
#    Ensure you remove or comment out any other 'auth' plugin, like 'htpasswd'.
#    For example, a minimal config.yaml might look like this:

# config.yaml
# ===============================
store:
  memory:
    limit: 1000 # Max number of packages in memory

auth:
  auth-memory:
    users:
      devuser:
        name: devuser
        password: password123
      testuser:
        name: testuser
        password: securepass

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs

  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs
# ===============================

# 4. Start Verdaccio
verdaccio

# Now, you can log in using the configured users:
npm adduser --registry http://localhost:4873
# When prompted, use 'devuser' and 'password123'

view raw JSON →