From b5afdbe3c81879fc091d19cf724e5b1e7cb9d4d8 Mon Sep 17 00:00:00 2001
From: Shinigami92 <chrissi92@hotmail.de>
Date: Mon, 24 Jan 2022 20:55:04 +0100
Subject: [PATCH 1/2] docs: provide migration guide

---
 docs/.vitepress/config.mjs |  4 ++++
 docs/migration/index.md    | 43 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 docs/migration/index.md

diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
index c824f327589..5794d259aef 100644
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -78,6 +78,10 @@ const sidebar = {
         },
       ],
     },
+    {
+      text: 'Migration from faker.js v5',
+      link: '/migration/',
+    },
   ],
 };
 
diff --git a/docs/migration/index.md b/docs/migration/index.md
new file mode 100644
index 00000000000..69a0c414b4d
--- /dev/null
+++ b/docs/migration/index.md
@@ -0,0 +1,43 @@
+# 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
+<script type="module">
+  import { faker } from 'https://unpkg.com/@faker-js/faker';
+
+  console.log(`${faker.name.firstName()} ${faker.name.lastName()}`);
+</script>
+```
+
+A stackblitz playground can be found here: https://stackblitz.com/edit/typescript-damv7h
+
+---
+
+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.
+:::

From db1ac23f9f2e343f80ca003d84c716bea06c2192 Mon Sep 17 00:00:00 2001
From: Shinigami92 <chrissi92@hotmail.de>
Date: Mon, 24 Jan 2022 21:01:14 +0100
Subject: [PATCH 2/2] chore: add more stuff

---
 docs/migration/index.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/migration/index.md b/docs/migration/index.md
index 69a0c414b4d..6e4be2da63d 100644
--- a/docs/migration/index.md
+++ b/docs/migration/index.md
@@ -16,7 +16,10 @@ So if you like to use `Faker` in the **browser**, just use:
 
 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.
 
@@ -41,3 +44,10 @@ 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"`.
+:::