Local Development

Prerequisites: This repository requires node v16 and up

Initial setup

Clone this repository
Install dependecies with npm i

This will also install some Git pre-commit hooks that check any modified files against the configured linters. (Use git commit -n to skip these hooks, e.g. to create some work-in-progress commits that will be cleaned up later.)

Regular development

TL;DR: All checks are run with:

npm t

Dev Entry point

To run the development entry point also known as the dev server:

npm run dev

You can visit the dev entry point at http://localhost:3000/. Changes to the source files will be applied automatically, so you can start this once and then leave it running in the background.

For instructions to see the form in the context of the special page, see the WikibaseLexeme readme.

The dev entry point can also read some parameters from the URL, as a single JSON-serialized initParams object in the same format as the special page passes to the app. Here are some useful links:

Linting

The linters, except for TypeScript type checking, can be run with:

npm run lint

Many linter errors can be fixed automatically:

npm run fix

Static type checking is executed with

npm run check-types

Testing

Several npm scripts are available to only run a subset of tests, such as:

npm run test-only # only tests without linters
npm run test:unit
npm run test:integration

Unit tests (in tests/unit/) focus on excercising a self-contained piece of code, while integration tests in (tests/integration/) are designed to test the interaction between several components and the store.

You can run individual unit or integration tests using npx jest, for example:

npx jest tests/unit/store/actions.test.ts

npx jest tests/integration/App.test.ts

Finally, browser tests in cypress/integration/ are designed to test this application end-to-end with actual browser interaction. They are also the main place for the automated accessiblity tests.

Cypress tests are run against the dev entry point (see above) and thus use /index.html to provide the scaffolding. After you've started the dev server, you can open the interactive browser tests environment with:

npm run cypress:open

Chore: Dependency Updates

You can see which dependencies have new releases by first making sure your local dependencies are up-to-date by executing npm ci and then running npm outdated. The following dependencies should be ignored:

Vue and Vuex: in production, we use the versions shipped by MediaWiki core, so we should use the same versions for testing. The current versions shipped by MediaWiki core are listed in foreign-resources.yaml.
Node.js version: The GitHub Workflows here should use the same Node.js version as the mwgate-nodeXX-docker CI job in WikibaseLexeme, because that job builds this app for the test:snl-distnodiff script. This version is currently Node 18. The upgrade to Node 20 there is tracked in T343827.
ESLint and related dependencies (i.e. @typescript-eslint/eslint-plugin, eslint-plugin-cypress): ESLint v9 requires flat config, which is currently incompatible with some MediaWiki repos. Migration to ESLint v9 is tracked in T364065. Until this migration is complete, we can't update to versions of dependencies that require v9 or higher. This also blocks @wmde/eslint-config-wikimedia-typescript above 0.2.12, since 0.2.14 requires eslint-config-wikimedia ^0.32.3, which pulls in a newer @typescript-eslint/eslint-plugin that drops several rules now moved to eslint-stylistic; fixing that is tracked in T436626.

All other dependencies should generally be updated to the latest version. If you discover that a dependency should not be updated for some reason, please add it to the above list. If a dependency can only be updated with substantial manual work, you can create a new task for it and skip it in the context of the current chore.

As of the chore task T435630, the following had only a major-version update available and were left on their current major version rather than attempting the migration as part of that chore; a future round should check whether these can be picked up:

jest, jest-environment-jsdom, @types/jest (29.x to 30.x).
typescript (5.x to 7.x, the new Go-based compiler).
@wikimedia/codex, @wikimedia/codex-design-tokens (1.x to 2.x).
cypress (13.x to 15.x), start-server-and-test (2.x to 3.x).
vite (6.x to 8.x), @vitejs/plugin-vue (5.x to 6.x).
stylelint-config-standard-scss (needs stylelint 17.x, we're still on 16.x), stylelint-config-recommended-vue (1.x to 2.x), @namics/stylelint-bem (10.x to 11.x). Note: wikidata-query-builder already did this migration (commit), worth reusing those learnings here.
lint-staged (15.x to 16.x).
eslint-plugin-vue (9.x to 10.x; also needs vue-eslint-parser 10.x, which conflicts with the still-pinned @vue/eslint-config-typescript).
vue-tsc (2.x to 3.x).

The recommended way to update dependencies is to collect related dependency updates into grouped commits; this keeps the number of commits to review manageable (compared to having one commit for every update), while keeping the scope of each commit limited and increasing reviewability and debuggability (compared to combining all updates in a single commit). For example, this can be one commit for each of:

all ESLint-related dependency updates
all Jest-related dependency updates
all Vue-related dependency updates
all PostCSS/Stylelint-related dependency updates
npm update for all other dependency updates

Make sure that all checks still pass for every commit.

Once all dependency updates are merged, update the submodule version in WikibaseLexeme (see below).

Updating the submodule version in WikibaseLexeme

This repository is a git submodule in WikibaseLexeme. That submodule needs to be updated there for changes here to be deployed to production.

To update the submodule version in WikibaseLexeme run npm run bump-special-new-lexeme there. See New Lexeme Special Page in the WikibaseLexeme dev README for more details.