@seedts/faker

Faker.js integration for SeedTS - Generate realistic fake data for database seeding.

Installation

npm install @seedts/faker @faker-js/faker
# or
pnpm add @seedts/faker @faker-js/faker
# or
yarn add @seedts/faker @faker-js/faker

Quick Start

import { faker } from '@seedts/faker';
import { Seed, Action, Entity, Attribute } from '@seedts/jsx-runtime';

export const UsersSeed = (props) => (
  <Seed name="users" adapter={props.adapter}>
    <Action count={50}>
      <Entity>
        <Attribute name="email" factory={faker.email()} />
        <Attribute name="firstName" factory={faker.firstName()} />
        <Attribute name="lastName" factory={faker.lastName()} />
        <Attribute name="avatar" factory={faker.avatar()} />
        <Attribute name="bio" factory={faker.paragraph()} />
      </Entity>
    </Action>
  </Seed>
);

Pre-built Factories

Use pre-built factories for common data patterns:

import { userFactory, postFactory, productFactory } from '@seedts/faker/factories';

// User with all common fields
<Entity>
  <Attribute name="email" factory={userFactory.email} />
  <Attribute name="firstName" factory={userFactory.firstName} />
  <Attribute name="lastName" factory={userFactory.lastName} />
  <Attribute name="username" factory={userFactory.username} />
  <Attribute name="password" factory={userFactory.password} />
  <Attribute name="avatar" factory={userFactory.avatar} />
  <Attribute name="phone" factory={userFactory.phone} />
</Entity>

// Blog post
<Entity>
  <Attribute name="title" factory={postFactory.title} />
  <Attribute name="slug" factory={postFactory.slug} />
  <Attribute name="content" factory={postFactory.content} />
  <Attribute name="excerpt" factory={postFactory.excerpt} />
  <Attribute name="publishedAt" factory={postFactory.publishedAt} />
</Entity>

// Product
<Entity>
  <Attribute name="name" factory={productFactory.name} />
  <Attribute name="description" factory={productFactory.description} />
  <Attribute name="price" factory={productFactory.price} />
  <Attribute name="sku" factory={productFactory.sku} />
  <Attribute name="inStock" factory={productFactory.inStock} />
</Entity>

Available Factories

• userFactory - User/profile data
• postFactory - Blog posts/articles
• productFactory - E-commerce products
• companyFactory - Company information
• addressFactory - Physical addresses
• commentFactory - Comments/reviews
• eventFactory - Events/meetings
• profileFactory - Social profiles
• orderFactory - Orders/transactions
• tagFactory - Tags/categories

API Reference

Person

faker.firstName()       // Generate first name
faker.lastName()        // Generate last name
faker.fullName()        // Generate full name
faker.jobTitle()        // Generate job title

Internet

faker.email()           // Generate email
faker.username()        // Generate username
faker.url()             // Generate URL
faker.avatar()          // Generate avatar URL
faker.password()        // Generate password

Company

faker.companyName()     // Generate company name
faker.catchPhrase()     // Generate catch phrase
faker.buzzword()        // Generate buzzword

Address

faker.streetAddress()   // Generate street address
faker.city()            // Generate city
faker.state()           // Generate state
faker.zipCode()         // Generate zip code
faker.country()         // Generate country

Phone

faker.phoneNumber()     // Generate phone number

Lorem

faker.word()            // Generate word
faker.words(5)          // Generate 5 words
faker.sentence()        // Generate sentence
faker.paragraph()       // Generate paragraph
faker.paragraphs(3)     // Generate 3 paragraphs
faker.text()            // Generate text

Numbers

faker.int({ min: 1, max: 100 })              // Generate integer
faker.float({ min: 0, max: 1, precision: 2 }) // Generate float

Dates

faker.pastDate({ years: 1 })                  // Generate past date
faker.futureDate({ years: 1 })                // Generate future date
faker.recentDate({ days: 30 })                // Generate recent date
faker.dateBetween(new Date('2020-01-01'), new Date()) // Generate date between

