@haruhimemoe/next-kit

The Next.js server plumbing the haruhime.moe tools share. packs.haruhime.moe and pools.haruhime.moe (in beta) each had their own copy, and the copies had started to drift.

• /server: route helpers. JSON error answers, a JSON body parser with a size cap, a cross-site guard, the client IP, fixed-window rate limits and call budgets in MongoDB, bearer machine auth, where to go after sign-in, and security.txt.
• /env: zod env parsing that runs on first use, with SKIP_ENV_VALIDATION for CI and a guard that refuses placeholder secrets on a production server.
• /mongo: one MongoClient per process with Mongoose on the same client, index builds that never take the site down, and frozen collection names.
• /auth: better-auth with osu! as the only way in, the indexes its collections need, and reading the caller.
• /auth-react: the browser half: the signed-in marker cookie, the account store and useAccount, RestoreSignedIn, and the account components (Sign in with osu!, Sign out, the header's account menu, Delete my account) styled with @haruhimemoe/ui.
• /seo: Next.js metadata that keeps each page's canonical, og:url and preview image together, robots.txt with the AI crawler stance written down, sitemap entries with honest lastmod, schema.org JSON-LD builders, and llms.txt. No runtime imports; all four haruhime.moe sites use it.
• /testing: Vitest helpers: one in-memory MongoDB per run, an msw server that refuses unhandled requests, and a fake env.
• /api-keys: the shared key format (an app prefix like hpk_ plus 32 random bytes), a key store over api_keys, and the /api/v1 guard with the standard limits.
• /docs: a content registry for an app's docs, guides and legal pages: sections, entries, app-made extra entries (like bb's tag pages), the path helpers a dynamic route needs, and mdxToMarkdown to turn bb-flavored MDX into plain Markdown. No runtime imports. /docs/files: reads the markdown files a registry's entries point at and reports drift between the registry and disk (node:fs).
• /legal: the five-page legal convention (terms, privacy, your-privacy-rights, copyright, disclaimers). A LegalSite config, seven plain server-safe blocks (LegalContact, DataWeKeep, Processors, YourRights, DmcaNotice, NoWarranty, Changes) an app drops into its own legal MDX, legalEntries for the app's content registry, and legalMarkdownTransform so those blocks survive mdxToMarkdown's .md mirrors and llms-full.txt instead of being dropped as unknown JSX.
• /vcs: document history in MongoDB on top of @haruhimemoe/vcs: one line of revisions per document, saves merged onto whatever landed since their base, revert, diffs, and autosave pruning.
• /account: account export and delete across every app. The hub fans out to each app with that app's own secret; each app serves two small handlers.
• /inbox: invites and notifications in the shared identity database. The hub stores them; apps write through the hub.
• /i18n: locale lists and Accept-Language negotiation, with no next-intl import. /i18n/next-intl: the request config and locale middleware on top of next-intl (install it first).

Every name, path, limit and message comes from the caller. There is no root entry point; import a subpath.

bun add @haruhimemoe/next-kit zod# or: npm install @haruhimemoe/next-kit zod

zod 4.6.5 or later in 4.x is a peer dependency. The other peers are optional, and each subpath needs only its own:

One file per app wires each piece to its own names.

// src/env.tsimport { createServerEnv, OSU_APP_PLACEHOLDERS, OSU_APP_SECRET_KEYS, osuAppEnvSchema, readIdSet } from "@haruhimemoe/next-kit/env";export const serverEnv = createServerEnv({ schema: osuAppEnvSchema, placeholders: OSU_APP_PLACEHOLDERS, secretKeys: OSU_APP_SECRET_KEYS });export const getServerEnv = serverEnv.get;export const getDatabaseUri = () => serverEnv.pick(process.env, ["MONGODB_URI"]).MONGODB_URI;export const getAdminOsuIds = () => readIdSet("ADMIN_OSU_IDS");// src/lib/db.tsimport { createMongo, ensureIndexes } from "@haruhimemoe/next-kit/mongo";import { AUTH_INDEX_SPECS } from "@haruhimemoe/next-kit/auth";import { counterTtlIndex } from "@haruhimemoe/next-kit/server";export const { getDb, getMongoClient, getModelConnection, connectDb, connectedDb, closeDb } = createMongo({  dbName: "pools",  globalKey: "__poolsMongo",  uri: getDatabaseUri,  onConnect: async ({ db }) => {    await ensureIndexes(db, [...AUTH_INDEX_SPECS, counterTtlIndex()]);  },});// src/lib/rate-limit.tsimport { createRateLimiter } from "@haruhimemoe/next-kit/server";export const limiter = createRateLimiter({ db: connectedDb });

