Skip to content

docs(components): align package scopes with published npm names - #645

Open
Ethan-Arrowood wants to merge 1 commit into
mainfrom
docs/package-namespace-audit
Open

docs(components): align package scopes with published npm names#645
Ethan-Arrowood wants to merge 1 commit into
mainfrom
docs/package-namespace-audit

Conversation

@Ethan-Arrowood

Copy link
Copy Markdown
Member

What

The docs referenced @harperdb/* and @harperfast/* inconsistently, reflecting an incomplete HarperDB -> HarperFast transition. I treated npm as the source of truth and audited every first-party package reference against it.

Verified npm state

Re-verified with npm view <pkg> version / npm view <pkg> deprecated at the time of this PR:

package version deprecated verdict
@harperfast/vite 1.1.7 no canonical
@harperfast/vite-plugin 0.2.1 yes - "Renamed to @harperfast/vite - install that instead." replaced by @harperfast/vite
@harperfast/nextjs 2.2.4 no canonical
@harperdb/nextjs 1.2.2 no legacy 1.x line
@harperdb/apollo 1.2.0 no only published scope (@harperfast/apollo 404s)
@harperdb/astro 0.0.2 no only published scope (@harperfast/astro 404s)
@harperdb/status-check 1.0.2 no only published scope
@harperdb/prometheus-exporter 1.1.3 no only published scope
@harperdb/acl-connect 1.0.10 no only published scope

Changes

  • reference/components/overview.md
    • @harperfast/vite-plugin -> @harperfast/vite (the package name is deprecated upstream). This addresses the stale package name half of Add a reference page for the @harperfast/vite plugin (and fix stale package name) #540; the @harperfast/vite reference page itself remains open work there.
    • Repository links for status-check, prometheus-exporter, and acl-connect now point at their current HarperFast/* locations instead of relying on HarperDB/* org redirects.
    • Added a one-line note under Known Custom Components explaining why both scopes appear.
  • learn/developers/harper-applications-in-depth.mdx - the Next.js example now uses @harperfast/nextjs (2.x) rather than the legacy @harperdb/nextjs (1.x).

Left unchanged on purpose: apollo, astro, status-check, prometheus-exporter, and acl-connect keep their @harperdb/* package names, because that is the only scope each is published under. Renaming them in the docs would give readers an install command that fails.

Link verification

I checked every repo link in the touched sections with gh repo view. None 404 - every HarperDB/* URL redirects to the same repo under HarperFast/*, and HarperFast/vite-plugin redirects to HarperFast/vite. I updated the ones in the audited lists to their canonical targets rather than leaving them on redirects.

Notes for the reviewer

  • The issue lists reference/components/extension-api.md as mentioning @harperdb/nextjs. That file no longer contains any package-scope reference, so there was nothing to change there.
  • reference/components/applications.md (lines 124 and 276) uses @harperdb/status-check, which is correct per npm - verified, not changed.
  • Adjacent, not folded into this PR: reference/components/applications.md:125, reference/cli/operations-api-commands.md:207, and reference/fastify-routes/overview.md:15 still use github.com/HarperDB/... URLs in syntax examples. They resolve via redirect, so they are not broken, but they could be refreshed separately.

Verification

  • npm run format:write then npm run format:check - clean.
  • npm run build - succeeds. The two broken-anchor warnings it prints are pre-existing and in files this PR does not touch.

Closes #503

🤖 Generated with Claude Code

Audit every first-party package reference against npm and update the
docs to the name actually published, plus point repository links at the
repos' current HarperFast org locations.

- @harperfast/vite-plugin is deprecated ("Renamed to @harperfast/vite");
  the Known Custom Components entry now lists @harperfast/vite.
- The Next.js plugin reference in the Harper Applications in Depth guide
  now uses @harperfast/nextjs (2.x) instead of the legacy
  @harperdb/nextjs (1.x).
- apollo, astro, status-check, prometheus-exporter, and acl-connect stay
  on @HarperDB, which is the only scope each is published under.
- Add a one-line note under Known Custom Components explaining why both
  scopes appear, so readers seeing both are not confused.

Closes #503

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Ethan-Arrowood
Ethan-Arrowood requested a review from a team as a code owner August 27, 2026 20:36

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates package scopes and repository URLs from @HarperDB to @HarperFast in the documentation to reflect the transition to HarperFast, and adds a clarifying note about the two active npm scopes. Feedback was provided on reference/components/overview.md to replace an em dash with a hyphen as a field separator, adhering to documentation style guidelines.


- [`@harperfast/nextjs`](https://github.com/HarperFast/nextjs) — Run a Next.js application on Harper ([docs](./nextjs.md))
- [`@harperfast/vite-plugin`](https://github.com/HarperFast/vite-plugin) — Develop and serve Vite-built front-ends from Harper, with HMR via `harper run`
- [`@harperfast/vite`](https://github.com/HarperFast/vite) — Develop and serve Vite-built front-ends from Harper, with HMR via `harper run`

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

In Markdown documentation, please use hyphens (-) instead of em dashes () as field separators (e.g., separating package names from their descriptions) to adhere to the style guide.

Suggested change
- [`@harperfast/vite`](https://github.com/HarperFast/vite) Develop and serve Vite-built front-ends from Harper, with HMR via `harper run`
- [@harperfast/vite](https://github.com/HarperFast/vite) - Develop and serve Vite-built front-ends from Harper, with HMR via harper run
References
  1. In Markdown documentation, use hyphens ('-') instead of em dashes ('—') as field separators (e.g., separating configuration option names from their descriptions) to adhere to the style guide, even if the file has pre-existing inconsistencies using em dashes.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not taking this one. The em-dash rule is being over-generalized here.

AGENTS.md says em dashes "are fine for parenthetical asides and match existing prose; do not use them as field separators." The field-separator prohibition refers to the bullet immediately above it - Type: / Default: reference blocks, where each field goes on its own line. It is not a ban on - **term** — description in prose lists.

Two checks: the docs tree has 633 em-dash list-item lines across 63 reference files, and AGENTS.md itself uses this exact pattern - including in the rule being quoted (- **Hyphens vs. dashes** — em dashes...).

So these are the established convention, not "pre-existing inconsistencies." Applying the suggestion would leave the touched lines inconsistent with every sibling line in the same list.

sent with Claude Opus 5

@github-actions

Copy link
Copy Markdown

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-645

This preview will update automatically when you push new commits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Audit @harperdb vs @harperfast package namespace usage

2 participants