Background

We currently lack a way within MediaWiki to perform code-splitting (aka tree-shaking) on the main Codex JS and CSS files.

As of Codex v0.9, the production build of the library generates a JS file that is around 72KB and a CSS file that is 54KB. GZIP compression can reduce the over-the-wire transfer size a bit further, but we are still talking about a sizeable amount of code that must be loaded and executed by the user's browser. Over time, these files will continue to grow as new components get added to the library.

We want to see Codex used to develop more and more features around the Wikimedia ecosystem, but currently there is no good way within MediaWiki for a feature using Codex to only deliver the CSS or JS code that is actually needed by that feature – we can only ship the entire CSS & JS files. Since the advent of CSS-only Codex components (see T325105), we've made it possible to load CSS styles independently of Codex JS, but there is currently no level of granularity beyond this.

In many situations, it will never be acceptable to ship dozens or hundreds of kilobytes of unused code to the user's browser. Our inability to optimize the Codex bundle files based on the needs of particular features will thus remain a significant barrier to adoption until we can figure out a solution.

Previous workarounds and potential solutions

In the past, various potential workarounds have been explored:

• T248718: Provide performance guidelines on when and how to load code including Codex on article namespace
• T289208: Develop and document a proposal for when to use Vue/Codex
• T286835: Port RelatedArticles to Codex
• T323180: [SPIKE] Determine how to mitigate performance concerns for CSS-only components
• etc.

We have also explored some potential solutions to this problem, for example:

• T334986: [Proposal] Create a new "codex-mw" package for shared MediaWiki-specific components
• T279108: Introduce a Front-end Build Step for MediaWiki Skins and Extensions
• T328699: Consider including a JS runtime as part of MediaWiki

Current status quo

Practically, our current status-quo amounts to doing the following:

• Limiting use of Vue and Codex to Special pages and other non-critical parts of MediaWiki
• Building a dedicated bundle upstream for the codex-search feature which is needed by the Web team (this complicates our build system, see T335302: Improve / simplify Codex build system ) and then relying on a lot of complicated code in Vector to ensure that the TypeaheadSearch component is loaded at the last possible moment (see T322077: Lower the maintenance costs of TypeaheadSearch in Vector for some issues with this)

The current de-facto solution we have in place is not scalable and is a burden to maintain – and until we can come up with a more generally-applicable solution, adoption of Codex is going to be limited.

I think that we need to decide on a way to solve this problem soon – even if that means committing ourselves to some relatively involved technical work that will take a long time to complete (build step / node runtime). If it's going to be a long time before any "ideal" solution is ready, we may need to come up with a good short-term solution (for example, see T334986: [Proposal] Create a new "codex-mw" package for shared MediaWiki-specific components and T335302: Improve / simplify Codex build system for things we can do now). Regardless of what solution we settle on, we should decide on something soon and write an ADR about it (and possibly other documentation) so that this issue does not continue to block both our work and the work of other WMF teams.

Next Steps

1. Clean up our existing build infrastructure to open up the possibilities for how we might want to deliver builds in the future (T335302).
2. Do an inventory of areas of WMF projects where we believe or know Codex usage would not currently be possible due to the current bundle size and the way builds are structured (T335785).
3. Pick a solution and a specific use case we can prototype against that we can deliver this quarter that validates the approach we’re taking (T335792).