npname 📦

Validate npm package names and check availability on the registry

A comprehensive npm package name library that combines validation, availability checking, and registry utilities in one lightweight package.

✨ Features

• 🔍 Validate package names against npm's naming rules
• 🌐 Check availability on npm registry (or custom registries)
• 📦 Batch check multiple package names in parallel
• 🏷️ Parse scoped package names (@scope/name)
• 🔐 Registry auth support (Bearer, Basic, legacy tokens)
• 💡 Suggestions for invalid names (URL-safe alternatives)
• 📝 Full TypeScript support with detailed types
• 💻 Powerful CLI with JSON output, validation mode, and batch checking
• 🖥️ Cross-platform CLI with Unicode/ASCII symbol support (macOS, Linux, Windows)
• 🤖 AI Agent Skill for Claude Code, Cursor, Copilot, and 20+ AI tools

🤖 AI Agent Skill

This package is available as an Agent Skill for AI coding assistants like Claude Code, Cursor, Copilot, and more.

npx skills add dobroslavradosavljevic/npname

Once installed, your AI agent will know how to validate npm package names and check availability on the registry.

📥 Installation

# npm
npm install npname

# yarn
yarn add npname

# pnpm
pnpm add npname

# bun
bun add npname

⚠️ Breaking Change (Named Exports Only)

The default export was removed. Import APIs by name.

// Old (removed)
// import npname from "npname";
// const result = await npname("my-package");

// New
import { checkAvailability } from "npname";

const result = await checkAvailability("my-package");

🚀 Quick Start

import { check, checkAvailability, validate } from "npname";

// Check if a package name is available
const isAvailable = await checkAvailability("my-awesome-package");
console.log(isAvailable); // true or false

// Validate a package name (no network request)
const validation = validate("my-package");
console.log(validation.valid); // true

// Full check: validate + availability
const details = await check("my-package");
console.log(details.available); // true, false, or null

💻 CLI

The package includes a powerful command-line interface.

Installation

# Global installation
npm install -g npname

# Or use with npx
npx npname my-package

Usage

$ npname <name> [names...]

Commands & Options

Option	Description
--validate, -v	Validate only (no network check)
--check, -c	Full check with detailed output
--registry, -r	Custom registry URL
--timeout, -t	Request timeout in ms (positive integer, default: 10000)
--json, -j	Output as JSON for scripting
--quiet, -q	Minimal output (exit codes only)
--concurrency	Parallel requests (positive integer, default: 4)
--help	Show help message
--version	Show version number

Exit Codes

Code	Description
0	All names available/valid
1	Some names unavailable/invalid
2	Invalid arguments or errors

Examples

# Check single package
$ npname my-awesome-package
✔ my-awesome-package available

# Check multiple packages
$ npname react vue angular
✔ react unavailable
✖ vue unavailable
✖ angular unavailable

# Validate without network check
$ npname "My Package" --validate
✖ My Package invalid
  ✖ name can only contain URL-friendly characters
  ⚠ name can no longer contain capital letters
  Suggestions:
    ℹ my-package

# JSON output for scripting
$ npname foo bar --json
[
  {"name": "foo", "available": false, ...},
  {"name": "bar", "available": true, ...}
]

# Custom registry
$ npname @myorg/pkg --registry https://npm.pkg.github.com/

# Quiet mode (for CI/CD)
$ npname my-pkg --quiet && echo "Available!"

📖 API Reference

checkAvailability(name, options?) 🔍

Check if a package name is available on the npm registry.

import { checkAvailability } from "npname";

const available = await checkAvailability("chalk"); // false (taken)
const available = await checkAvailability("my-unique-pkg-xyz"); // true (available)

// With custom registry
const available = await checkAvailability("my-package", {
  registryUrl: "https://registry.mycompany.com/",
  timeout: 5000,
});

Returns: Promise<boolean | null>

---

checkAvailabilityMany(names, options?) 📦

Check availability of multiple package names in parallel.

import { checkAvailabilityMany } from "npname";