A route handler then reads like this:

import { clientIp, jsonError, parseJsonBody, rateLimitSubject, refuseCrossSite } from "@haruhimemoe/next-kit/server";export async function POST(request: Request) {  const foreign = refuseCrossSite(request, { siteUrl: SITE.url, siteTitle: SITE.title });  if (foreign) return foreign;  const limited = await limiter.refuseOverLimit(RATE_LIMITS.save, rateLimitSubject(clientIp(request.headers)));  if (limited) return limited;  const body = await parseJsonBody(request, saveBodySchema);  if (!body.ok) return body.response;  // ...  return jsonError(404, "Pack not found.");}

Sign-in takes a server file and a client file:

// src/lib/auth.ts (server)import { createOsuAuth, getOsuUser } from "@haruhimemoe/next-kit/auth";export const getAuth = () => {  const env = getServerEnv();  return createOsuAuth({    clientId: env.OSU_CLIENT_ID, clientSecret: env.OSU_CLIENT_SECRET,    baseURL: env.BETTER_AUTH_URL, secret: env.BETTER_AUTH_SECRET,    db: getDb(), client: getMongoClient(),    markerCookie: "pools-signed-in",    hooks: { afterUserCreate: linkNewEditor },  });};// src/lib/account.ts (browser)"use client";import { createAccount, createSignedInMarker } from "@haruhimemoe/next-kit/auth-react";export const marker = createSignedInMarker("pools-signed-in");const kit = createAccount(authClient, marker);export const { store, useAccount, markSignedOut, RestoreSignedIn } = kit;export const { SignInWithOsu, SignOutButton, AccountMenu, DeleteAccountForm } =  createAuthComponents(authClient, kit);// Anywhere, server pages included: only plain data is left to pass.<SignInWithOsu next={next} /><AccountMenu items={[{ href: "/new", label: "Make a pool" }, { href: "/account", label: "Account" }]} /><DeleteAccountForm username={user.username} appName="pools" deletes="This deletes your account and every pool you own. It can't be undone." />

Build the auth instance once (memoize getAuth), and use the same cookie name on both sides.

SEO: one Site per app, then one call per file.

// src/constants/seo.tsimport { HARUHIME_ORG, type Site } from "@haruhimemoe/next-kit/seo";export const SEO_SITE: Site = {  name: "pools",  url: "https://pools.haruhime.moe",  title: "osu! tournament mappool builder",  description: "Build an osu! tournament mappool: search every ranked map under HR or DT, check the content rules, then download it as a pack.",  ogImages: [{ url: "/opengraph-image.png", width: 1200, height: 630, alt: "pools" }],  organization: HARUHIME_ORG,  parent: { name: "haruhime.moe", url: "https://www.haruhime.moe" },};// src/app/layout.tsx: export const metadata = siteMetadata(SEO_SITE);// src/app/page.tsx:   export const metadata = homeMetadata(SEO_SITE);// src/app/search/page.tsxexport const metadata = pageMetadata(SEO_SITE, { path: "/search", title: "Search osu! tournament mappools" });// src/app/robots.tsexport default () => robots(SEO_SITE, { disallow: ["/api/", "/admin"], aiBots: "allow" });// src/app/sitemap.tsexport default async () => sitemapEntries(SEO_SITE, [["/", "/search"], pools.map((p) => ({ path: `/pools/${p.id}`, lastModified: p.contentUpdatedAt }))]);// src/app/page.tsx (render with @haruhimemoe/ui's JsonLd)<JsonLd data={ld.graph(ld.webSite(SEO_SITE, { searchUrlTemplate: "/search?q={search_term_string}" }), ld.webApplication(SEO_SITE, { category: "UtilitiesApplication" }))} />// src/app/llms.txt/route.tsexport const GET = () => textResponse(llmsTxt({ title: "pools.haruhime.moe", summary: SEO_SITE.description, sections }));

One registry per app, built from its docs, guides and legal entries; the crawl helpers and a dynamic route are built on top of it.

// src/constants/content.tsimport { defineContent } from "@haruhimemoe/next-kit/docs";export const CONTENT = defineContent({  docs: [{ slug: "api", title: "API", description: "The /api/v1 reference.", lastUpdated: "2026-10-04" }],  guides: [{ slug: "make-a-pack", title: "Make a pack", description: "Build your first mappool.", lastUpdated: "2026-10-04" }],  legal: [    { slug: "terms", title: "Terms of service", description: "The rules for using pools.", lastUpdated: "2026-10-04" },    { slug: "privacy", title: "Privacy policy", description: "What pools stores and why.", lastUpdated: "2026-10-04" },  ],});// src/app/docs/[slug]/page.tsx (and guides/, legal/, the same shape)import { findEntry } from "@haruhimemoe/next-kit/docs";import { readContentMarkdown } from "@haruhimemoe/next-kit/docs/files";import { CONTENT } from "../../../constants/content";export default async function DocPage({ params }: { params: Promise<{ slug: string }> }) {  const { slug } = await params;  const entry = findEntry(CONTENT, "docs", slug);  if (!entry) return notFound();  const markdown = await readContentMarkdown(CONTENT, "docs", slug, { siteUrl: SEO_SITE.url });  return <Markdown>{markdown}</Markdown>;}// src/app/llms.txt/route.tsimport { contentLlmsTxt } from "@haruhimemoe/next-kit/docs";import { textResponse } from "@haruhimemoe/next-kit/seo";export const GET = () =>  textResponse(contentLlmsTxt({ site: SEO_SITE, title: "pools.haruhime.moe", summary: SEO_SITE.description, content: CONTENT }));// src/app/llms-full.txt/route.tsimport { contentLlmsFull } from "@haruhimemoe/next-kit/docs";import { readContentMarkdown } from "@haruhimemoe/next-kit/docs/files";export const GET = async () =>  textResponse(    await contentLlmsFull({      site: SEO_SITE, title: "pools.haruhime.moe", content: CONTENT,      read: (section, slug) => readContentMarkdown(CONTENT, section, slug, { siteUrl: SEO_SITE.url }),    }),  );// src/app/sitemap.tsimport { contentSitemap } from "@haruhimemoe/next-kit/docs";export default async () => sitemapEntries(SEO_SITE, [["/", "/search"], contentSitemap(CONTENT)]);// next.config.tsimport { contentRewrites } from "@haruhimemoe/next-kit/docs";export default { async rewrites() { return contentRewrites(); } };

next-kit check [dir] walks src/app and, when it exists, content/ (both under dir, default: the current directory) and confirms every standard file exists, so CI catches a missing one before a page does. It checks files only; the content registry itself is never parsed.

bunx next-kit check

Every app is checked against:

• crawl (always): robots.ts, sitemap.ts, llms.txt/route.ts, llms-full.txt/route.ts, and .well-known/security.txt/route.ts (each also accepted as a route handler, like robots.txt/route.ts).
• brand (always): brand/page.tsx.
• legal (always): legal/page.tsx, legal/[x]/page.tsx, legal/[x]/md/route.ts (any dynamic segment name), and the five legal convention pages: content/legal/{terms,privacy,your-privacy-rights,copyright,disclaimers}.mdx.
• docs, once src/app/api/v1 exists or any content/docs file does: docs/page.tsx, docs/[x]/page.tsx, docs/[x]/md/route.ts.
• guides, only once a content/guides file exists: the same three files under guides/. An app with no guides is never asked for them.
• api, once src/app/api/v1 exists: api/v1/me/route.ts, api/v1/openapi.json/route.ts, api/me/api-key/route.ts, and content/docs/api.mdx.

Route groups like (public)/ are ignored, since they don't change the URL. A missing route file prints as missing src/app/<path>; a missing content file prints as missing content/<path>.

The command prints one pass or FAIL line per standard, names each missing file, and exits 1 on a failure (or when src/app is missing). Add it to CI:

- run: bunx next-kit check

Since 0.3.0. Every helper takes the app's Site: name, url (the canonical origin), title (the home page's primary keyword), titleSuffix? (defaults to the host), shortTitleSuffix? (since 0.4.0, like "pools"), description, locale? (en_US), twitter?, ogImages, organization and parent?.

