# Keywords array for discoverability

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

## 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.

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

## Detection

- **ID:** `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:

  ```json
  {
    "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

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