⚒️ ForgeData

A modern, modular, tree-shakable, zero-runtime-dependency fake data generator for TypeScript and JavaScript.

A production-ready alternative to Faker.js — with React integration and a CLI built in.

Website  ·  Try it live  ·  Docs  ·  npm  ·  GitHub

• 100+ generators across 16 modules (forge.listGenerators() to see every one)
• Zero runtime dependencies
• ESM + CommonJS, one package
• Works in Node.js, Bun, Deno, and browsers — no runtime-specific APIs, only web-standard globals (btoa, crypto-free PRNG)
• 100% typed, every generator has a precise return type
• Tree-shakable — import only the modules/functions you use
• Seedable — deterministic output for tests and snapshots
• 9 built-in locales, plus a custom locale API
• Custom generators via forge.define(...)
• Schema-based generation (@sahinur/forgedata/zod): fake data straight from a Zod schema
• React integration (@sahinur/forgedata/react): a provider + two hooks
• CLI (forgedata): generate fake data from your terminal or scripts
• 100% test coverage (statements/branches/functions/lines)

Table of contents

• Install
• Quick start
• Deterministic output (seeding)
• Locales
• Custom generators
• Unique values
• Helpers & randomness utilities
• Generator introspection
• Zod schema generation
• React integration
• CLI
• Modules
• Runtime support
• Development
• Website
• Publishing
• License

Install

npm install @sahinur/forgedata

Quick start

import { ForgeData } from "@sahinur/forgedata";

const forge = new ForgeData();

forge.person.fullName();          // "Ava Thompson"
forge.internet.email();           // "[email protected]"
forge.location.country();         // "Canada"
forge.finance.creditCardNumber(); // "4539123456781234"
forge.phone.number();             // "+1-555-123-4567"
forge.ai.prompt();                // "Explain quantum computing to a beginner..."

Or use the ready-made default instance for quick scripts:

import { forge } from "@sahinur/forgedata";

console.log(forge.person.fullName());

Deterministic output (seeding)

const forge = new ForgeData({ seed: 42 });
forge.person.fullName(); // always the same value for seed 42

forge.seed(42);          // reseed an existing instance

Seeds accept a number or a string (strings are hashed into a seed), so you can seed with something readable like a test name.

Locales

const forge = new ForgeData({ locale: "ja" });
forge.person.fullName(); // Japanese name pool

forge.locale("fr");      // switch at runtime
forge.locale();          // "fr" — read the current locale

Built-in locales: en, bn (Bangla), hi (Hindi), ar (Arabic), ja (Japanese), fr (French), de (German), es (Spanish), zh (Chinese).

Custom locales

forge.defineLocale({
  code: "pirate",
  name: "Pirate",
  person: {
    firstNamesMale: ["Blackbeard", "Redbeard"],
    firstNamesFemale: ["Anne", "Mary"],
    lastNames: ["Silver", "Flint"],
    jobTitles: ["First Mate"],
    professions: ["Sailor"],
  },
  location: { cities: ["Tortuga"], states: ["Caribbean"], countries: ["Never Land"] },
  company: { suffixes: ["& Co"], catchPhraseAdjectives: ["Salty"], catchPhraseNouns: ["treasure"] },
  lorem: { words: ["arr", "matey", "doubloon"] },
});

forge.locale("pirate");

Custom generators

forge.define("pokemon", (f) => f.pick(["Pikachu", "Bulbasaur", "Charmander"]));

forge.custom.pokemon(); // "Pikachu"

Unique values

forge.unique.email();    // never repeats for this ForgeData instance
forge.unique.username();
forge.unique.uuid();

const uniqueCity = forge.unique.wrap(() => forge.location.city());
uniqueCity();

forge.unique.clear(); // forget everything generated so far

Helpers & randomness utilities

forge.uuid();
forge.shuffle([1, 2, 3]);
forge.pick(["a", "b", "c"]);
forge.pickMultiple(["a", "b", "c", "d"], 2);
forge.randomEnum(MyEnum);
forge.probability(0.3);
forge.weighted([
  { weight: 9, value: "common" },
  { weight: 1, value: "rare" },
]);
forge.randomArray(() => forge.person.fullName(), 5);

Generator introspection

Every module is walked via prototype introspection rather than a hand-maintained registry, so this never drifts from the real API:

forge.listGenerators();
// [{ module: "person", method: "fullName", id: "person.fullName" }, ...]  (100+ entries)

forge.invoke("person", "fullName"); // same as forge.person.fullName()

This is what the CLI is built on.

Zod schema generation

npm install @sahinur/forgedata zod

import { z } from "zod";
import { fromZodSchema } from "@sahinur/forgedata/zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email(),
  age: z.number().int().min(18).max(99),
  role: z.enum(["admin", "user", "guest"]),
  tags: z.array(z.string()).min(1).max(3),
  bio: z.string().max(140).optional(),
});

const user = fromZodSchema(forge, UserSchema);
// fully typed as z.infer<typeof UserSchema> — every field respects the
// schema's constraints: a valid uuid, a real-looking email, age in [18, 99],
// one of the three enum values, 1-3 tags, bio present ~80% of the time.

