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 🥳.