Migration Guide

Migrating to nanofaker from other faker libraries is straightforward. This guide helps you transition from popular alternatives.

From Faker.js / @faker-js/faker

Installation

# Remove old package
npm uninstall faker
# or
npm uninstall @faker-js/faker

# Install nanofaker
npm install nanofaker

Import Changes

Before (faker.js):

import { faker } from '@faker-js/faker'

After (nanofaker):

import { faker } from 'nanofaker'

API Differences

Most APIs are compatible, but here are the key differences:

Locale Setting

Before:

import { faker } from '@faker-js/faker'
import { es } from '@faker-js/faker/locale/es'

faker.locale = es

After:

import { faker } from 'nanofaker'

faker.setLocale('es')
// or create new instance
const esFaker = new Faker({ locale: 'es' })

Seeding

Before:

faker.seed(123)

After:

faker.seed(123) // Same!

Common Methods

Most methods work the same:

faker.js	nanofaker	Notes
faker.name.firstName()	faker.person.firstName()	Use person instead of name
faker.name.lastName()	faker.person.lastName()	Use person instead of name
faker.name.fullName()	faker.person.fullName()	Use person instead of name
faker.internet.email()	faker.internet.email()	✓ Same
faker.address.city()	faker.address.city()	✓ Same
faker.datatype.number()	faker.number.int()	Use number.int()
faker.datatype.boolean()	faker.helpers.boolean()	Moved to helpers
faker.random.arrayElement()	faker.helpers.arrayElement()	Moved to helpers
faker.random.word()	faker.word.noun()	More specific

Migration Example

Before (faker.js):

import { faker } from '@faker-js/faker'

const user = {
  id: faker.datatype.uuid(),
  name: faker.name.fullName(),
  email: faker.internet.email(),
  age: faker.datatype.number({ min: 18, max: 80 }),
  city: faker.address.city(),
  isActive: faker.datatype.boolean(),
}

After (nanofaker):

import { faker } from 'nanofaker'

const user = {
  id: crypto.randomUUID(), // Use native crypto
  name: faker.person.fullName(),
  email: faker.internet.email(),
  age: faker.number.int({ min: 18, max: 80 }),
  city: faker.address.city(),
  isActive: faker.helpers.boolean(),
}

Not Yet Supported

Some faker.js features aren't in nanofaker yet:

• faker.datatype.uuid() → Use crypto.randomUUID()
• faker.datatype.datetime() → Use faker.date.* methods
• faker.image.*() → Use faker.image.*() (limited)
• Custom locales at runtime → Locales are built-in

From Laravel Faker (PHP)

Basic Usage

Before (Laravel/PHP):

$faker = Faker\Factory::create();
$name = $faker->name;
$email = $faker->email;

After (nanofaker/TypeScript):

import { faker } from 'nanofaker'

const name = faker.person.fullName()
const email = faker.internet.email()

Locale

Before:

$faker = Faker\Factory::create('es_ES');

After:

const faker = new Faker({ locale: 'es' })

Common Methods

Laravel Faker (PHP)	nanofaker (TypeScript)
$faker->name	faker.person.fullName()
$faker->firstName	faker.person.firstName()
$faker->email	faker.internet.email()
$faker->phoneNumber	faker.phone.number()
$faker->address	faker.address.street()
$faker->city	faker.address.city()
$faker->country	faker.address.country()
$faker->company	faker.company.name()
$faker->randomElement($array)	faker.helpers.arrayElement(array)
$faker->boolean	faker.helpers.boolean()
$faker->numberBetween(1, 100)	faker.number.int({ min: 1, max: 100 })
$faker->word	faker.word.noun()
$faker->sentence	faker.lorem.sentence()

Formatters

Before:

$faker->numerify('###-###');
$faker->lexify('???');
$faker->bothify('##??##');

After:

faker.helpers.numerify('###-###')
faker.helpers.lexify('???')
faker.helpers.bothify('##??##')

Database Seeding

Before (Laravel):

User::factory()->count(50)->create();

// or manual
for ($i = 0; $i < 50; $i++) {
    User::create([
        'name' => $faker->name,
        'email' => $faker->email,
    ]);
}

After (TypeScript/Node.js):

import { faker } from 'nanofaker'

// Generate data
const users = Array.from({ length: 50 }, () => ({
  name: faker.person.fullName(),
  email: faker.internet.email(),
}))

// Insert into database
await db.users.insertMany(users)

From Chance.js

Installation

npm uninstall chance
npm install nanofaker

