or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-validate-npm-package-name

Validates npm package names according to current and legacy npm registry rules, returning detailed validation results with specific error and warning messages.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/validate-npm-package-name@6.0.x

To install, run

npx @tessl/cli install tessl/npm-validate-npm-package-name@6.0.0

index.mddocs/

validate-npm-package-name

Validates npm package names according to current and legacy npm registry rules, returning detailed validation results with specific error and warning messages. This library helps determine if a string is valid as an npm package name, distinguishing between packages that can be newly published versus those that were valid under older naming rules.

Package Information

  • Package Name: validate-npm-package-name
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install validate-npm-package-name

Core Imports

const validate = require("validate-npm-package-name");

For ES modules:

import validate from "validate-npm-package-name";

Basic Usage

const validate = require("validate-npm-package-name");

// Valid package names
const result1 = validate("some-package");
// { validForNewPackages: true, validForOldPackages: true }

const result2 = validate("@npm/scoped-package");
// { validForNewPackages: true, validForOldPackages: true }

// Invalid package names with errors
const result3 = validate(" leading-space");
// {
//   validForNewPackages: false,
//   validForOldPackages: false,
//   errors: ['name cannot contain leading or trailing spaces', 'name can only contain URL-friendly characters']
// }

// Legacy names with warnings
const result4 = validate("UPPERCASE-NAME");
// {
//   validForNewPackages: false,
//   validForOldPackages: true,
//   warnings: ['name can no longer contain capital letters']
// }

const result5 = validate("crazy!");
// {
//   validForNewPackages: false,
//   validForOldPackages: true,
//   warnings: ['name can no longer contain special characters ("~\'!()*")']
// }

Capabilities

Package Name Validation

The main validation function that checks npm package names against all naming rules.

/**
 * Validates an npm package name according to current and legacy rules
 * @param {any} name - The package name to validate (expected to be string)
 * @returns {ValidationResult} Validation result with validity flags and messages
 */
function validate(name);

Validation Rules:

Error Conditions (invalid for both new and old packages):

  • Name is null, undefined, or not a string
  • Name length is zero
  • Name starts with period (.) or underscore (_)
  • Name contains leading or trailing spaces
  • Name matches reserved names (node_modules, favicon.ico)
  • Name contains non-URL-friendly characters (except valid scoped packages)

Warning Conditions (invalid for new packages, valid for legacy):

  • Name matches Node.js core module names (http, events, etc.)
  • Name length exceeds 214 characters
  • Name contains uppercase letters
  • Name contains special characters: ~, ', !, (, ), *

Special Handling:

  • Scoped packages: Names like @scope/package receive special validation
  • Core modules: Automatically detected using Node.js built-in module list
  • URL safety: Validated using encodeURIComponent comparison

Types

/**
 * Result object returned by the validate function
 */
interface ValidationResult {
  /** True if the name is valid for newly published packages */
  validForNewPackages: boolean;
  /** True if the name is valid under legacy npm naming rules */
  validForOldPackages: boolean;
  /** Array of warning messages for legacy rule violations (omitted if empty) */
  warnings?: string[];
  /** Array of error messages for naming rule violations (omitted if empty) */
  errors?: string[];
}

Usage Examples

Valid Names

const validate = require("validate-npm-package-name");

// Simple package names
validate("lodash");           // { validForNewPackages: true, validForOldPackages: true }
validate("express");          // { validForNewPackages: true, validForOldPackages: true }
validate("my-package");       // { validForNewPackages: true, validForOldPackages: true }
validate("under_score");      // { validForNewPackages: true, validForOldPackages: true }
validate("example.com");      // { validForNewPackages: true, validForOldPackages: true }
validate("123numeric");       // { validForNewPackages: true, validForOldPackages: true }

// Scoped package names
validate("@babel/core");      // { validForNewPackages: true, validForOldPackages: true }
validate("@types/node");      // { validForNewPackages: true, validForOldPackages: true }
validate("@my-org/utils");    // { validForNewPackages: true, validForOldPackages: true }

Invalid Names

// Names that were never valid
validate("");                 // { validForNewPackages: false, validForOldPackages: false, errors: ['name length must be greater than zero'] }
validate(null);               // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot be null'] }
validate(undefined);          // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot be undefined'] }
validate(42);                 // { validForNewPackages: false, validForOldPackages: false, errors: ['name must be a string'] }
validate(".hidden");          // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot start with a period'] }
validate("_private");         // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot start with an underscore'] }
validate(" spaces ");         // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot contain leading or trailing spaces', 'name can only contain URL-friendly characters'] }
validate("node_modules");     // { validForNewPackages: false, validForOldPackages: false, errors: ['node_modules is not a valid package name'] }
validate("favicon.ico");      // { validForNewPackages: false, validForOldPackages: false, errors: ['favicon.ico is not a valid package name'] }

Legacy Names (Warnings)

// Names valid under old rules but not new ones
validate("UPPERCASE");        // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain capital letters'] }
validate("crazy!");           // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain special characters ("~\'!()*")'] }
validate("http");             // { validForNewPackages: false, validForOldPackages: true, warnings: ['http is a core module name'] }

// Very long names (214+ characters)
const longName = "a".repeat(215);
validate(longName);           // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain more than 214 characters'] }

Scoped Package Validation

// Valid scoped packages
validate("@user/package");     // { validForNewPackages: true, validForOldPackages: true }
validate("@org/my-lib");       // { validForNewPackages: true, validForOldPackages: true }

// Scoped packages with legacy warnings
validate("@user/CAPS");        // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain capital letters'] }
validate("@user/special!");    // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain special characters ("~\'!()*")'] }

// Scoped packages with errors
validate("@user/.dotfile");    // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot start with a period'] }

// Note: Scoped packages have relaxed rules - they can contain core module names
validate("@user/http");        // { validForNewPackages: true, validForOldPackages: true }
validate("@user/node_modules"); // { validForNewPackages: true, validForOldPackages: true }