Supports the full range of Zod v4 schema types recursively: primitives (with format-aware strings — .email(), .url(), .uuid(), .datetime(), .ipv4(), .jwt(), and more — plus .min()/.max()/.length()), object, array, tuple, record, map, set, enum/native enums, literal, union/discriminated union, optional/nullable/default/catch, and recursive schemas via z.lazy() (depth-capped, so a self-referential schema can't blow the stack).

.transform()/.pipe() are run through the schema's real safeParse() after generation, so the output reflects the actual post-transform shape. Arbitrary .refine() predicates aren't evaluated ahead of time — a generated value can occasionally fail one, in which case the raw (pre-refine) value is returned rather than throwing. zod is an optional peer dependency (^4.0.0); the main @sahinur/forgedata entry point never imports it, exactly like the React integration.

React integration

import { ForgeDataProvider, useForgeData, useGenerator } from "@sahinur/forgedata/react";

function App() {
  return (
    <ForgeDataProvider seed={42} locale="en">
      <UserCard />
    </ForgeDataProvider>
  );
}

function UserCard() {
  // Regenerated only when `deps` changes — stable across re-renders otherwise.
  const user = useGenerator(
    (forge) => ({ name: forge.person.fullName(), email: forge.internet.email() }),
    [],
  );
  return <div>{user.name} — {user.email}</div>;
}

useForgeData() works even without a ForgeDataProvider (it falls back to a shared default instance) — wrap your tree in a provider whenever you need a specific seed/locale or per-instance isolation. react is an optional peer dependency; the main @sahinur/forgedata entry point never imports it.

CLI

npx --package=@sahinur/forgedata forgedata list                     # every generator id
npx --package=@sahinur/forgedata forgedata list --module person     # filtered to one module
npx --package=@sahinur/forgedata forgedata generate person.fullName # one value
npx --package=@sahinur/forgedata forgedata generate internet.email --count 5 --seed 42
npx --package=@sahinur/forgedata forgedata generate location.country --locale ja --json

Install it globally (npm install -g @sahinur/forgedata) to just run forgedata ... directly; see the docs site for the full flag reference.

Modules

| Module | Examples | |-------------|----------| | person | firstName(), lastName(), fullName(), gender(), jobTitle(), profession() | | internet | email(), username(), password(), url(), domain(), ipv4(), ipv6(), mac(), userAgent(), jwt(), apiKey(), jwtSecret() | | company | name(), catchPhrase(), logo() | | finance | currency(), amount(), creditCardNumber(), creditCardCVV(), iban(), bitcoinAddress(), ethereumAddress(), cryptoCoin(), stockSymbol() | | location | country(), state(), city(), zipCode(), latitude(), longitude(), timezone(), airport() | | commerce | productName(), price(), department(), isbn(), barcode() | | phone | number(), imei() | | date | past(), future(), recent(), birthdate(), month(), weekday(), between() | | image | avatar(), url(), category(), dataUri() | | lorem | word(), words(), sentence(), paragraph(), slug(), markdown(), html() | | color | hex(), rgb(), rgba(), hsl(), cssColorName(), tailwindColor(), materialColor(), svgPattern() | | vehicle | manufacturer(), model(), type(), vin() | | animal | type(), name() | | science | unit(), chemicalElement() | | ai | prompt(), chatConversation(), codeSnippet(), sqlQuery(), json(), markdown(), apiResponse(), logLine(), commitMessage(), issueTitle(), prDescription() | | misc | emoji(), hashtag(), programmingLanguage(), githubUsername(), gitCommitHash(), semver(), dockerImageName(), npmPackageName(), otp(), licenseKey(), qrData(), movie(), book(), music(), food(), holiday(), university() |

Run forge.listGenerators().length to see the exact live count (100+).

Runtime support

ForgeData avoids Node-only APIs in src/ — it uses only btoa, Math/Date, and standard JS, all of which exist in Node 18+, Bun, Deno, and every modern browser. It's published as ESM + CJS so:

• Node.js: import/require both work out of the box.
• Bun: works via the same ESM/CJS builds.
• Deno: import { ForgeData } from "npm:@sahinur/forgedata";
• Browsers: import { ForgeData } from "@sahinur/forgedata"; through any bundler, or examples/browser.html for a zero-bundler example.

Development

npm install
npm run build            # tsup -> dist (ESM + CJS + .d.ts, for index/react/zod/cli)
npm run test:coverage    # vitest, enforces 100% coverage thresholds
npm run lint
npm run bench            # micro-benchmark, compares against faker if installed
npm run cli -- list      # run the CLI from source during development

See the documentation site (built from docs/docs.html) for the getting-started guide, full API reference, React guide, CLI reference, migration guide from Faker.js, and contributing guide. See examples/ for runnable Node, browser, React, and CLI samples.

Website

docs/ is a plain HTML + Tailwind CSS landing page and single-page documentation site (no framework, no server-side build):

cd docs
npm install
npm run build   # compiles src/input.css -> dist/output.css (commit the result)
npm run serve   # or just open index.html directly

Deployed straight from the repo — no CI needed: Settings → Pages → Source → Deploy from a branch → main / docs. Because there's no build step in that flow, docs/dist/output.css is committed rather than gitignored; run npm run build in docs/ and commit the output whenever you touch docs/src/input.css or add new Tailwind classes to the HTML.

Publishing

This repo is fully set up to publish, but nothing publishes itself:

npm run preflight   # lint + typecheck + 100%-coverage tests + build
npm login
npm publish --access public

scripts/publish.sh wraps that sequence with a confirmation prompt, and RELEASE_NOTES.md has a ready-to-paste description for the GitHub Release / npm announcement.

For every release after the first, .github/workflows/release.yml runs semantic-release on pushes to main — it derives the next version from Conventional Commits, updates CHANGELOG.md, tags, and publishes, but only once you add an NPM_TOKEN repository secret. Until then it's a no-op (see the docs site's Contributing section); it never requires a token to just sit there ready.

License

MIT