API Mapping

Chance.js	nanofaker
chance.name()	faker.person.fullName()
chance.first()	faker.person.firstName()
chance.last()	faker.person.lastName()
chance.email()	faker.internet.email()
chance.phone()	faker.phone.number()
chance.address()	faker.address.street()
chance.city()	faker.address.city()
chance.state()	faker.address.state()
chance.country()	faker.address.country()
chance.bool()	faker.helpers.boolean()
chance.integer({ min, max })	faker.number.int({ min, max })
chance.pickone(array)	faker.helpers.arrayElement(array)
chance.shuffle(array)	faker.helpers.shuffle(array)

From Casual

Basic Usage

Before (Casual):

import casual from 'casual'

const name = casual.full_name
const email = casual.email

After (nanofaker):

import { faker } from 'nanofaker'

const name = faker.person.fullName()
const email = faker.internet.email()

Common Methods

Casual	nanofaker
casual.full_name	faker.person.fullName()
casual.first_name	faker.person.firstName()
casual.email	faker.internet.email()
casual.phone	faker.phone.number()
casual.city	faker.address.city()
casual.country	faker.address.country()
casual.random_element(array)	faker.helpers.arrayElement(array)
casual.integer(1, 100)	faker.number.int({ min: 1, max: 100 })
casual.coin_flip	faker.helpers.boolean()

Common Migration Patterns

Factory Pattern

Before (any library):

class UserFactory {
  static create() {
    return {
      name: oldFaker.name(),
      email: oldFaker.email(),
    }
  }
}

After:

import { faker } from 'nanofaker'

class UserFactory {
  static create() {
    return {
      name: faker.person.fullName(),
      email: faker.internet.email(),
    }
  }
}

Seeding Databases

Before:

const users = []
for (let i = 0; i < 100; i++) {
  users.push({
    name: oldFaker.name(),
    email: oldFaker.email(),
  })
}

After:

import { faker } from 'nanofaker'

const users = Array.from({ length: 100 }, () => ({
  name: faker.person.fullName(),
  email: faker.internet.email(),
}))

Test Fixtures

Before:

beforeEach(() => {
  testUser = {
    name: oldFaker.name(),
    email: oldFaker.email(),
  }
})

After:

import { faker } from 'nanofaker'

beforeEach(() => {
  faker.seed(12345) // Reproducible!
  testUser = {
    name: faker.person.fullName(),
    email: faker.internet.email(),
  }
})

Tips for Migration

1. Start with Core Data

Migrate your most common data first:

• Names → faker.person.*
• Emails → faker.internet.email()
• Addresses → faker.address.*

2. Use Find & Replace

Most migrations can be done with find & replace:

• faker.name. → faker.person.
• faker.datatype.number → faker.number.int
• faker.random.arrayElement → faker.helpers.arrayElement

3. Test Incrementally

Migrate one module at a time and test:

// Step 1: Migrate imports
import { faker } from 'nanofaker'

// Step 2: Migrate one function
function createUser() {
  return {
    name: faker.person.fullName(), // ✓ Migrated
    email: faker.internet.email(), // ✓ Migrated
  }
}

// Step 3: Test
const user = createUser()
console.log(user)

// Step 4: Migrate next function

4. Create Adapters for Complex Cases

If you have complex legacy code:

// adapter.ts
import { faker } from 'nanofaker'

export const legacyFaker = {
  name: () => faker.person.fullName(),
  email: () => faker.internet.email(),
  // Map your old API to new API
}

// Then gradually replace the adapter

5. Update Tests

Ensure your tests work with the new library:

import { describe, expect, test } from 'bun:test'
import { faker } from 'nanofaker'

describe('Migration tests', () => {
  test('generates valid user data', () => {
    faker.seed(123) // Reproducible

    const user = {
      name: faker.person.fullName(),
      email: faker.internet.email(),
    }

    expect(user.name).toBeTruthy()
    expect(user.email).toContain('@')
  })
})

Benefits After Migration

After migrating to nanofaker, you'll get:

✅ Smaller bundle size - Significantly lighter than faker.js ✅ Better performance - Faster data generation ✅ Complete locale coverage - All 16 locales fully translated ✅ Full TypeScript support - Better IDE autocomplete ✅ Simpler API - Less configuration needed ✅ CLI tool - Command-line data generation

Need Help?

If you encounter issues during migration:

1. Check the API Reference
2. See Usage Examples
3. Ask on GitHub Discussions
4. Join the Discord

Happy migrating! 🚀