From 8d980ac9a616a6bdc3e765f0c536ba9aeaa41eed Mon Sep 17 00:00:00 2001 From: Shinigami92 Date: Sat, 10 Sep 2022 15:41:57 +0200 Subject: [PATCH] docs: upgrading guide --- docs/.vitepress/config.ts | 17 +--- docs/guide/migration-guide-v5.md | 83 ------------------- .../{migration-guide-v6.md => upgrading.md} | 11 ++- docs/migration/index.md | 53 ------------ 4 files changed, 14 insertions(+), 150 deletions(-) delete mode 100644 docs/guide/migration-guide-v5.md rename docs/guide/{migration-guide-v6.md => upgrading.md} (91%) delete mode 100644 docs/migration/index.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 59e2d1ba22a..a3b716337e5 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -130,25 +130,16 @@ export default defineConfig({ text: 'Getting Started', link: '/guide/', }, + { + text: 'Upgrading to v7', + link: '/guide/upgrading', + }, ], }, { text: 'API', items: apiPages, }, - { - text: 'Migrations', - items: [ - { - text: 'Migrating from Faker v5', - link: '/guide/migration-guide-v5', - }, - { - text: 'Migrating from Faker v6', - link: '/guide/migration-guide-v6', - }, - ], - }, ], '/api/': [ { diff --git a/docs/guide/migration-guide-v5.md b/docs/guide/migration-guide-v5.md deleted file mode 100644 index 13f23c3a9ce..00000000000 --- a/docs/guide/migration-guide-v5.md +++ /dev/null @@ -1,83 +0,0 @@ -# Migrating from Faker v5 to v6 - -## ESM Support - -**New Format**: We're now ESM compatible! We've dropped the Browser bundle in favor of ESM. - -So if you'd like to use `Faker` in the **browser**, simply include it using a [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#applying_the_module_to_your_html). - -```html - -``` - -## Remove all references to `faker` from your project. The new package is located at `@faker-js/faker` - -:::warning -You **MUST** swap all references from the `faker` package to the new `@faker-js/faker` package. - -In addition to releasing all _future_ versions under the `@faker-js/faker` package namespace, we have also provided all _historical_ versions of Faker. - -If you depend on a specific version of Faker you still can reference the version directly. - -`npm i @faker-js/faker@5.5.3 -D` will work just fine 😄. -::: - -## TypeScript - -:::tip TypeScript Improvements -Faker now ships with its own types! Remove `@types/faker` from your `package.json` to avoid conflicts. -::: - -## Tree-shaking - -:::warning -Tree shaking is not yet fully supported due to some structural issues. But we plan to make Faker fully tree-shakable in the future. -::: - -For now Faker supports tree-shaking for some parts, and we highly recommend that you take advantage of your bundler's tree-shaking capabilities and change how you import Faker right now. - -Instead of using: - -```ts -// js -const faker = require('@faker-js/faker'); - -// ts -import faker from '@faker-js/faker'; -``` - -You should switch to: - -```ts -// js -const { faker } = require('@faker-js/faker'); - -// ts -import { faker } from '@faker-js/faker'; -``` - -If you only need one specific language, we highly recommend to make use of the locale specific imports like: - -```ts -// js -const fakerDe = require('@faker-js/faker/locale/de'); - -// ts -import fakerDe from '@faker-js/faker/locale/de'; -``` - -This is especially true if you're importing Faker in the browser. - -Faker is a giant package made up of many megabytes of strings. Only import what you need. - -_We plan to load the locales in another way in a future major release._ - ---- - -Happy Faking! - -- Shini, Jess, and the Faker Team diff --git a/docs/guide/migration-guide-v6.md b/docs/guide/upgrading.md similarity index 91% rename from docs/guide/migration-guide-v6.md rename to docs/guide/upgrading.md index 6a91a1439ff..ac95b6b5f77 100644 --- a/docs/guide/migration-guide-v6.md +++ b/docs/guide/upgrading.md @@ -1,4 +1,13 @@ -# Migrating from Faker v6 to v7 +# Upgrading to v7 + +This is the migration guide for upgrading from v6 to v7. + +::: info +Not the version you are looking for? + +- [v6.fakerjs.dev](https://v6.fakerjs.dev/migration-guide-v5/) + +::: ## Node 12 no longer supported diff --git a/docs/migration/index.md b/docs/migration/index.md deleted file mode 100644 index 6e4be2da63d..00000000000 --- a/docs/migration/index.md +++ /dev/null @@ -1,53 +0,0 @@ -# Migration from faker.js v5 - -There are now two bundles: `cjs` and `esm` - -The browser bundle was dropped in favor of `esm` - -So if you like to use `Faker` in the **browser**, just use: - -```html - -``` - -A stackblitz playground can be found here: https://stackblitz.com/edit/typescript-damv7h - -:::tip -Faker now provides TypeScript types out of the box. -So you can remove `@types/faker` completely. -::: - -You no longer need to import `faker` as a standard import, but as a tree shakeable instance. - -For JS: - -```js -const { faker } = require('@faker-js/faker'); - -// Or specific locale -const fakerDe = require('@faker-js/faker/locale/de'); -``` - -For TS: - -```ts -import { faker } from '@faker-js/faker'; - -// Or specific locale -import fakerDe from '@faker-js/faker/locale/de'; -``` - -:::tip -If you have many files using these imports, we suggest to use e.g. VSCode's search and replace functionality. -::: - ---- - -:::warning -You need to switch from the package `faker` to `@faker-js/faker`. -We also provided all historical versions under the new organization scope. So if you depend on a specific version you still can use `"@faker-js/faker": "5.5.3"`. -:::