const results = await checkAvailabilityMany(["chalk", "lodash", "my-new-pkg"]);

results.get("chalk"); // false
results.get("lodash"); // false
results.get("my-new-pkg"); // true

// With concurrency control
const results = await checkAvailabilityMany(names, { concurrency: 2 });

Returns: Promise<Map<string, boolean | null>>

Throws RangeError if options.concurrency is not a positive integer.

---

validate(name) ✅

Validate a package name without checking the registry.

import { validate } from "npname";

const result = validate("my-package");
// {
//   valid: true,
//   validForNewPackages: true,
//   validForOldPackages: true,
//   errors: [],
//   warnings: []
// }

const result = validate("UPPERCASE");
// {
//   valid: false,
//   validForNewPackages: false,
//   validForOldPackages: true,
//   errors: [],
//   warnings: ['name can no longer contain capital letters'],
//   suggestions: ['uppercase']
// }

const result = validate(".invalid");
// {
//   valid: false,
//   validForNewPackages: false,
//   validForOldPackages: false,
//   errors: ['name cannot start with a period'],
//   warnings: []
// }

Returns: ValidationResult

---

check(name, options?) 🔎

Full check: validates the name and checks availability.

import { check } from "npname";

const result = await check("my-package");
// {
//   name: 'my-package',
//   available: true,
//   validation: { valid: true, ... }
// }

// Invalid name returns error
const result = await check(".invalid");
// {
//   name: '.invalid',
//   available: null,
//   validation: { valid: false, ... },
//   error: InvalidNameError
// }

Returns: Promise<CheckResult>

---

parseName(name) 🏷️

Parse a package name into its components.

import { parseName } from "npname";

parseName("my-package");
// {
//   scope: null,
//   name: 'my-package',
//   full: 'my-package',
//   isScoped: false
// }

parseName("@myorg/my-package");
// {
//   scope: 'myorg',
//   name: 'my-package',
//   full: '@myorg/my-package',
//   isScoped: true
// }

Returns: ParsedName

---

getRegistryUrl(scope?) 🌐

Get the registry URL for a scope (or default registry).

import { getRegistryUrl } from "npname";

getRegistryUrl(); // 'https://registry.npmjs.org/'
getRegistryUrl("@myorg"); // Custom registry if configured in .npmrc

Returns: string

---

getAuthToken(registryUrl) 🔐

Get authentication info for a registry URL.

import { getAuthToken } from "npname";

const auth = getAuthToken("https://registry.npmjs.org/");
// {
//   token: 'npm_xxxx',
//   type: 'Bearer'
// }

Returns: AuthInfo | undefined

---

isScoped(name) 🏷️

Check if a package name is scoped.

import { isScoped } from "npname";

isScoped("@babel/core"); // true
isScoped("lodash"); // false

Returns: boolean

---

isOrganization(name) 🏢

Check if a name is a standalone npm organization (not a scoped package).

import { isOrganization } from "npname";

isOrganization("@babel"); // true
isOrganization("@babel/core"); // false
isOrganization("lodash"); // false

Returns: boolean

📋 Validation Rules

❌ Errors (Invalid for all packages)

Rule	Example	Error Message
Must be a string	null, undefined, 123	name must be a string
Cannot be empty	''	name length must be greater than zero
No leading/trailing spaces	' pkg '	name cannot contain leading or trailing spaces
Cannot start with period	.hidden	name cannot start with a period
Cannot start with underscore	_private	name cannot start with an underscore
Cannot start with hyphen	-pkg	name cannot start with a hyphen
Must be URL-safe	pkg:name	name can only contain URL-friendly characters
Not blacklisted	node_modules	node_modules is not a valid package name

⚠️ Warnings (Invalid for new packages only)

Rule	Example	Warning Message
Max 214 characters	very...long...name	name can no longer contain more than 214 characters
No uppercase	MyPackage	name can no longer contain capital letters
No special chars	pkg!	name can no longer contain special characters ("~'!()*")
Not a core module	fs, http	fs is a core module name

