Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

AP114 Bundle size optimisations #65

Open
wants to merge 9 commits into
base: main
Choose a base branch
from

Conversation

davecoates
Copy link
Contributor

@davecoates davecoates commented Dec 8, 2024

AP114: Bundle Size Optimisations

This PR introduces significant improvements to how frontend resources are managed, providing greater flexibility
in bundling. With these changes, the default bundle size in the template size is ~75% smaller.

Key Changes:

  1. FrontendResource: A New Abstraction for Resources
    • replaces the previous approach of defining everything as simple paths.
    • Allows more detailed representation of resources, such as ES Modules with specific used exports. This enables the bundler to produce smaller builds.
    • Simplifies filtering of resources based on the resource class, as opposed to guessing the type based on file extensions.
  2. Rename and Update Resource Registry
    • FrontendAssetRegistry is now FrontendResourceRegistry.
    • Enhanced to support adding both FrontendResource instances and paths (paths are still supported for convenience).
  3. New Resource Extraction Method
    • Introduces extract_frontend_resources, which exports used resources in a new, detailed format. This format includes all the necessary metadata for the bundler to leverage additional information (initially just the ES module usage data).
  4. Deprecation of extract_frontend_assets
    • While still functional, extract_frontend_assets is now deprecated in favour of extract_frontend_resources.

I've tested the package in an existing project with no changes to use new interfaces, and it will work but with deprecation warnings.

I will be introducing another MR to the template, and possibly a new @alliancesoftware/ JS package, to handle the build side of this (i.e. the Vite plugin that makes use of the output of extract_frontend_resources). I'll also add a doc page for upgrading once that's done.

@davecoates davecoates requested a review from micahklaz December 8, 2024 06:10
- Introduce `FrontendResource` to represent a resource that will be bundled. This is
  a change from the previous method of defining everything as just a path. This allows
  more flexibility in how resources are handled. For example, we can now represent usage
  of an ES Module as a path and the used exports from that module, which enables the
  bundler to produce a smaller build. It also means we can more easily filter resources
  based on the resource class, whereas before the only thing you can filter on was the
  path (e.g. guess the type from the extension).
- Rename FrontendAssetRegistry to FrontendResourceRegistry and change it to support adding
  resources, not just paths (paths are still supported for convenience).
- Intrduce extract_frontend_resources that will export the used resources in a new format
  containing all the details necessary for the bundler to make use of the extra info.
- extract_frontend_assets still works, but is deprecated
Fix cases where an asset may be treated as undiscoverable incorrectly. This occurs when
using a component as a var, e.g. {% component "package" "MyComponent" as my_var %}{% endcomponent %}
and then passing that as a prop to another component. When the prop is processed in the
component it is passed to it would previously throw an error about it being undiscoverable.
This fix accumulates the known resources as we go, so if the prop is encountered after the
node has been processed it is no longer considered unknown.

This would not have previously caused issues if the prop passed used an import path that was
used in the component (e.g. @alliancesoftware/ui components). With the new changes, this
would be much more common as using a new import from that package would be treated as a
unique usage.
@davecoates davecoates force-pushed the feature/ap114-bundle-size-optimisations branch from 81c1841 to 5a80d26 Compare December 8, 2024 09:20
@davecoates davecoates changed the base branch from main to sys/sphinx-upgrades December 8, 2024 09:20
Allow a full JavascriptResource to cover off on specific imports from that resource

This makes it so adding a path to a file is sufficient to cover off on any imports
used from that file.
@davecoates davecoates changed the base branch from sys/sphinx-upgrades to main December 9, 2024 03:49
Copy link
Collaborator

@micahklaz micahklaz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few typos and doc fixes to address

@davecoates davecoates requested a review from micahklaz December 9, 2024 21:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants