build: bundle with esbuild (#257)

.eslintignore

@@ -1 +1 @@
-lib/
+dist/

.prettierignore

@@ -1,7 +1,5 @@
 coverage/
 dist/
-doc/
-examples/browser/js/
-lib/
 CHANGELOG.md
+CHANGELOG_old.md
 pnpm-lock.yaml

CONTRIBUTING.md

@@ -1,23 +1,21 @@
-A lot of effort has been put into `Faker` to create a useful and handy
-library. There are still a lot of things to be done, so all contributions are welcome! If you can make `Faker` better, please read the following contribution guide.
+A lot of effort has been put into `Faker` to create a useful and handy library.
+There are still a lot of things to be done, so all contributions are welcome!
+If you want to make `Faker` a better, please read the following contribution guide.
 
 # Important
 
-- Please make sure that you run both `gulp` and tests before making a PR.
+- Please make sure that you run `pnpm install`, `pnpm run build` and `pnpm run test` before making a PR to ensure that everything is working from the start.
 
-## Support
+## Good to know
 
-`Faker` relies on [commonJS](http://www.commonjs.org/) standard and supports both node.js and the browsers. Keep this in mind, when modifying and/or extending the sources.
-
-## Automation
-
-- The project is being built by [gulp](http://gulpjs.com/) (see [gulpfile](build/gulpfile.js)), destination directory is [build/build](build/build)
-- The documentation is auto-generated, based on [build/src](build/src) markdown sources. If you modify the main [Readme.md](Readme.md) file, the Pull Request will be rejected, since it will be overwritten by the upcoming `gulp` execution
+- The project is being built by [esbuild](https://esbuild.github.io) (see [bundle.ts](scripts/bundle.ts))
+- The documentation is running via VitePress.
+  Make sure you **build** the project before running the docs, cause some files depend on `dist`.
+  Use `pnpm run docs:dev` to edit them in live mode.
 - The tests are executing `vitest` against `test/**/*.spec.ts`
 
 ## Architecture
 
-The sources are located in the [lib](lib) directory. All fake data generators are
-divided into namespaces (each namespace being a separate module). Most of the
-generators use the _definitions_, which are just plain JavaScript
-objects/arrays/strings that are separate for each [locale](lib/locales).
+The sources are located in the [src](src) directory.
+All fake data generators are divided into namespaces (each namespace being a separate module).
+Most of the generators use the _definitions_, which are just plain JavaScript objects/arrays/strings that are separate for each [locale](src/locales).

README.md

@@ -46,17 +46,20 @@ pnpm install @faker-js/faker -D
 ### Node.js
 
 ```js
-const faker = require('@faker-js/faker');
+const { faker } = require('@faker-js/faker');
 const randomName = faker.name.findName(); // Rowan Nikolaus
 const randomEmail = faker.internet.email(); // Kassandra.Haley@erich.biz
 const randomCard = faker.helpers.createCard(); // random contact card containing many properties
 ```
 
 ### TypeScript Support
 
-Types are available via the `@types/faker` package. You must manually link them using a `*.d.ts` file, like so:
+Since version `v6+` there is native TypeScript support.
 
-```typescript
+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';
@@ -462,14 +465,11 @@ console.log(firstRandom === secondRandom);
 
 ### Building Faker
 
-Faker uses [gulp](http://gulpjs.com/) to automate its build process. Each build operation is a separate task which can be run independently.
-
-### Browser Bundle
+The project is being built by [esbuild](https://esbuild.github.io) (see [bundle.ts](scripts/bundle.ts))
 
 ```shell
 pnpm install
 pnpm run build
-pnpm run browser
 ```
 
 ### Testing
@@ -488,27 +488,27 @@ You can view a code coverage report generated in `coverage/index.html`.
 ### Developing the docs
 
 ```shell
-# build the Faker library for the browser
+# build the Faker dist
 # it's used inside of certain routes
-pnpm run browser
+pnpm run build
 
 pnpm run docs:dev
 ```
 
 ### Building and serving the docs statically
 
 ```shell
-# build the Faker library for the browser
+# build the Faker dist
 # it's used inside of certain routes
-pnpm run browser
+pnpm run build
 
 pnpm run docs:build # Output docs to /dist
 pnpm run docs:serve # Serve docs from /dist
 ```
 
 ### Deploying Documentation
 
-The website is kindly hosted for free by the Netlify team under their Open Source plan. See the netlify.toml for configuration.
+The website is kindly hosted for free by the Netlify team under their Open Source plan. See the [netlify.toml](netlify.toml) for configuration.
 
 ## What happened to the original faker.js?
 

docs/.vitepress/theme/components/Playground.vue

@@ -1,18 +1,11 @@
 <script setup>
-import { ref } from 'vue';
+import { faker } from '../../../../dist/esm';
 
-const faker = ref();
-const ready = ref(false);
-
-import('../../../../dist/faker').then((_faker) => {
-  window.faker = _faker.default;
-  faker.value = _faker.default;
-  ready.value = true;
-});
+window.faker = faker;
 </script>
 
 <template>
   <h2>🚧 Playground under construction 🚧</h2>
   <h3>window.faker</h3>
-  <pre v-if="ready">{{ Object.keys(faker) }}</pre>
+  <pre>{{ Object.keys(faker) }}</pre>
 </template>

docs/guide/index.md

@@ -68,9 +68,9 @@ const randomCard = faker.helpers.createCard(); // An object representing a rando
 ```
 
 :::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 around `1.57 MB` minified. **Please avoid deploying Faker in your web app.**
+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 Faker in your web app.**
 :::
 
 ## Community
 
-If you have questions or need help, reach out to the community via Discord and GitHub Discussions.
+If you have questions or need help, reach out to the community via [Discord](https://discord.com/invite/4qDjAmDj4P) and [GitHub Discussions](https://github.com/faker-js/faker/discussions).

package.json

@@ -7,7 +7,6 @@
     "faker.js",
     "fakerjs",
     "faker-js",
-    "marak",
     "fake data generator",
     "fake data",
     "fake-data",
@@ -22,23 +21,43 @@
     "url": "https://github.com/faker-js/faker.git"
   },
   "license": "MIT",
-  "main": "lib/index.js",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "index.d.ts",
+  "typesVersions": {
+    ">=4.0": {
+      "*": [
+        "dist/types/*"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "node": "./dist/cjs/index.js",
+      "es2015": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./locale/*": {
+      "node": "./dist/cjs/locale/*.js",
+      "es2015": "./dist/esm/locale/*.js",
+      "default": "./dist/esm/locale/*.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "CHANGELOG.md",
     "CHANGELOG_old.md",
     "dist",
-    "index.d.ts",
-    "index.js",
-    "lib",
-    "locale",
     "tsconfig.json"
   ],
   "scripts": {
     "preinstall": "npx only-allow pnpm",
-    "build": "tsc",
-    "browser": "gulp browser",
+    "build:clean": "rimraf dist",
+    "build:code": "esno ./scripts/bundle.ts",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist/types",
+    "build": "run-s build:clean build:code build:types",
     "docs:build": "vitepress build docs",
-    "docs:build:ci": "run-s build browser docs:build",
+    "docs:build:ci": "run-s build docs:build",
     "docs:dev": "vitepress dev docs",
     "docs:serve": "vitepress serve docs",
     "format": "prettier --write .",
@@ -54,33 +73,24 @@
     "*": [
       "prettier --write --ignore-unknown"
     ],
-    "/lib/**/*.{js,ts}": [
+    "/dist/**/*.{js,ts}": [
       "eslint --ext .js,.ts"
     ]
   },
   "devDependencies": {
     "@vitest/ui": "~0.1.24",
-    "browserify": "^16.5.2",
     "c8": "~7.11.0",
     "conventional-changelog-cli": "~2.2.2",
+    "esbuild": "~0.14.13",
     "eslint": "^6.5.1",
     "esno": "~0.13.0",
-    "gulp": "^4.0.2",
-    "gulp-gh-pages": "^0.5.4",
-    "gulp-rename": "^2.0.0",
-    "gulp-uglify": "^3.0.2",
-    "ink-docstrap": "1.1.4",
     "lint-staged": "~9.5.0",
     "npm-run-all": "~4.1.5",
-    "optimist": "0.3.5",
     "picocolors": "~1.0.0",
     "prettier": "2.5.1",
+    "rimraf": "~3.0.2",
     "simple-git-hooks": "~2.7.0",
-    "through2": "2.0.0",
-    "typescript": "~4.5.4",
-    "vinyl-buffer": "^1.0.1",
-    "vinyl-source-stream": "^2.0.0",
-    "vinyl-transform": "^1.0.0",
+    "typescript": "~4.5.5",
     "vite": "~2.7.13",
     "vitepress": "^0.21.4",
     "vitest": "~0.1.24"