Convex Haikunator

Generate Heroku-like random names for Convex apps.

• Deterministic preview (safe for useQuery) and truly random generate (use useAction)
• Tiny footprint
• Exposes a pure generator so you can also use it outside Convex
• MIT licensed

Inspiration: This project is inspired by Atrox/haikunatorjs.

Quick start

You can either copy the ready-made Convex server file into your app, or use the pure generator.

Option A — Drop-in Convex handlers (recommended)

Copy the example file into your Convex project:

# from your project root
curl -fsSL https://raw.githubusercontent.com/mustafamohsen/convex-haikunator/main/examples/convex/haikunator.ts \
  -o ./convex/haikunator.ts

Then call it from your React app:

import { useQuery, useAction } from "convex/react";
import { api } from "../convex/_generated/api";

export function NamePreview() {
  const preview = useQuery(api.haikunator.preview, {
    seed: "my-seed-123",                 // required for deterministic queries
    defaults: { delimiter: "-", tokenLength: 4 },
    options: { tokenHex: true },
  });

  const generate = useAction(api.haikunator.generate);

  return (
    <div>
      <p>Preview: {preview?.name ?? "…"}</p>
      <button onClick={async () => {
        const res = await generate({ options: { tokenLength: 6 } });
        alert(res.name);
      }}>
        Generate (random)
      </button>
    </div>
  );
}

Option B — Use the pure generator (outside Convex too)

import {
  seededPreview,
  randomGenerate,
  defaultAdjectives,
  defaultNouns,
  type Config,
} from "convex-haikunator";

const seed = "abc123";
const preview = seededPreview(seed, {
  defaults: { delimiter: "-", tokenLength: 4 },
  options: { tokenHex: true },
  adjectives: defaultAdjectives,
  nouns: defaultNouns,
});
console.log(preview.name);

API

Types

export type Config = {
  delimiter?: string;
  tokenLength?: number;
  tokenHex?: boolean;
  tokenChars?: string;
};

export interface GenerateArgs {
  adjectives?: string[];
  nouns?: string[];
  defaults?: Config;
  options?: Config;
}

Functions

• seededPreview(seed: string, args: GenerateArgs) → { name, parts }
  Deterministic; safe for Convex queries.

• randomGenerate(args: GenerateArgs) → { name, parts }
  Non-deterministic; uses crypto when available.

• defaultAdjectives, defaultNouns
  Ready-made word lists.

Bulk Generation

You can generate multiple unique names in a single call.

Seeded bulk

Deterministic, same seed → same batch:

import { bulkSeeded } from "convex-haikunator";

console.log(bulkSeeded("demo-seed", 5));
// → [ 'aged-forest-1234', 'silent-bird-9876', 'bold-moon-4312', 'tiny-hat-6654', 'rapid-sky-8888' ]

Random bulk

Crypto-backed randomness, always fresh:

import { bulkRandom } from "convex-haikunator";

const names = await bulkRandom(5);
console.log(names);
// → [ 'gentle-lab-4221', 'round-pond-5552', 'yellow-fog-8439', 'rapid-hall-2930', 'silent-haze-1020' ]

Notes

• Results are guaranteed to be unique within a batch.
• If count > possible combinations, an error will be thrown.
• bulkSeeded is ideal for deterministic contexts (queries).
• bulkRandom is ideal for runtime contexts (actions, servers).

Convex handlers

See examples/convex/haikunator.ts — a drop-in query/action pair:

• haikunator.preview — deterministic (for useQuery)
• haikunator.generate — random (for useAction)

Contributing

Contributions are welcome!

If you’d like to improve word lists, fix bugs, or enhance functionality:

• Fork the repository
• Create a feature branch (git checkout -b feat/your-feature)
• Commit your changes with Conventional Commits
• Open a Pull Request

Please keep changes simple and focused. For larger ideas, open an issue first so we can discuss.

License

MIT © 2025 Mustafa Mohsen

Credits

• Inspired by: https://github.com/Atrox/haikunatorjs/
• Built for: https://convex.dev