Chance.js Random Data Generator

1.1.13 · active · verified Sun Apr 19

Chance.js is a comprehensive utility library designed for generating a wide variety of random data in JavaScript environments, including Node.js and browsers. It currently stands at stable version 1.1.13 and has a generally infrequent release cadence, with major updates occurring as needed for new features or critical bug fixes rather than on a fixed schedule. Its core differentiator is its foundation on the Mersenne Twister algorithm, which allows for repeatable pseudo-random sequences when seeded, making it invaluable for testing, data simulation, and reproducible scenarios. The library provides generators for basic types like numbers, characters, and strings, as well as complex data such as names, addresses, dice rolls, and geographical coordinates, distinguishing itself by its breadth and optional determinism.

Common errors

```
TypeError: Chance is not a constructor
```
cause Attempting to call `Chance()` directly without the `new` keyword.

fix Use `const chance = new Chance();` to instantiate the Chance generator.
```
ReferenceError: Chance is not defined
```
cause The Chance library was not imported or included correctly, or you are trying to use a CommonJS `require` in an ES Module context without proper setup, or vice versa.

fix Ensure you have `import Chance from 'chance';` (ESM) or `const Chance = require('chance');` (CJS) at the top of your file, or that the `<script>` tag is loaded in a browser environment.
```
ReferenceError: require is not defined
```
cause Trying to use `require('chance')` in an ES Module context (e.g., in a file where `type: 'module'` is set in `package.json` or a `.mjs` file).

fix Change the import to `import Chance from 'chance';`. If you truly need CommonJS, ensure your file is treated as CJS (e.g., using `.cjs` extension or `type: 'commonjs'` in `package.json`).

Warnings

gotcha When using Chance.js, always instantiate it with `new Chance()` to get a generator instance. Calling `Chance()` directly without `new` will result in a TypeError because it's a constructor.
Fix: Use `const chance = new Chance();` instead of `const chance = Chance();`.
gotcha To ensure true randomness or unique sequences across different runs in a production environment, avoid hardcoding a seed or remove seeding entirely. Seeding is primarily for reproducible testing.
Fix: For non-reproducible randomness, instantiate without a seed: `const chance = new Chance();`. For environment-driven seeding, use `new Chance(process.env.RANDOM_SEED ?? undefined);`.
gotcha While Chance.js supports both CommonJS and ESM, mixing import styles (e.g., `require` in an ESM module or `import` in a CJS module without proper transpilation) can lead to module resolution errors. Ensure your project's module system is consistently configured.
Fix: For ESM projects, use `import Chance from 'chance';`. For CommonJS projects, use `const Chance = require('chance');`. Configure your `package.json` `type` field and build tools appropriately.

Install

npm install chance npm
yarn add chance yarn
pnpm add chance pnpm

Imports

Chance
wrong:
```
import { Chance } from 'chance';
import chance from 'chance';
```
correct:
```
import Chance from 'chance';
```
The primary export is a constructor function for the Chance class. Instantiate it with `new Chance()` to get a generator instance. The `import chance from 'chance'` form would be correct if it were an already instantiated default export, which it is not.
Chance
wrong:
```
import Chance from 'chance';
```
correct:
```
const Chance = require('chance');
```
This is the standard CommonJS import pattern. Remember to instantiate the Chance constructor with `new Chance()`.
Chance (global)
wrong:
```
import Chance from 'chance'; // In browser without build step
```
correct:
```
<script src="path/to/chance.min.js"></script>
// Chance is now available globally
```
In browser environments, if loaded via a script tag, 'Chance' becomes a global variable. No explicit import statement is needed or supported in this context without a module bundler.

Quickstart

This quickstart demonstrates how to instantiate Chance, generate various types of random data, and critically, how to use seeding to achieve reproducible random sequences for testing or deterministic data generation.

import Chance from 'chance';

// Create a new Chance instance (can be seeded for repeatable results)
const chance = new Chance(process.env.RANDOM_SEED ?? undefined);

console.log('Generating some random data:');
console.log(`- Random Name: ${chance.name()}`);
console.log(`- Random Age: ${chance.age()}`);
console.log(`- Random GUID: ${chance.guid()}`);
console.log(`- Random Sentence: ${chance.sentence()}`);
console.log(`- Random Email: ${chance.email()}`);
console.log(`- Random IPv4 Address: ${chance.ip()}`);
console.log(`- Random Dice Roll (d6): ${chance.d6()}`);
console.log(`- Random Boolean: ${chance.bool()}`);
console.log(`- Random Color (hex): ${chance.color({ format: 'hex' })}`);
console.log(`- Pick a random element: ${chance.pickone(['apple', 'banana', 'cherry'])}`);

// Demonstrating seeding for reproducibility
const repeatableChance = new Chance('my-seed-value');
const firstString = repeatableChance.string();
const secondString = repeatableChance.string();

const anotherRepeatableChance = new Chance('my-seed-value');
const thirdString = anotherRepeatableChance.string();

console.log('\nDemonstrating reproducibility with seeding:');
console.log(`- First string with seed: ${firstString}`);
console.log(`- Second string with seed: ${secondString}`);
console.log(`- Third string with same seed (should match first): ${thirdString}`);
console.log(`- Are first and third strings identical? ${firstString === thirdString}`);

view raw JSON →