No runtime imports.

node:fs. Markdown source for an entry lives at <root>/content/<section>/<slug>.mdx.

The store's methods:

Notes:

• Run ensureIndexes() (or build revisionIndexSpecs with your own list) before the first write. The unique (docId, seq) index is what stops two writers from both taking the next seq.
• check can run more than once for one commit (retries), so keep it free of side effects.
• A stale autosave that merges is kept as kind merge, like a save; only plain autosaves are pruned.
• A base whose id is another document's revision, or whose seq doesn't match, is missing. Only an id that no longer exists (pruned) falls back to the nearest earlier revision.

Who may read a history, and the routes around it, stay the app's.

Locale negotiation needs nothing. The next-intl glue lives in its own subpath, so an app that doesn't install next-intl never loads or type-checks against it.

bun add next-intl

// i18n/config.tsexport const LOCALES = { locales: ["en", "ja"], defaultLocale: "en" } as const satisfies LocaleConfig;// i18n/request.tsimport { createRequestConfig } from "@haruhimemoe/next-kit/i18n/next-intl";export default createRequestConfig({  config: LOCALES,  app: async (locale) => (await import(`../messages/${locale}.json`)).default,  packages: [async (locale) => (await import(`@haruhimemoe/ui/messages/${locale}.json`)).default],});// proxy.ts (middleware)import { createI18nMiddleware } from "@haruhimemoe/next-kit/i18n/next-intl";export default createI18nMiddleware({ config: LOCALES, cookieDomain: ".haruhime.moe" });export const config = { matcher: ["/((?!api|_next|.*\\..*).*)"] };

