Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: include hints on specifying a locale can help startup time #1629

Merged
merged 9 commits into from
Dec 7, 2022
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,12 @@ Array.from({ length: 10 }).forEach(() => {
});
```

The above code indicates a basic usage of Faker.
The point of interest is the import statements at the top.
The first import indicates how one can import the entirety of Faker, which includes every local, while the commented-out import showcases how to import only a single local.
In most situations, importing a single local is preferable for performance because some testing frameworks reload imports for every test file, which causes startup latencies to add up quickly.
Thus, limiting the import to a single locale can speed up startup times.

## 💎 Modules

An in-depth overview of the API methods is available in the [documentation](https://fakerjs.dev/guide/).
Expand Down
5 changes: 5 additions & 0 deletions docs/guide/localization.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,11 @@ The English locales are around 600 KB in size.
All locales together are around 5 MB in size.
:::

:::tip Note
Some locales have limited coverage and rely more heavily on the English locale as the source for features they currently do not have.
However, in most cases, using a specific locale will be beneficial in the long term as specifying a locale reduces the time necessary for startup, which has a compounding effect on testing frameworks that reload the imports every execution.
:::

## Available locales

<!-- LOCALES-AUTO-GENERATED-START -->
Expand Down
9 changes: 8 additions & 1 deletion docs/guide/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,18 @@ Using Faker is as easy as importing it from `@faker-js/faker`.

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

// or, if desiring only a specific locale
// import { faker } from '@faker-js/faker/locale/de'
const randomName = faker.person.fullName(); // Rowan Nikolaus
const randomEmail = faker.internet.email(); // [email protected]
```

:::tip Note
Using the first import statement will load every locale into memory.
As such, start-up times and performance may be slow.
Thus, by declaring a locale in the import, one can increase performance and reduce the time on start-up.
:::

Or if you're using CommonJS:

```js
Expand Down