The new Vue.js search experience also marks the beginning of a Wikimedia Vue.js component library. Components therein have great aspirations including that they be:
- Efficient to develop, meeting the expectations of modern developers, and encouraging of a welcoming culture.
- Sharable and reusable in any context within and without Wikimedia in development and production.
- Easily composable in any combination.
- Responsive.
- Performant both in terms of bandwidth and computationally.
- Accessible (including screen readers and keyboards).
- Localizable.
- Tested.
- Renderable in any context within and without a browser.
- Documented.
- With accurately typed, well-defined, and semantically versioned APIs.
- User-friendly styled.
- Intelligently divided with explicit dependencies to serve different use cases.
- Strongly patterned, idiomatic, and intentional; components are designed consistently and cohesively.
- Favoring composition over inheritance.
Many of these goals were identified as shortcomings of T225453 or requirements in T225572, both of which were inputs to and a supporting rationale for the Vue.js RFC itself. These guiding principles are not impossible and, in the long-term, are not merely aspirational but necessary. The initial components for the new Vue.js search experience will probably fall short but nevertheless, we do not wish to repeat past mistakes and hold these objectives dear.
An initial decision that greatly impacts our ability to meet these goals is language. This task explores the tradeoffs of uncompiled and compiled options within the remits of responsible, deliberate, and isolated experimentation that the broader case study objectives this project is expected to meet to be considered successful.
This decisioning is partly dependent on the outcome of T249350 and it's implementation is informed by T249051.
Uncompiled ES5
Notable examples
Pros
- Components built in ES5 are universally usable in any context including ResourceLoader, gadgets, and user scripts. No abstractions. What you write is what you ship. No bundling required.
- JSDocs provide some type checking without compilation and are more common in Wikimedia currently.
- Every web developer has basic ES5 comprehension.
- All documentation except for WMDE's can be written in the same coding language (ES5).
- The most conservative option.
Cons
- No abstractions. What you write is what you ship with little flexibility. There are few programmer accomodations available.
- JSDocs are verbose and provide limited type checking. A lot of documentation is not actually JSDocs but instead the similar but frustratingly different JSDuck, including all of Core and OOUI.
- Code is dated in appearance and fundamental language features like let.
Compiled language
Notable examples
- ContentTranslation
- WMDE (Wikidata Bridge, vuejs-components, wikibase-termbox, Tainted references)
- Prototype
Pros
- As is the case for T249350, Web can build on past experience to help establish improved patterns for the broader organization (e.g., Popups, MobileFrontend, and Vector Storybook). Web would be in a position to share expertise outwards. Popups most of all has some of Web's best code and this is due in part to its modern language choice and intentionally progressive design. We should continue to build on that work.
- Compiled languages allow for canonical Vue.js and meet the expectations of modern developers including: Vue.js directive and ES6 shorthands are supported, templates are precompiled and scoped styles are supported.
- ES6 and TypeScript better meet the expectations of modern developers that would like to participate.
- As noted for ES5, JSDocs can also be used for ES6. TypeScript provides a significantly richer and more accurate typing experience that is also less verbose, "free" unit tests for all types, and a significantly better IDE experience.
- An improved TypeScript experience via the composition API is one of the prominent major new features in Vue 3 and may be expected by third-party or incoming Vue.js developers.
- As informed by T249350, the output consumed in MediaWiki is an NPM package or compiled output. Since the output is ES5, it works everywhere.
- WMDE is using TypeScript extensively for their components and Vue.js work. Using TypeScript may allow many existing components to be reused and avoid significant technical debt (ref 0, ref 1, ref 2)
- Vector already has the functionality for adding TypeScript as wanted. If a new repo is used, this configuration could easily be replicated.
- TypeScript is well aligned with Vue's standard prop validation but occurs at compilation time instead of run time and is universal, not just for props. See related discourse on using mutations to force typing at run time.
Cons
- As is the case for T249350, more work lands on Web define good patterns others to use as wanted.
- Compiled code is not the current definition of canonical MediaWiki code.
- Compiled code does not meet the expectations of some MediaWiki developers that would like to participate. For example, not everyone knows what fat arrow functions are or how to annotate types. There's a learning curve!
- Vue 3 ain't released yet and the Vue 2 mixin experience doesn't work well with types.
- Implies bundling and more build time dependencies.
Acceptance criteria
- A decision is made for the Vue.js search project.
- Feedback on this decision is solicited in the developer survey. (This means adding some nicely formed question(s) to the survey task.)
- Any new task(s) needed to support the decision are made. E.g., Browserlist and ES5 config.
- Documentation on wiki is revised with any learnings.