diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index aad3bdf2ace..ef274b9df31 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -130,6 +130,10 @@ export default defineConfig({
text: 'Getting Started',
link: '/guide/',
},
+ {
+ text: 'Usage',
+ link: '/guide/usage',
+ },
{
text: 'Localization',
link: '/guide/localization',
diff --git a/docs/guide/index.md b/docs/guide/index.md
index bd39ec2c3cb..cfee521dc27 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -37,94 +37,6 @@ or
pnpm add @faker-js/faker --save-dev
```
-## Usage
-
-### Node.js
-
-```js
-import { faker } from '@faker-js/faker';
-// or, if using CommonJS
-// const { faker } = require('@faker-js/faker');
-
-const randomName = faker.name.fullName(); // Rowan Nikolaus
-const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
-```
-
-### Browser
-
-```html
-
-
-```
-
-:::tip Note
-Using the browser is great for experimenting 👍. However, due to all of the strings Faker uses to generate fake data, **Faker is a large package**. It's `> 5 MiB` minified. **Please avoid deploying the full Faker in your web app.**
-:::
-
-### CDN/Deno
-
-```js
-import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
-
-const randomName = faker.name.findName(); // Willie Bahringer
-const randomEmail = faker.internet.email(); // Tomasa_Ferry14@hotmail.com
-```
-
-:::tip Note
-It is highly recommended to use version tags when importing libraries in Deno, e.g: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0"`. Add `?dts` to import with type definitions: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0?dts"`.
-:::
-
-#### Alternative CDN links
-
-**esm:**
-
-- https://esm.sh/@faker-js/faker
-- https://cdn.jsdelivr.net/npm/@faker-js/faker/+esm
-
-**cjs:**
-
-- https://cdn.jsdelivr.net/npm/@faker-js/faker
-
-### TypeScript Support
-
-Since version `v6+` there is native TypeScript support.
-
-In order to have faker working properly, you need to check if these `compilerOptions` are set correctly in your `tsconfig` file:
-
-```json
-{
- "compilerOptions": {
- "esModuleInterop": true,
- "moduleResolution": "Node"
- }
-}
-```
-
-And then simply import it like everything else:
-
-```ts
-import { faker } from '@faker-js/faker';
-```
-
-If you want for whatever reason the versions prior to `v6`,
-you can use `@types/faker` and rebind the declarations to the `@faker-js/faker` package with a `faker.d.ts` file in your e.g. src folder.
-
-```ts
-// faker.d.ts
-declare module '@faker-js/faker' {
- import faker from 'faker';
- export default faker;
-}
-```
-
## Community
If you have questions or need help, reach out to the community via [Discord](https://chat.fakerjs.dev) and [GitHub Discussions](https://github.com/faker-js/faker/discussions).
diff --git a/docs/guide/usage.md b/docs/guide/usage.md
new file mode 100644
index 00000000000..8d211354d7d
--- /dev/null
+++ b/docs/guide/usage.md
@@ -0,0 +1,205 @@
+# Usage
+
+## Node.js
+
+Using Faker is as easy as importing it from `@faker-js/faker`.
+
+```js
+import { faker } from '@faker-js/faker';
+
+const randomName = faker.name.fullName(); // Rowan Nikolaus
+const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
+```
+
+Or if you using CommonJS
+
+```js
+const { faker } = require('@faker-js/faker');
+
+const randomName = faker.name.fullName(); // Rowan Nikolaus
+const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
+```
+
+## Browser
+
+```html
+
+```
+
+:::note
+Using the browser is great for experimenting 👍. However, due to all of the strings Faker uses to generate fake data, **Faker is a large package**. It's `> 5 MiB` minified. **Please avoid deploying the full Faker in your web app.**
+:::
+
+## CDN/Deno
+
+```js
+import { faker } from 'https://cdn.skypack.dev/@faker-js/faker';
+
+const randomName = faker.name.findName(); // Willie Bahringer
+const randomEmail = faker.internet.email(); // Tomasa_Ferry14@hotmail.com
+```
+
+:::note
+It is highly recommended to use version tags when importing libraries in Deno, e.g: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0"`. Add `?dts` to import with type definitions: `import { faker } from "https://cdn.skypack.dev/@faker-js/faker@v7.4.0?dts"`.
+:::
+
+### Alternative CDN links
+
+**esm:**
+
+- https://esm.sh/@faker-js/faker
+- https://cdn.jsdelivr.net/npm/@faker-js/faker/+esm
+
+**cjs:**
+
+- https://cdn.jsdelivr.net/npm/@faker-js/faker
+
+## TypeScript Support
+
+Faker supports TypeScript out of the box, so you don't have to install any extra packages.
+
+In order to have Faker working properly, you need to check if these `compilerOptions` are set correctly in your `tsconfig` file:
+
+```json
+{
+ "compilerOptions": {
+ "esModuleInterop": true,
+ "moduleResolution": "Node"
+ }
+}
+```
+
+## Create complex objects
+
+Faker mostly generates values for primitives.
+This is because in the real world, most object schemas simply look very different.
+So, if you want to create an object, you most likely need to write a factory function for it.
+
+For our example, we use TypeScript to strongly type our model.
+The models we will use are described below:
+
+```ts
+import type { SexType } from '@faker-js/faker';
+
+type SubscriptionTier = 'free' | 'basic' | 'business';
+
+class User {
+ _id: string;
+ avatar: string;
+ birthday: Date;
+ email: string;
+ firstName: string;
+ lastName: string;
+ sex: SexType;
+ subscriptionTier: SubscriptionTier;
+}
+```
+
+As you can see, your `User` model probably looks completely different from the one you have in your codebase.
+One thing to keep an eye on is the `subscriptionTier` property, as it is not simply a string, but only one of the strings defined in the `SubscriptionTier` type (`'free'` or `'basic'` or `'business'`).
+Also, in a real scenario, your model should not depend on a type of a third party library (`SexType` in this case).
+
+Let's create our first user factory function:
+
+```ts
+import { faker } from '@faker-js/faker';
+
+function createRandomUser(): User {
+ return {
+ _id: faker.datatype.uuid(),
+ avatar: faker.image.avatar(),
+ birthday: faker.date.birthdate(),
+ email: faker.internet.email(),
+ firstName: faker.name.firstName(),
+ lastName: faker.name.lastName(),
+ sex: faker.name.sexType(),
+ subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
+ };
+}
+
+const user = createRandomUser();
+```
+
+At this point, we have a perfectly working function that will work for most purposes.
+But we can take this a step further.
+Currently, all properties are just randomly generated.
+This can lead to some undesirable values being produced.
+For example: The `sex` property having value `'female'` while `firstName` is `'Bob'`.
+
+Let's refactor our current code:
+
+```ts {4-7,13-16}
+import { faker } from '@faker-js/faker';
+
+function createRandomUser(): User {
+ const sex = this.faker.name.sexType();
+ const firstName = faker.name.firstName(sex);
+ const lastName = faker.name.lastName();
+ const email = faker.internet.email(firstName, lastName);
+
+ return {
+ _id: faker.datatype.uuid(),
+ avatar: faker.image.avatar(),
+ birthday: faker.date.birthdate(),
+ email,
+ firstName,
+ lastName,
+ sex,
+ subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
+ };
+}
+
+const user = createRandomUser();
+```
+
+As you can see, we changed the order in which we generate our values.
+First, we generate a `sex` value to use it as input for the generation of `firstName`.
+Then we generate the `lastName`.
+Here, we could also pass in the `sex` value as argument, but in our use-case there are no special cases in where a female last name would differ from a male one.
+By doing this first, we are able to pass both names into the `email` generation function.
+This allows the value to be more reasonable based on the provided arguments.
+
+But we can take this even another step further.
+Opposite to the `_id` property that uses an `uuid` implementation, which is unique by design, the `email` property potentially isn't.
+But, in most use-cases, this would be desirable.
+
+Faker has your back, with another helper method:
+
+```ts {7-9}
+import { faker } from '@faker-js/faker';
+
+function createRandomUser(): User {
+ const sex = this.faker.name.sexType();
+ const firstName = faker.name.firstName(sex);
+ const lastName = faker.name.lastName();
+ const email = faker.helpers.unique(faker.internet.email, [
+ firstName,
+ lastName,
+ ]);
+
+ return {
+ _id: faker.datatype.uuid(),
+ avatar: faker.image.avatar(),
+ birthday: faker.date.birthdate(),
+ email,
+ firstName,
+ lastName,
+ sex,
+ subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
+ };
+}
+
+const user = createRandomUser();
+```
+
+By wrapping Faker's `email` function with the [`unique`](../api/helpers.md#unique) helper function, we ensure that the return value of `email` is always unique.
+
+Congratulations, you should now be able to create any complex object you desire. Happy faking 🥳.