Skip to main content

Keywords array for discoverability

ab-002385 · sdk-package-quality.docs-maintenance.keywords
Severity: infoactive

Why it matters

An empty or missing keywords array in package.json removes the package from npm's keyword-indexed search results, so developers looking for an SDK in your domain will never surface it through the registry's discovery surface. Generic keywords like javascript or node are functionally equivalent to no keywords — they collide with hundreds of thousands of unrelated packages. This failure maps directly to the findability taxon and directly suppresses organic installs, GitHub traffic, and ecosystem integrations that depend on npm search.

Severity rationale

Info because the package still installs and functions correctly; only discovery is degraded, not runtime behavior or security.

Remediation

Add a keywords array to package.json with at least five specific terms that describe the package's domain, protocol, and ecosystem. Avoid generic words like javascript, library, or utility; instead name the service, the transport, the framework, and the problem category so that npm's search ranks the package for relevant queries.

{
  "keywords": [
    "api-client",
    "rest-api",
    "typescript",
    "sdk",
    "your-service-name"
  ]
}

Detection

  • ID: sdk-package-quality.docs-maintenance.keywords

  • Severity: info

  • What to look for: List all keywords in package.json. check package.json for a keywords array. This helps npm search find the package. Verify:

    1. keywords array exists and is non-empty
    2. Keywords are relevant to the package's purpose
    3. Keywords include the primary technology or domain

  • Pass criteria: keywords array exists with at least 3 relevant keywords that describe the package's purpose and domain — at least 3 keywords must be configured for npm discoverability. Report: "X keywords configured."

  • Fail criteria: No keywords field, or keywords is an empty array, or keywords are generic/irrelevant (e.g., ["javascript", "node", "library"] with nothing specific).

  • Skip (N/A) when: The package is scoped to an organization (@org/package) and intended for internal use only (not meant to be discovered via npm search). Also skip for Go and Rust (their registries use different discovery mechanisms).

  • Detail on fail: "No keywords field in package.json. This package will not appear in npm search results for relevant terms. Add keywords like ['api-client', 'rest', 'http', 'typescript'] to improve discoverability."

  • Remediation: Keywords improve discoverability on npm. Include specific terms that someone searching for this type of package would use:

    {
  "keywords": [
    "api-client",
    "rest-api",
    "typescript",
    "sdk",
    "your-service-name"
  ]
}

    Focus on what the package does and what ecosystem it belongs to, not generic terms.

Taxons

findability

History