Upgrading to v8

This is the migration guide for upgrading from v7 to v8.

Not the version you are looking for?

• Upgrading to v7
• Upgrading to v6

Breaking changes

Removed ability to change the locale on existing Faker instances

Note

If you are using only the default (en) locale, then you don't have to change anything.

In order to facilitate better and easier locale fallback mechanics, we removed the methods to change the locales on existing Faker instances. Now, we expose specific faker instances for each locale that you can use:

Old

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

faker.setLocale('de_CH');
// or
faker.locale = 'de_CH';
faker.localeFallback = 'en';

New

import { fakerDE_CH as faker } from '@faker-js/faker';

This also fixes issues where more than two locales are required:

Old

import { faker, Faker } from '@faker-js/faker';

const { de_CH, de, en } = faker.locales;
const customFaker = new Faker({
  locale: 'de_CH', // the expected locale
  localeFallback: 'de', // ensure we have a German fallback for addresses
  locales: { de_CH, de, en },
});
const a = customFaker.internet.email();
customFaker.locale = 'en'; // neither 'de_CH' nor 'de' have emojis
const b = customFaker.internet.emoji();

New

import { base, de, de_CH, en, Faker } from '@faker-js/faker';

// same as fakerDE_CH
export const customFaker = new Faker({
  // Now multiple fallbacks are supported
  locale: [de_CH, de, en, base],
});
const a = customFaker.internet.email();
const b = customFaker.internet.emoji();

If you wish to create entries for multiple locales, you can still do so:

Old

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

for (let user of users) {
  const lang = faker.helpers.arrayElement(['de', 'en', 'fr']);
  faker.locale = lang;
  user.email = faker.internet.email();
}

New

import { faker, fakerDE, fakerEN, fakerFR } from '@faker-js/faker';

for (let user of users) {
  const currentFaker = faker.helpers.arrayElement([fakerDE, fakerEN, fakerFR]);
  user.email = currentFaker.internet.email();
}

For more information refer to our Localization Guide.

For missing locale data, Faker will now throw instead of returning undefined or a-c

Note

The following section mostly applies to custom-built Faker instances.

