Page MenuHomePhabricator

Create a basic "Hello world" example of how to use Codex in a user script
Open, Stalled, Needs TriagePublic3 Estimated Story Points

Description

Like T330350, but as a user script. See also T307487, which did some exploration in this area.

Current issues

Using Vue and Codex in userscripts is going to be all but blocked by T75714: Update JavaScript syntax checker for gadgets and user-scripts for ES6 and later.

Gadgets and Userscripts rely on an outdated JS syntax validator which is written in PHP. This library doesn't support modern (ES6 and beyond) JS syntax, meaning that userscripts which include ES6 features will automatically fail.

Some work was done to allow individual Gadgets to opt-out of this validation, but for userscripts this is not possible (because there is no way to define metadata for a userscript, it's just a wiki page with a JS extension in the user namespace).

The "best" experience for writing Vue/Codex code involves using Vue's single-file component feature (.vue files). This allows template, script, and styling for a single component to all be defined in the same file. Developers who are working in MW Extensions can use .vue files (ResourceLoader supports them), and hopefully we'll enable this for Gadgets as well.

There are alternatives to using single-file components that involve using ES6 template strings (which can be multi-line, suitable for writing template markup). Another alternative would be to add a <script> tag to the page with type="x-template", where the body of the script tag contains the template markup for Vue to use. This markup won't be visible until Vue is loaded.

Unfortunately, I don't think MW allows users to arbitrarily add <script> tags to pages, and if ES6 template literals are also disallowed, then we are left with no good way to define component templates. Users would have to write everything inside a single-line string literal (good luck using any complex markup), or would need to resort to manual render() functions (an advanced technique not suitable for beginners).

So until there is a way to get around enforcement of (now quite outdated) ES5 validation, using Vue and Codex in the context of userscripts is not something I would recommend – you are better off just using OOUI and jQuery.

Potential solutions
  • Figure out a way to disable the existing validator for userscripts (some? all? which ones? Unlike Gadgets, Userscripts don't have a way to define metadata where you could specify something like es6: true)
  • Upgrade the JS validator to something that supports more modern (ES6 and beyond) JS syntax. Unfortunately, nothing like this exists in PHP, so you'd need to shell out to another program to do this. Introducing the ability to use a Node runtime (per T328699: Consider including a JS runtime as part of MediaWiki) could potentially help here as there are many JS validation libraries in the Node ecosystem that we could choose from.

Event Timeline

Restricted Application triaged this task as High priority. · View Herald TranscriptApr 11 2023, 1:13 AM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
egardner changed the task status from Open to Stalled.Apr 12 2023, 10:54 PM
egardner updated the task description. (Show Details)
egardner set the point value for this task to 3.

Gadgets and Userscripts rely on an outdated JS syntax validator which is written in PHP. This library doesn't support modern (ES6 and beyond) JS syntax, meaning that userscripts which include ES6 features will automatically fail.
Some work was done to allow individual Gadgets to opt-out of this validation, but for userscripts this is not possible (because there is no way to define metadata for a userscript, it's just a wiki page with a JS extension in the user namespace).

This is not correct. ES5 syntax validation is applied only for the entry points to user scripts (User:Example/common.js, /vector.js, etc) – but these are just entry points that are supposed to contain a bunch of importScript statements. The user scripts themselves are fetched over HTTP – without going through ResourceLoader. You might as well use ES2022 in user scripts!

The limitation is that it's not possible to use package files in user scripts. Components either need to be in the same file, or if put in a separate file that will have to be fetched with yet another http call.

Gadgets and Userscripts rely on an outdated JS syntax validator which is written in PHP. This library doesn't support modern (ES6 and beyond) JS syntax, meaning that userscripts which include ES6 features will automatically fail.
Some work was done to allow individual Gadgets to opt-out of this validation, but for userscripts this is not possible (because there is no way to define metadata for a userscript, it's just a wiki page with a JS extension in the user namespace).

This is not correct. ES5 syntax validation is applied only for the entry points to user scripts (User:Example/common.js, /vector.js, etc) – but these are just entry points that are supposed to contain a bunch of importScript statements. The user scripts themselves are fetched over HTTP – without going through ResourceLoader. You might as well use ES2022 in user scripts!

The limitation is that it's not possible to use package files in user scripts. Components either need to be in the same file, or if put in a separate file that will have to be fetched with yet another http call.

Interesting, I wasn't aware of this (haven't worked with userscripts much so far). In that case, a userscript author who wanted to use Vue & Codex could use ES6 template literals with the template option to provide markup, or they could define a render() function manually. This is still not ideal (it would be better if we could provide the same level of support for PackageFiles and .vue single-file components that we do in ResourceLoader).

If it's not feasible for us to make changes in Gadget/Userscript infrastructure for now, then we could document these workarounds somewhere.

Task for adding support for package files and other RL features in the user scripting setup is T36958.

Task for adding support for package files and other RL features in the user scripting setup is T36958.

It doesn't look like this task (which comes with a functional and near-complete patch!) is going to get anywhere without some level of support from WMF. @egardner Is this something your team would be interested in?

Task for adding support for package files and other RL features in the user scripting setup is T36958.

It doesn't look like this task (which comes with a functional and near-complete patch!) is going to get anywhere without some level of support from WMF. @egardner Is this something your team would be interested in?

Hey @SD0001, thanks for the task link. I was not aware of this proposal – it's interesting, but this is bigger in scope than what my team (Design Systems) is currently considering. Our medium-term goal is captured here: T313945: [EPIC] Enable gadget and user-script developers to use Vue and Codex.

I see the underlying motivation as similar though – empowering user-script authors and simplifying their workflows.

I anticipate that we will be spending more time on T313945 a bit later this year. If that work will necessitate changes to the underlying Gadget/Userscript infrastructure anyway (which it might) then it may make sense to also consider other proposals like T36958. We'll want to minimize the impact on existing workflows as much as possible of course; changes that are not backwards-compatible are probably not feasible.

CCiufo-WMF raised the priority of this task from High to Needs Triage.Dec 8 2023, 11:38 PM
CCiufo-WMF moved this task from Needs Refinement to Backlog on the Design-System-Team board.