• Write each loader as a literal import() so the bundler sees the catalogs.
• The middleware runs in the edge runtime and touches no database. Keep rate limits and session checks in route handlers.
• For hreflang, pass alternates: { languages: hreflangAlternates(LOCALES, path, site.url) } to pageMetadata.

0.12 is the identity core behind the shared hub login: haruhime.moe is the only app that runs osu! sign-in, every other app (bb, packs, pools) reads the hub's session instead of its own. Two modes:

• Single-DB (0.11 apps, unchanged). createMongo({ dbName, ... }) with no identityDbName, createOsuAuth({ ..., markerCookie: "pools-signed-in" }) with no cookieDomain, and getOsuUser/getSessionUser/requireSession over that same instance. Nothing here changes for an app that doesn't opt in, apart from the two breaking changes in the Migration section below (the onConnect signature and the new identity user fields).
• Hub (haruhime.moe).
  ts

  Copy

  // the hub's src/lib/db.tsexport const { getDb, getIdentityDb, connectDb, ... } = createMongo({  dbName: "haruhime",  identityDbName: "identity",  globalKey: "__hubMongo",  uri: getDatabaseUri,  onConnect: async ({ identityDb }) => {    if (identityDb) await buildIdentityIndexes(identityDb);  },});// the hub's src/lib/auth.tsexport const getAuth = () => createOsuAuth({  ...,  db: getIdentityDb(), client: getMongoClient(),  markerCookie: SHARED_MARKER_COOKIE, // "haruhime-signed-in", from auth-react  cookieDomain: ".haruhime.moe",  trustedOrigins: ["https://pools.haruhime.moe", "https://packs.haruhime.moe", "https://bb.haruhime.moe"],});

  Sign-in and the OAuth callback only ever run on the hub, so cookieDomain putting the state and PKCE cookies on .haruhime.moe too is safe. Re-validate a satellite's ?next= with safeAbsoluteNext before redirecting back to it; the hub is the authoritative check even if the satellite built its own hubSignInUrl-style link as a convenience.