Commerce

faker.productName()         // Generate product name
faker.productDescription()  // Generate product description
faker.price()              // Generate price
faker.department()         // Generate department

Finance

faker.creditCardNumber()    // Generate credit card number
faker.iban()               // Generate IBAN
faker.currencyCode()       // Generate currency code

Other

faker.boolean()            // Generate boolean
faker.uuid()               // Generate UUID
faker.arrayElement(['a', 'b', 'c'])     // Pick random element
faker.arrayElements(['a', 'b', 'c'], 2) // Pick 2 random elements
faker.shuffle([1, 2, 3])                // Shuffle array

Locale Support

Create a faker instance with a specific locale:

import { createFaker } from '@seedts/faker';
import { faker as fakerDE } from '@faker-js/faker/locale/de';
import { faker as fakerFR } from '@faker-js/faker/locale/fr';

// Create German faker
const deFaker = createFaker(fakerDE);

// Create French faker
const frFaker = createFaker(fakerFR);

<Attribute name="name" factory={deFaker.fullName()} />
<Attribute name="city" factory={deFaker.city()} />

Available locales: en, de, fr, es, it, pt, ru, zh_CN, ja, ko, and many more. See Faker.js locales for the full list.

Advanced Usage

Custom Combinations

import { faker } from '@seedts/faker';

// Combine multiple faker methods
const customEmail: AttributeGenerator<string> = (ctx) => {
  const firstName = faker.instance.person.firstName();
  const lastName = faker.instance.person.lastName();
  return `${firstName}.${lastName}@example.com`.toLowerCase();
};

<Attribute name="email" factory={customEmail} />

Context-aware Factories

// Use context index for sequential data
const sequentialEmail: AttributeGenerator<string> = (ctx) => {
  return `user${ctx.index}@example.com`;
};

// Combine with faker for variety
const variedEmail: AttributeGenerator<string> = (ctx) => {
  const domain = faker.instance.internet.domainName();
  return `user${ctx.index}@${domain}`;
};

Accessing Raw Faker Instance

import { faker } from '@seedts/faker';

// Access the underlying Faker.js instance
const customFactory = () => {
  return faker.instance.helpers.fake('{{person.firstName}} {{person.lastName}}');
};

TypeScript Support

All faker methods are fully typed:

import { faker } from '@seedts/faker';
import type { AttributeGenerator } from '@seedts/types';

const emailGen: AttributeGenerator<string> = faker.email();
const ageGen: AttributeGenerator<number> = faker.int({ min: 18, max: 80 });
const activeGen: AttributeGenerator<boolean> = faker.boolean();

Examples

Complete User Seed

import { faker, userFactory } from '@seedts/faker';

export const UsersSeed = ({ adapter }) => (
  <Seed name="users" adapter={adapter}>
    <Action count={100}>
      <Entity>
        <Attribute name="id" type="number" autoIncrement />
        <Attribute name="email" type="string" unique factory={userFactory.email} />
        <Attribute name="firstName" type="string" factory={userFactory.firstName} />
        <Attribute name="lastName" type="string" factory={userFactory.lastName} />
        <Attribute name="username" type="string" unique factory={userFactory.username} />
        <Attribute name="password" type="string" factory={userFactory.password} />
        <Attribute name="avatar" type="string" factory={userFactory.avatar} />
        <Attribute name="bio" type="string" factory={faker.paragraph(2)} />
        <Attribute name="phone" type="string" factory={userFactory.phone} />
        <Attribute name="age" type="number" factory={faker.int({ min: 18, max: 80 })} />
        <Attribute name="active" type="boolean" factory={faker.boolean()} />
        <Attribute name="createdAt" type="date" default={() => new Date()} />
      </Entity>
    </Action>
  </Seed>
);

License

MIT