Tree-shaking not properly documented

[Fuzzyma]

Describe the bug

Following the guide on the website, you just have to import { faker } from '@faker-js/faker';. That doesn't work. It actually makes it worse by adding a whopping 1/2MB to the bundle size.

The section above says, that you should only import what you need. Well I tried that as well:

import { address } from '@faker-js/faker' // error, no export address
import address from '@faker-js/faker/address'

address.city() // error, method not defined

So is this is supposed to work? Looking at the code, I can see why this is not treeshakeable. But why is it advertized?

Reproduction

I am using vite. So bundling is done by rollup. Using faker anywhere leads to the whole faker lib in your bundle

Additional Info

No response

[ST-DDT]

This feature was supposedly added in #152
@Shinigami92 Do you have a hint what might have went wrong in the meantime/this usecase?

[Shinigami92]

import { faker } from '@faker-js/faker'; should work from 6.0.0-alpha.5 I think
Before it was import faker from '@faker-js/faker'; or import * faker from '@faker-js/faker';
And that's what I currently mean by "tree-shakeable"
Beside that it's currently possible to use and load only a specific locale with fallback to en by using e.g.: import fakerDe from '@faker-js/faker/locale/de';

This will and should reduce the loaded size to only the needed locale.

---

Something like import { address } from '@faker-js/faker'; will not work and it would be a long way to support something like this (maybe someday in v8, v9 or v10 🤷)
But as e.g. address needs the faker instance in it's constructor and referencing stuff around, it's not possible to just give only the address module back.

[ST-DDT]

Or does it only refer to per language shaking?
Only support a single locale by using:

import fakerDe from "@faker-js/faker/locale/de";
console.log("a", fakerDe.name.jobType()); // Orchestrator

[ST-DDT]

We should be more explicit about the treeshaking behavior/limitations in our docs to avoid any confusion about this in the future.

The documentation should be updated to contain:

• Information about the things that support treeshaking (locale specific fakers only AFAICT)
• Estimates on how much you can safe by using the feature
• An example/hint using only a specific locale.

[Fuzzyma]

Well I DID use import {faker} from ... and it increased my bundle size compared to the last version of the original faker. Is it including all locales like this? I only want english.

Also: yes, proper treeshaking isn't that easy but also isn't that hard. separating the different faker modules would already help a lot. Ofc, the premium would be to only import the actual functions you need e.g. import {city} from '@faker-js/faker/address'

[Shinigami92]

I only want english.

@Fuzzyma Please try to use import fakerEn from '@faker-js/faker/locale/en'; for now

[ST-DDT]

Well I DID use import {faker} from ... and it increased my bundle size compared to the last version of the original faker.

Probably because we link a few more entries now that existed in the sources but where never added to the translation tree.

Is it including all locales like this?

Yes.

faker/src/index.ts

Lines 150 to 152 in 773bcec

	export const faker: Faker = new Faker({
	locales: allLocales,
	});

EDIT: @Shinigami92 is always a few seconds faster...

[ST-DDT]

This needs to be in the v6.0 release version, to avoid confusion and frustration when switching to this lib.

[JessicaSachs]

Before I started writing documentation, I wanted to make sure I was giving the right guidance on how to import things performantly.

To make sure I was getting it right, I started using size-limit to get a handle on what the size differences of the different imports would be for CJS and ESM. I found that no matter what I did, I couldn't get the bundle size down past ~600 kB compressed + minified. I thought I might be misconfiguring size-limit so I went ahead and created a tiny Vite project, but found that no matter what I did, all of the locales were being bundled -- even if I only imported the en locale directly.

So I started digging into why the bundle was including all locales.

If you turn minification off and trace through the imports, you'll see that dist/esm/locale/en.js ends up importing { init_src } which is a function that has references to all locales. I don't think tree-shaking is working at all per-locale.

I started making some changes to test out my theory and we should be getting around ~207.64 kB compressed + minified if only english is loaded.

I'll continue exploring this, but making changes is a bit difficult because of how much codegen is being done on the locales and the way they're exported.

[Shinigami92]

I will have a look into this init_src later, but let's remove documentation about tree-shaking for now and address it later in a future milestone.
Due to how the project is structured right now it is too complicated to just make it support that quickly.

[ST-DDT]

Maybe we have to move the Faker class to its own file. That way we don't have to import the index.ts file which contains the faker instance with all locales.

[Shinigami92]

Maybe we have to move the Faker class to its own file. That way we don't have to import the index.ts file which contains the faker instance with all locales.

As we wanted to do this anyways, I will open a PR for that now. But I'm not sure if this really will work 🤔
I think the issue lies deeper in the structure of the whole project like the Faker class contains instances of all its modules and how it is coupled.
For the languages a planned to load them from language files instead of TypeScript source files. But this is so far away from now like v7, v8, or v9 🤷 but I will open an issue for that, so it can be somehow planned

[Shinigami92]

Rewrite docs for tree-shaking: #549