• Satellite (bb, packs, pools, after cutover). Keep the app's own createMongo for its own data, but build a reader instead of createOsuAuth:
  ts

  Copy

  export const sessionReader = createSessionReader({  identityDb: getIdentityDb(), // identityDbName: "identity" on this app's own createMongo too  secret: getServerEnv().BETTER_AUTH_SECRET, // shared with the hub  hubUrl: "https://haruhime.moe",});// in a route or server page:const user = await requireSession(sessionReader, request.headers);

  The reader makes zero database writes (it's a raw cookie-and-Mongo read, not a betterAuth() instance), and a satellite's own Atlas user should be readWrite on its own database and read only on identity — app code isn't the boundary, the DB credential is.

Local dev. Production shares a cookie across *.haruhime.moe via cookieDomain: ".haruhime.moe", but localhost subdomains don't share cookies the same way. Run every app under a *.localhost host instead (hub.localhost:3000, pools.localhost:3001, ...) with cookieDomain: ".localhost" on the hub's dev config, or use an lvh.me-style public DNS wildcard that resolves to 127.0.0.1. Either way, leave cookieDomain unset on a plain localhost:3000 setup: a single-origin dev server doesn't need cross-subdomain cookies at all, and better-auth's baseURL check for crossSubDomainCookies requires an actual domain to scope to.

Cutover. Deploy the hub with identity, run next-kit migrate-identity --from bb,packs,pools --to identity (dry run first, then --execute), switch each satellite to createSessionReader, then run --drop-old once every satellite is confirmed working. migrateIdentity also rewrites userId references in an app's own collections when given { collection, field } per app — the CLI doesn't expose that (no sane flag syntax for a per-app list), so call migrateIdentity directly from a one-off script when an app needs it:

import { migrateIdentity } from "@haruhimemoe/next-kit/check/migrate-identity";await migrateIdentity(  [{ id: "packs", db: packsDb, references: [{ collection: "download", field: "userId" }] }],  identityDb,  { dryRun: false },);

The hub lets a signed-in user link one Discord account. It stores only discordId and discordUsername on the identity user: no account row, no Discord token.

Env vars (hub only): DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET. With either unset, every route answers 404 and the account page should hide its Discord row. In the Discord developer portal, add the redirect https://<hub>/api/account/discord/callback.

const discord = createDiscordLinkRoutes({  config: discordLinkConfig(process.env, env.BETTER_AUTH_URL),  identityDb: async () => getIdentityDb(),  secret: env.BETTER_AUTH_SECRET,  currentUser: (req) => getSessionUser(getAuth(), req.headers),});// app/api/account/discord/start/route.ts     export const POST = discord.start;// app/api/account/discord/callback/route.ts  export const GET = discord.callback;// app/api/account/discord/route.ts           export const POST = discord.unlink;

• start is a POST from a form button on the account page, behind the same-site check. A signed-out user goes to /signin?next=<returnPath>.
• callback lands on returnPath (default /account) with ?discord=linked, taken (another user holds that Discord) or error.
• Banned users can't link. One Discord account belongs to one user at most: buildIdentityIndexes adds a unique discordId index.
• Wrap start and callback in your rate limit (10 per IP per 10 minutes is plenty).

A bot looks people up with findUserByDiscordId(identityDb, interaction.user.id), using a database user with read on identity.

A key carries scopes. "*" grants everything, and is what issue(userId) gives and what a key made before 0.13 reads as.

const apiKeys = createApiKeyStore({ prefix: "hpk_", db: getDb, scopes: ["read", "write"] });await apiKeys.issue(user.id, ["read"]); // a read-only key; an undeclared name throws TypeErrorexport const POST = withApiKey(handler, { scope: "write" }); // a read-only key gets 403

The hub owns "Download my data" and "Delete my account". Each app keeps its own data and serves two handlers the hub calls.

Each app gets its own secret (openssl rand -base64 32, at least 32 bytes). The hub holds all of them; each app holds only its own:

In each app:

// app/api/internal/account/[op]/route.tsconst handlers = createAccountHandlers({  secret: () => process.env.ACCOUNT_FANOUT_SECRET,  export: async (userId) => ({ packs: await packsOwnedBy(userId) }),  delete: async (userId) => { await deletePacksOf(userId); await apiKeys.deleteFor(userId); },});export const POST = (req: Request, { params }: { params: Promise<{ op: string }> }) =>  params.then(({ op }) => op === "export" ? handlers.export(req) : op === "delete" ? handlers.delete(req) : new Response(null, { status: 404 }));

On the hub:

const APPS = [  { id: "packs", name: "packs.haruhime.moe", baseUrl: "https://packs.haruhime.moe", secretEnv: "ACCOUNT_SECRET_PACKS" },  // bb, pools] as const;const report = await fanOut({ apps: APPS, op: "delete", userId: user.id, env: process.env });if (report.ok) { /* delete the identity user, its sessions and accounts */ }else { /* keep the user; show which apps failed so they can retry */ }const exported = await fanOut({ apps: APPS, op: "export", userId: user.id, env: process.env });return Response.json(exportBundle(identityRecord, exported.results), {  headers: { "Cache-Control": "no-store", "Content-Disposition": 'attachment; filename="haruhime-data.json"' },});

• Delete only removes the identity user when every app said yes. Delete tries each app three times; export tries once and still returns what it got.
• An app whose secret is unset is skipped and reported not_configured, so delete refuses until it's set.
• Only https:// base URLs are called (http://localhost in dev), and redirects are never followed.
• Put refuseCrossSite and the session check in front of the hub's DELETE /api/account, and the session check in front of GET /api/account/export.
• Delete handlers must be safe to run twice.

Invites and notifications live in the identity database so every app can show them. The hub writes; apps post to the hub with the same secret they use for account fan-out, and read identity directly with their read-only database user.

// hub: app/api/internal/inbox/route.tsconst inbox = createInboxStore(async () => getIdentityDb());export const { post: POST } = createInboxRoutes({ store: inbox, apps: APPS, env: process.env });// an appconst hub = createInboxClient({ hubUrl: process.env.HUB_URL!, secret: process.env.ACCOUNT_FANOUT_SECRET! });await hub.putInvite({ id: invite.id, from: 124493, to: 2, state: "pending", doc: invite });await hub.notify({ userId, kind: "invite", title: "You were invited to a team", href: "/invites" });

• The secret decides which app is writing. A body can't name an app, and an app can't overwrite an invite another app stored (409).
• href is a path or an https:// URL.
• Notifications expire after 90 days. buildIdentityIndexes builds the inbox indexes.
• On account delete, call inbox.deleteFor(userId, osuId).

Both apps can drop their copies for the subpaths above. Where the copies differed, this package keeps pools.haruhime.moe's behavior. What changes for packs.haruhime.moe:

• A 503 answers unavailable, not internal_error.
• parseJsonBody says "That request is too large." and "That request isn't valid." by default (pass tooLarge to keep "That pack is too large."), and sends a refinement's params.code as the error code.
• ?ids= parsing is strict: 1,,2, 5, 0x10 and 1e3 are refused.
• safeNextPath sends /signin as next to the fallback.
• ADMIN_OSU_IDS is read on every call (readIdSet), not memoized with the server env, so a removed admin loses access at the next request.
• Sign-in gains account linking for osu! (a half-deleted account relinks), onAPIError to /signin?error=<code>, and an errorCallbackURL that keeps next (osuSignIn).
• better-auth's collections get their indexes. The first start after the upgrade builds them; existing duplicate users or links are logged and that index is skipped until they're merged.
• The cron guard is async: await refuseWithoutBearer(...).
• deleteRateLimitsFor(userId) becomes limiter.deleteSubject(rules, userId), which escapes the subject instead of requiring an ObjectId.

For pools.haruhime.moe, createMongo runs onConnect (the privilege check, index builds and backfill) after Mongoose is attached; connectDb still rejects when the check fails. Budget counters retry once on a duplicate key, as rate limits already did.

ES modules for Node 22.12+ on the server. auth-react also runs in browsers; its hook and component files keep "use client", and it loads only react, next/navigation.js and @haruhimemoe/ui. server loads node:crypto for machine auth. seo, docs and i18n load nothing at runtime (Next's types only, or nothing), so they run anywhere; docs/files loads node:fs and stays server only.

MIT. See LICENSE.

Questions and feedback are welcome on the haruhime.moe Discord server. Bugs and ideas go in issues.

See CONTRIBUTING.md to work on the package. Changes are logged in CHANGELOG.md. Report a vulnerability as SECURITY.md describes.