✅ Scoped Package Relaxations

Within a scope (@scope/name), the package name portion can:

• Start with - or _ (e.g., @scope/-pkg, @scope/_pkg)
• Use core module names (e.g., @scope/http)
• Use reserved names (e.g., @scope/node_modules)

🔧 Exports

All public APIs are available as named exports:

import {
  validate,
  check,
  parseName,
  checkAvailability,
  checkAvailabilityMany,
  getRegistryUrl,
  getAuthToken,
  parseNpmrc,
  DEFAULT_REGISTRY,
  InvalidNameError,
  // Utility functions
  isScoped,
  isOrganization,
  expandEnvVars,
  normalizeUrl,
} from "npname";

// Types
import type {
  ValidationResult,
  CheckResult,
  ParsedName,
  AuthInfo,
  AvailabilityOptions,
  BatchOptions,
} from "npname";

⚙️ Options

AvailabilityOptions

interface AvailabilityOptions {
  registryUrl?: string; // Custom registry URL (default: npm registry)
  timeout?: number; // Request timeout in ms (default: 10000)
}

BatchOptions

interface BatchOptions extends AvailabilityOptions {
  concurrency?: number; // Max parallel requests (positive integer, default: 4)
}

🔐 Registry Authentication

The library automatically reads authentication from your .npmrc file:

# Bearer token (recommended)
//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx

# Basic auth
//registry.example.com/:username=myuser
//registry.example.com/:_password=base64encodedpassword

# Legacy auth
_auth=base64encodedusername:password

# Scoped registries
@myorg:registry=https://npm.myorg.com/
//npm.myorg.com/:_authToken=${NPM_TOKEN}

Environment variables are automatically expanded (${VAR} and $VAR syntax).

🌍 Environment Variables

Variable	Description
npm_config_registry	Override default registry URL
NPM_CONFIG_REGISTRY	Override default registry URL (lowercase takes precedence)
NPNAME_ASCII	Set to 1 to force ASCII output symbols (useful on some Windows terminals)

💡 Suggestions

When a package name is invalid, the library provides suggestions:

import { validate } from "npname";

const result = validate("My Package!");
// {
//   valid: false,
//   suggestions: ['my-package']  // URL-safe, lowercase alternative
// }

🚨 Error Handling

import {
  InvalidNameError,
  checkAvailability,
  checkAvailabilityMany,
} from "npname";

try {
  await checkAvailability(".invalid-name");
} catch (error) {
  if (error instanceof InvalidNameError) {
    console.log(error.message); // 'Invalid package name: .invalid-name'
    console.log(error.errors); // ['name cannot start with a period']
    console.log(error.warnings); // []
  }
}

// Batch operations throw AggregateError
try {
  await checkAvailabilityMany([".invalid", "-also-invalid"]);
} catch (error) {
  if (error instanceof AggregateError) {
    console.log(error.errors); // Array of InvalidNameError
  }
}

🤝 Contributing

Contributions from external contributors are welcome and appreciated.

For full details, see CONTRIBUTING.md.

External Contributor Workflow

# 1) Fork this repository on GitHub, then clone your fork
git clone https://github.com/<your-username>/npname.git
cd npname

# 2) Add upstream and create a branch from main
git remote add upstream https://github.com/dobroslavradosavljevic/npname.git
git fetch upstream
git checkout -b feat/my-change upstream/main

# 3) Install dependencies
bun install

# 4) Run quality checks (same as CI)
bun run lint
bun run typecheck
bun run build
bun run test

# 5) Commit using Conventional Commits (required by commitlint)
git commit -m "feat: add better external contributor docs"

# 6) Push branch to your fork and open a PR to main
git push -u origin feat/my-change

Pull Request Checklist

• Keep PRs focused and easy to review
• Add or update tests for behavior changes
• Update docs for user-facing changes
• Ensure all CI checks pass (lint, typecheck, build, test)
• Fill out the PR template with clear description and motivation

📄 License

MIT © Dobroslav Radosavljevic

---

Made with ❤️ for the npm community