[Decorators][Docs] Clarify that modern decorator usage will increase TypeScript project bundle size

[chadsowald]

Clarified that using modern decorators will increase the output bundle size for TypeScript projects.

I ran into this on my project after upgrading from legacy decorators. I wanted to add this to the docs so others don't have to find out the hard way. Once ESNext is supported by major browsers, though, it will be great!

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6b08279

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[mweststrate]

Would you mind quantifying the change, and where it comes from? How it is formulated is pretty clear whether a) it is 100 bytes or 100 KB, and b) whether this is a shared resource like polyfills or something else. Mind charing the difference in transpiled output?

[chadsowald]

@mweststrate definitely! Here's some examples from the TypeScript Playground - rather than my specific project's code - that illustrates the tradeoff. Would you like me to include these details in the doc update too, or just here?

With experimentalDecorators on + ES2023

With experimentalDecorators off + ES2023

With experimentalDecorators off + ESNext

You can see that web projects following the migration guide to "modern decorators" would be hit by the diff between the first 2 links above. Then, whenever ESNext is released and enough browsers support modern decorators, then we'll all benefit from the size reduction in the 3rd link. At least, I think that's my understanding.

Does that seem about right?

It's hard to quantify the overall size impact as it depends on how much decorator use there is and how large the project is.

In my case, my project heavily uses mobx decorators and the move to modern decorators added ~40kb after compression! But is has many stores, observables, and more.