[RFC] ESM bundling

[marklundin]

Support for ESM bundling

Note

ESM bundling does not attempt to fundamentally rewrite the playcanvas export format. Only what is necessary to have bundled scripts

This is a WIP progress ticket to track and discuss bundling for ESM based projects

As the engine and editor will soon support ES Modules playcanvas/engine#4767, users should be able to export bundled versions of projects with ESM Scripts. This can improve network load by providing optimised builds that end users have control over.

Requirements

• Bundling ESM projects for both download and published apps.
• Backwardly compatible with existing projects. (Does not change the export pipeline for current projects)
• Alllows gradual migration. Compatible with projects containing boths classic and esm scripts together.
• Bundles bootstrap, engine and user code together into a single build.
• Supports code splittings (split by preload/split by scene) for optimising load/cache
• Supports modern bundling features (tree shaking/symbol replacement/transforms)
• Obeys minify and concatenation editor options (concatenate false: creates separate files, but still tree-shaken etc)

Remaining Tasks

• Bundle published apps
• Bundle downloaded apps
• Bundle loading screen
• Verify code splitting strategies
• Concatenations / minification
• Export source maps
• Surface build errors to editor
• Support custom loading screen work

User configuration

Update: We've opted for user build configuration to be presented in the export UI dialog as opposed to a separate congfig. This is mainly for UX consistency with how export options are currently presented.

This can be specified using a simple build.json in the root of the project, if none are found we use a pre-defined set of options.

Additionally users can define a debug.build.json used in the launcher. This will allow user to configure different environments depending on the environment.

Code Transformation/Transpiling

Bundling will support basic code transformations, starting with minimal initial transforms like stripping debugger statements etc. Over time, we may expand this to include other transformations, such as TypeScript. Each addition will be evaluated on a case by case basis.

However, we don’t plan to support broad code lowering (e.g., Babel et al). Supporting every possible browser target and language feature would be unmanageable. Instead, we’ll focus on a common baseline and let users decide the language features to use specific to their needs. We’re also exploring the option for users to download the project’s source with the same ESM bundler, enabling custom transformations like Babel for local use.

Breaks rest-api-tools

See playcanvas/playcanvas-rest-api-tools#50 for more information

[Maksims]

This can be specified using a simple build.json in the root of the project, if none are found we use a pre-defined set of options.

Can you please clarify this?
Does it require creating a JSON asset by the user?

[marklundin]

Yep to override build options etc, otherwise it will just default to some predefined ones.

[Maksims]

Yep to override build options etc, otherwise it will just default to some predefined ones.

As the Editor has the benefits of having UI, this is better to be implemented as UI elements. Otherwise, there are a couple of issues:

1. Extra file loading.
2. Discoverability - how to discover it is there, what options are supported, etc? UI solves it.
3. Human factor - humans do type the wrong JSON.

[marklundin]

This work has now been completed.