Extension:GrowthExperiments/Technical documentation/Frontend

Client modules map Edit

ResourceLoader Module Usage Server side rendering Base UI components Custom UI components Notes
ext.growthExperiments.Account Set up ULS for WelcomeSurvey; show confirm email in Special:CreateAccount MessageBox


ext.growthExperiments.Account.styles Style elements in ext.growthExperiments.Account, custom landing pages, Special:Contributions
ext.growthExperiments.DataStore Manage states for filters and newcomer tasks
ext.growthExperiments.Help Ask help dialog; contents of the help panel Layouts (PanelLayout, IndexLayout, StackLayout)

ProcessDialog SearchInputWidget

ext.growthExperiments.HelpPanel Help panel CTA, help panel popup; suggested edits guidance HelpPanelButton


ext.growthExperiments.Homepage.ConfirmEmailNotice Show a notification after the user confirms their email
ext.growthExperiments.Homepage.Impact Homepage module; Show page views for edited articles (activated) or open suggested edits (unactivated) PopupButtonWidget
ext.growthExperiments.Homepage.Logger Logger class for homepagemodule schema
ext.growthExperiments.Homepage.Logging Set up logging for homepage modules
ext.growthExperiments.Homepage.Mentorship Homepage module; Show questions posted to mentor; opt in/out of mentorship ButtonMenuSelectWidget


ext.growthExperiments.Homepage.mobile Set up mobile overlays for homepage modules MobileOverlay (MobileFrontend)

Drawer (MobileFrontend)

Maybe it's worth considering splitting out the overlays from the server-side rendered view
ext.growthExperiments.Homepage.styles Style server-side rendered elements of the homepage
ext.growthExperiments.Homepage.SuggestedEdits Homepage module; suggested edits feed and filters ProcessDialog

PanelLayout PopupButtonWidget MessageWidget SwipePane

ext.growthExperiments.HomepageDiscovery Show banner w/instructions on how to back to Special:Homepage; Remove mobile discovery banner after it's been closed
ext.growthExperiments.MentorDashboard Allow mentors to manage their mentees, their mentorship status mw.widgets.UserInputWidget


There's room for improvement in the UI in terms of mobile/responsive layouts and loading/progress feedback to users
ext.growthExperiments.MentorDashboard/MenteeOverview Browse mentees, see mentee stats Inputs (NumberInput, ButtonSelect, CheckboxInput) FilterDropdown
ext.growthExperiments.MentorDashboard/MentorTools Claim mentees, set mentor availability Select (Browser native), Dialog
ext.growthExperiments.MentorDashboard/Resources Lists useful links for mentors Could be a candidate for experimentings with custom SSR on PHP. That means building a mustache template in the server that matches the generated HTML of a Vue component.
ext.growthExperiments.PostEdit Show dialog upon task completion MessageWidget CollapsibleDrawer
ext.growthExperiments.StructuredTask Base classes for structured tasks VE classes
ext.growthExperiments.StructuredTask.desktop Desktop-specific classes for structured tasks VE classes
ext.growthExperiments.StructuredTask.mobile Mobile-specific classes for structured tasks VE classes
ext.growthExperiments.StructuredTask.PreEdit Check for structured task eligiblity; show onboarding dialog (mobile) ProcessDialog MultiPaneDialog


Might be a good candidate if we have the dialog component but since the onboarding is bundled w/StructuredTask module, we may need to research bundling Vue-based modules with VE
ext.growthExperiments.SuggestedEditSession Manage states for suggested edits

Disclaimer: the table is not updated since May 2022

Unit testing Edit

The GrowthExperiments extension client code can and should be tested with one of MediaWiki's preferred runners: jest or qunit. Specifically Jest is used for running Vue components unit tests and QUnit for running other Javascript scripts. QUnit tests live under the folder tests/qunit whereas Jest tests are normally placed in source directories by the side of the script they are testing. The current CI setup (tbd: add reference to doc/sources) will execute both kinds of tests whenever a change is pushed to gerrit. Sadly there's not a single command (yet) to run them all from a developer environment.

QUnit Edit

For running QUnit tests use ./node_modules/.bin/grunt qunit --qunit-component=GrowthExperiments from the root mediawiki directory.

Jest Edit

For running Jest tests use the NPM script npm run test:jest from the GrowthExperiments extension directory.

Snapshot testing Edit

Jest supports snapshot testing which is a useful feature to make sure UIs do not change unexpectedly. To create a snapshot file from a component for the first time use npm run test:jest. To update an existing snapshot based on source component changes use npm run test:jest:update

Testing a Codex patch in the frontend documentation Edit

Pull the relevant Codex patch

/projects/codex$ git review -d 1234

Build all Codex packages since the build of packages/codex may depend on the build of packages/codex-design-tokens

/projects/codex$ npm run build-all

Link the local package into your package

$ cd /projects/codex/packages/codex             # go to the codex package directory
/projects/codex/packages/codex$ npm link        # create a global link
$ cd /projects/my-node-package                  # go to your package directory
/projects/my-node-$ npm link @wikimedia/codex   # link-install the codex package

All import '@wikimedia/codex' or require( '@wikimedia/codex' ) statements should work as expected. Relative imports in .{vue,js,ts} files should also continue to work, eg: import '../../node_modules/@wikimedia/codex/dist/codex.style.css';

VitePress projects Edit

On VitePress projects only files within the root directory are allowed to be served by default. Assuming the codex repository folder is a sibling of the target project to test, the vite config can be modified to temporary allow serving files from outside its root.

// vite.config.js
const { defineConfig } = require( 'vite' );

module.exports = defineConfig( {
	server: {
		fs: {
			 * Allow serving files from the codex local package.
             * Only files from the dist/ directory should be used
			allow: [ '../codex/packages/codex/dist' ]
} );

This change should not be pushed to the remote repository.

Unlinking Edit

To revert your project to use the original Codex version:

/projects/my-node-package$ npm unlink --no-save @wikimedia/codex    # remove the package without removing its original entry in package.json
/projects/my-node-package$ npm install                              # install the package again from the npm registry

See npm-link

Trouble shooting Edit

VitePress creates a cache dependency directory which isn't updated on unlinking operations. You can just flush its content and the cache will be populated again with the current packages from node_modules.

/projects/my-node-package$ rm -rf docs/.vitepress/cache/deps/

Integrating a Vue prototype into a MW extension Edit

Pre-steps ( developed in the VitePress sandbox in the prototyping phase ) Edit

This is a backlog of issues found while trying to integrate a Vue component developed with VitePress and Codex into GrowthExperiments. TODO: add links to phab tasks.

  1. Integrate with a MW-compatible i18n system T335277
  2. Meet, at least, the UX excellence level of OOUI version of the implemented component
    1. Adapt component styles and user interactions (eg: swipe) for RTL languages T335371
    2. Image loading performance T335268
    3. Documentation on the component

Steps ( developed in MW in the integration phase ) Edit

  1. Compile the Vue code
  2. Load it through RL
  3. Testing? Regression?
  4. ...