Previously, for example if en didn't have data for animal.cat, then faker.animal.cat() would have returned one of a, b or c (arrayElement's default value). These values aren't expected/useful as a fallback and potentially also violate the method's defined return type definitions (in case it doesn't return a string).

We have now addressed this by changing the implementation so that an error is thrown, prompting you to provide/contribute the missing data. This will also give you detailed information which data are missing. If you want to check for data you can either use entry in faker.definitions.category or use faker.rawDefinitions.category?.entry instead.

import { es, Faker, fakerES } from '@faker-js/faker';

const fakerES_noFallbacks = new Faker({
  locale: [es],
});
fakerES.music.songName(); // 'I Want to Hold Your Hand' (fallback from en)
// Previously:
//fakerES_noFallbacks.music.songName(); // 'b'
// Now:
fakerES_noFallbacks.music.songName(); // throws a FakerError

This also has an impact on data that aren't applicable to a locale, for example Hong Kong (en_HK) doesn't use ZIP codes/postcodes.

import { fakerEN_HK, fakerEN_US } from '@faker-js/faker';
fakerEN_US.location.zipCode(); // 90210
fakerEN_HK.location.zipCode(); // throws a FakerError

faker.mersenne and faker.helpers.repeatString removed

faker.mersenne and faker.helpers.repeatString were only ever intended for internal use, and are no longer available.

faker.location.zipCodeByState

The faker.location.zipCodeByState method has been deprecated, but will also now throw an error if the current locale does not have a postcode_by_state definition.

Methods will throw on empty data set inputs

The methods faker.helpers.arrayElement and faker.helpers.arrayElements previously defaulted the array argument to a simple string array if none was provided. This behavior is no longer supported, as the default value has been removed. You are now required to provide an argument.

Additionally, when passing in an empty array argument ([]), the functions previously returned undefined. This behavior violated the expected return type of the method. The methods will now throw an FakerError instead.

The same thing happens now if you provide an empty object {} to faker.helpers.objectKey or faker.helpers.objectValue.

Old

const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
// `tags` might be an empty array which was no problem in v7
const featuredTag = faker.helpers.arrayElement(tags);
// `featureTag` will be typed as `string` but could actually be `undefined`

New

const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
// `tags` might be an empty array which will throw in v8
const featuredTag =
  tags.length === 0 ? undefined : faker.helpers.arrayElement(tags);
// `featureTag` has to be explicitly set to `undefined` on your side

// OR

const allTags = ['dogs', 'cats', 'fish', 'horses', 'sheep'];
const tags = faker.helpers.arrayElements(allTags, { min: 0, max: 3 });
let featuredTag: string | undefined;
try {
  featuredTag = faker.helpers.arrayElement(post.tags);
} catch (e) {
  // handle error and do something special
}

Other deprecated methods removed/replaced

Old method	New method
faker.unique	faker.helpers.unique (⚠️ please check #1785)
faker.fake	faker.helpers.fake
faker.commerce.color	faker.color.human
faker.company.companyName	faker.company.name
faker.phone.phoneNumber	faker.phone.number
faker.phone.phoneNumberFormat	No direct replacement, see documentation for faker.phone.number
faker.phone.phoneFormats	No direct replacement, see documentation for faker.phone.number
faker.name.findName	Removed, replace with faker.person.fullName
faker.address.cityPrefix	Removed
faker.address.citySuffix	Removed
faker.address.streetPrefix	Removed
faker.address.streetSuffix	Removed
faker.image.lorempixel	Removed, as the LoremPixel service is no longer available

Definitions removed

Some data definitions, which were only available via the faker.helpers.fake method, or the undocumented faker.definitions, have been removed.

Removed data	Alternative
faker.definitions.business.credit_card_numbers	faker.finance.creditCardNumber()
faker.definitions.business.credit_card_types	faker.finance.creditCardIssuer()
faker.definitions.business.credit_card_expiry_dates	faker.date.future()

Deprecations and other changes

This is not an exhaustive list of all deprecations in v8.0.0. Many methods and parameters have been renamed in this release. You can:

• use the warnings which are shown at runtime to guide you to the new names
• use a suitable plugin to find usages of deprecated code
• Review the full list of deprecations here and here
• Ignore the deprecations for now: the old names will continue to work for v8.x.x, however you will need to make changes before upgrading to v9.x.x.

faker.name changed to faker.person

The whole faker.name module is now located at faker.person, as it contains more information than just names. The faker.name.* methods will continue to work as an alias in v8 and v9, but it is recommended to change to faker.person.*

Old method	New method
faker.name.firstName	faker.person.firstName
faker.name.lastName	faker.person.lastName
faker.name.middleName	faker.person.middleName
faker.name.fullName	faker.person.fullName
faker.name.gender	faker.person.gender
faker.name.sex	faker.person.sex
faker.name.sexType	faker.person.sexType
faker.name.prefix	faker.person.prefix
faker.name.suffix	faker.person.suffix
faker.name.jobTitle	faker.person.jobTitle
faker.name.jobDescriptor	faker.person.jobDescriptor
faker.name.jobArea	faker.person.jobArea
faker.name.jobType	faker.person.jobType
faker.name.findName	Removed, replace with faker.person.fullName

faker.address changed to faker.location

The whole faker.address module is now located at faker.location, as it contains more information than just addresses. The faker.address.* methods will continue to work as an alias in v8 and v9, but it is recommended to change to faker.location.*

Old method	New method
faker.address.buildingNumber	faker.location.buildingNumber
faker.address.cardinalDirection	faker.location.cardinalDirection
faker.address.city	faker.location.city
faker.address.cityName	faker.location.city
faker.address.country	faker.location.country
faker.address.countryCode	faker.location.countryCode
faker.address.county	faker.location.county
faker.address.direction	faker.location.direction
faker.address.faker	faker.location.faker
faker.address.latitude	faker.location.latitude
faker.address.longitude	faker.location.longitude
faker.address.nearbyGPSCoordinate	faker.location.nearbyGPSCoordinate
faker.address.ordinalDirection	faker.location.ordinalDirection
faker.address.secondaryAddress	faker.location.secondaryAddress
faker.address.state	faker.location.state
faker.address.stateAbbr	faker.location.stateAbbr
faker.address.street	faker.location.street
faker.address.streetAddress	faker.location.streetAddress
faker.address.streetName	faker.location.street
faker.address.timeZone	faker.location.timeZone
faker.address.zipCode	faker.location.zipCode
faker.address.zipCodeByState	faker.location.zipCodeByState
faker.address.cityPrefix	Removed
faker.address.citySuffix	Removed
faker.address.streetPrefix	Removed
faker.address.streetSuffix	Removed

Number methods of faker.datatype moved to new faker.number module

The number-related methods previously found in faker.datatype have been moved to a new faker.number module. For the old faker.datatype.number method you should replace with faker.number.int or faker.number.float depending on the precision required.

By default, faker.number.float no longer defaults to a precision of 0.01

// OLD
faker.datatype.number(); // 88999 (NOTE: The default max was 99999)
faker.datatype.number({ max: 100 }); // 35
faker.datatype.number({ max: 100, precision: 0.01 }); // 35.21
faker.datatype.float({ max: 100 }); // 35.21
faker.datatype.float({ max: 100, precision: 0.001 }); // 35.211

// NEW
faker.number.int({ max: 99999 }); // 88999 (NOTE: the default max is now Number.MAX_SAFE_INTEGER)
faker.number.int({ max: 100 }); // 35
faker.number.float({ max: 100 }); // 35.21092065742612
faker.number.float({ max: 100, precision: 0.01 }); // 35.21

Old method	New method
faker.datatype.number	faker.number.int or faker.number.float
faker.datatype.float	faker.number.float
faker.datatype.bigInt	faker.number.bigInt

Deprecation of faker.datatype.array

The method faker.datatype.array has been deprecated and will be removed in v9. If you need an array of useful values, you are better off creating your own one using faker.helpers.multiple.

faker.datatype.datetime deprecated in favor of faker.date.between and faker.date.anytime

The datetime method previously found in faker.datatype has been deprecated, use faker.date.between or faker.date.anytime instead.

faker.helpers.regexpStyleStringParse deprecated in favor of faker.helpers.fromRegExp

The regexpStyleStringParse method in faker.helpers has been deprecated in Faker 8.1. A likely replacement is the more powerful faker.helpers.fromRegExp.

faker.helpers.regexpStyleStringParse('a{3,6}'); // aaaaa
faker.helpers.fromRegExp('a{3,6}'); // aaaaa

However, please note that faker.helpers.fromRegExp is not an exact replacement for faker.helpers.regexpStyleStringParse as fromRegExp cannot handle numeric ranges. This will now need to be handled separately.

faker.helpers.regexpStyleStringParse('a{3,6}[1-100]'); // "aaaa53", etc.
faker.helpers.fromRegExp('a{3,6}') + faker.number.int({ min: 1, max: 100 });

allowLeadingZeros behavior change in faker.string.numeric

The allowLeadingZeros boolean parameter in faker.string.numeric (in the new string module) now defaults to true. faker.string.numeric will now generate numeric strings that could have leading zeros by default.

Simplified MIME type data

The functions faker.system.mimeType, faker.system.fileType and faker.system.fileExt now return data from a smaller set of more common MIME types, filetypes and extensions.

faker.helpers.unique is planned to be outsourced

The faker.helpers.unique method is planned to be outsourced to a separate package.
Please check issue #1785 for more details.

Locales renamed

The en_IND (English, India) locale was renamed to en_IN for consistency with other locales.

The cz (Czech) locale was renamed to cs_CZ to use the standard ISO codes for language and country.

The ge (Georgian) locale was renamed to ka_GE to use the standard ISO codes for language and country.