# Package name follows conventions

- **Pattern:** `ab-002359` (`sdk-package-quality.package-config.package-naming`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002359
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002359)

## Why it matters

Package names on npm are permanent. Publishing `MyUtils` or `helpers` creates a name that cannot be renamed without breaking every downstream install. CamelCase and underscores in package names violate npm naming rules and can trigger resolution issues in some bundlers. Generic unscoped names (`utils`, `lib`, `tools`) are either already taken or so ambiguous that consumers cannot distinguish your package from dozens of identically named ones. A scoped name (`@yourorg/my-utils`) is the only way to guarantee namespace ownership.

## Severity rationale

High because package names are immutable post-publish — a non-compliant or generic name cannot be corrected without abandoning the published identifier and re-publishing under a new name.

## Remediation

Rename the package to lowercase kebab-case and use an npm scope to guarantee uniqueness.

```json
{
  "name": "@yourorg/my-utils"
}
```

Create an npm organization at `npmjs.com/org/create` if you don't have one. After renaming, deprecate the old name with `npm deprecate myOldName 'Moved to @yourorg/my-utils'`. Any `package.json` files referencing the old name in consumer projects will need updates — communicate the migration in a major version bump.

## Detection

- **ID:** `package-naming`
- **Severity:** `high`
- **What to look for:** Count all package.json files. For each, check the `name` field in `package.json`. Verify:
  1. Uses lowercase kebab-case (e.g., `my-package`, not `myPackage` or `My_Package`)
  2. If published under an organization, uses a scope (e.g., `@org/my-package`)
  3. No generic names that will conflict on npm (e.g., `utils`, `helpers`, `lib`)
  4. Name length is reasonable (not excessively long)
  For Python: check `pyproject.toml` `[project]` `name` uses lowercase with hyphens or underscores. For Rust: check `Cargo.toml` `[package]` `name` uses lowercase with hyphens.
- **Pass criteria:** Package name is lowercase kebab-case (or scoped), does not use a generic/reserved name, and is appropriate for the package's purpose — 100% of package names must follow npm naming rules (lowercase, no spaces, under 214 characters). Report: "X package.json files checked, all Y have valid names."
- **Fail criteria:** Package name uses camelCase, PascalCase, or underscores in an npm package. OR the name is extremely generic (e.g., `utils`, `tools`, `lib`) without a scope. OR the name contains uppercase characters.
- **Skip (N/A) when:** Never — every publishable package has a name.
- **Detail on fail:** `"Package name 'myAwesomeUtils' uses camelCase. npm convention is lowercase kebab-case: 'my-awesome-utils'. Additionally, consider using a scope (@yourorg/my-awesome-utils) to avoid naming conflicts."`
- **Remediation:** Package names are permanent once published. Following conventions makes your package discoverable and prevents resolution issues.

  ```json
  // Before:
  { "name": "MyUtils" }

  // After:
  { "name": "@myorg/my-utils" }
  ```

  If you're publishing under an organization, create an npm org at npmjs.com/org/create and use the scope prefix. This also avoids name squatting issues.

## External references

- iso-25010 maintainability.modifiability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-002359