CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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 }

docs

index.md

tile.json