polygerrit-ui/README.md - gerrit - Git at Google

 # Gerrit Lit Frontend

 Follow the
 [setup instructions for Gerrit backend developers](https://gerrit-review.googlesource.com/Documentation/dev-readme.html)
 where applicable. The most important command is:

 ```sh
 git clone --recurse-submodules https://gerrit.googlesource.com/gerrit
 ```

 The `--recurse-submodules` option is needed on `git clone` to ensure that the
 core plugins, which are included as git submodules, are also cloned.

 Then make sure to install the commit hook that will set up the `Change-Id` for
 each push to Gerrit:

 ```sh
 cd gerrit && (
   cd .git/hooks
   ln -s ../../resources/com/google/gerrit/server/tools/root/hooks/commit-msg
 )
 ```

 ## Installing [Bazel](https://bazel.build/)

 Follow the instructions
 [here](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_installation)
 to get and install Bazel. Using Bazelisk is usually the easiest option.

 ## Installing [Node.js](https://nodejs.org/en/download/) yarn and pnpm

 Use a recent Node.js version that is supported by the repository. If in doubt,
 use the version that is used in CI or documented in the root `package.json`.

 Examples:

 ```sh
 # Debian / Ubuntu
 sudo apt-get install nodejs npm

 # macOS with Homebrew
 brew install node
 ```

 All other platforms:
 [download from nodejs.org](https://nodejs.org/en/download/),

 or use [nvm - Node Version Manager](https://github.com/nvm-sh/nvm).

 Install Yarn:

 ```sh
 npm install -g yarn
 ```

 Install pnpm:

 ```sh
 npm install -g pnpm
 ```

 ## Dependency Management (Yarn → pnpm Transition)

 - yarn.lock is authoritative
 - pnpm-lock.yaml is generated via `pnpm import`
 - Do NOT edit pnpm-lock.yaml manually

 ## Expected Bazel Behavior

 First run may fail with:

 pnpm-lock.yaml file updated. Please run your build again.

 Rerun the same command.

 ## Workflow

 1. Edit package.json
 2. Run: yarn install
 3. Run: bazel build gerrit
 4. If lock updated → rerun build

 ## Why Yarn stays

 - gradual migration from `yarn` to `pnpm`
 - stable dependency resolution
 - avoids breaking workflows

 ## DO NOT RUN

 ```sh
 pnpm install
 ```

 It creates a different dependency graph.

 ## Long-term

 Eventually:
 - pnpm-lock.yaml becomes canonical
 - yarn.lock removed

 ## Setup TypeScript support in the IDE

 Modern IDEs should automatically handle TypeScript settings from
 `polygerrit-ui/app/tsconfig.json`. The `tsc` compiler places compiled files in
 the `.ts-out/pg` directory at the root of the Gerrit workspace, and you can
 configure the IDE to exclude the whole `.ts-out` directory. In IntelliJ IDEA,
 right-click the directory and select **Mark Directory As > Excluded**.

 If your IDE still reports errors, then you can try configuring TypeScript
 manually. For example, if IntelliJ IDEA shows
 `Cannot find parent 'tsconfig.json'`, then set the TypeScript options to:

 ```sh
 --project polygerrit-ui/app/tsconfig.json
 ```

 ## Developing locally

 The preferred method for development is to serve the web files locally using the
 Web Dev Server and then view a running Gerrit instance (local or otherwise) and
 replace its web client with the local one using the Gerrit FE Dev Helper
 extension.

 ### Web Dev Server

 The [Web Dev Server](https://modern-web.dev/docs/dev-server/overview/) serves
 the compiled web files and dependencies unbundled over localhost. Start it with:

 ```sh
 pnpm start
 ```

 To inject plugins or other files, we use the
 [Gerrit FE Dev Helper](https://chrome.google.com/webstore/detail/gerrit-fe-dev-helper/jimgomcnodkialnpmienbomamgomglkd)
 Chrome extension.

 If you run into problems, refer to the troubleshooting section below or contact
 the team.

 ### Chrome extension: Gerrit FE Dev Helper

 To help frontend development, including bypassing auth in local dev workflows,
 we created this Chrome extension:
 [Gerrit FE Dev Helper](https://chrome.google.com/webstore/detail/gerrit-fe-dev-helper/jimgomcnodkialnpmienbomamgomglkd).

 It basically works as a proxy that blocks or redirects requests from the current
 site to a configured URL according to rules.

 The source code is in
 [Gerrit - gerrit-fe-dev-helper](https://gerrit-review.googlesource.com/q/project:gerrit-fe-dev-helper),
 and contributions are welcome.

 To use this extension, follow its
 [README](https://gerrit.googlesource.com/gerrit-fe-dev-helper/+/master/README.md).

 ### Running locally against a Gerrit test site

 Set up a local test site once:

 1. [Build Gerrit](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_gerrit_development_war_file)
 2. [Set up a local test site](https://gerrit-review.googlesource.com/Documentation/dev-readme.html#init)
 3. Optionally [populate](https://gerrit.googlesource.com/gerrit/+/master/contrib/populate-fixture-data.py)
    your test site with test data

 For running a locally built Gerrit war against your test instance use
 [this command](https://gerrit-review.googlesource.com/Documentation/dev-readme.html#run_daemon).

 If you want to serve the Lit frontend directly from the sources in
 `polygerrit-ui/app/` instead of from the war:

 1. Start the [Web Dev Server](#web-dev-server)
 2. Add the `--dev-cdn` option:

 ```sh
 $(bazel info output_base)/external/local_jdk/bin/java \
     -DsourceRoot=$(bazel info workspace) \
     -jar bazel-bin/gerrit.war daemon \
     -d $GERRIT_SITE \
     --console-log \
     --dev-cdn http://localhost:8081
 ```

 The Web Dev Server currently does not serve fonts or some other static assets.
 Follow
 [Issue 40015119](https://issues.gerritcodereview.com/issues/40015119)
 for updates.

 *Note:* You can also use another CDN here, for example:
 https://cdn.googlesource.com/polygerrit_ui/678.0

 ## Running tests

 For daily development you typically only want to run and debug individual tests.
 Our tests run using the
 [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/).

 Common commands:

 * Run all tests once:

 ```sh
 pnpm test
 ```

 * Run all tests in watch mode. Changing a file reruns affected tests:

 ```sh
 pnpm test:watch
 ```

 * Run all tests once under Bazel:

 ```sh
 ./polygerrit-ui/app/run_test.sh
 ```

 * Run a single test file and rerun when affected files change:

 ```sh
 pnpm test:single "**/gr-comment_test.ts"
 ```

 ### Screenshot tests

 We use screenshot tests to prevent unintended visual regressions.

 To run the screenshot tests:

 ```sh
 pnpm test:screenshot
 ```

 Or via Bazel, which matches what CI runs and uses the Bazel-managed
 dependency tree:
 ```sh
 bazelisk test //polygerrit-ui:web_test_runner_screenshots
 ```

 The `//polygerrit-ui:web_test_runner_all` target runs both the unit and
 screenshot buckets in a single invocation. Both screenshot targets are
 tagged `manual`, so they are never picked up by a bare `bazel test //...`
 and must be named explicitly.

 If a test fails, then the component's appearance has changed. New screenshots
 are generated in the `polygerrit-ui/screenshots/Chromium/failed/` directory.
 If an existing baseline differs, then a diff image is also created there.

 If the change is intended, then approve the new screenshots as the baseline by
 moving the new screenshot files from `failed` to `baseline`, overwriting the old
 ones. The diff images in `failed` can be deleted.

 ```sh
 mv polygerrit-ui/screenshots/Chromium/failed/*.png \
   polygerrit-ui/screenshots/Chromium/baseline/
 ```

 After moving the file(s), run `pnpm test:screenshot` again to confirm they pass.

 ### Compiling code

 ```sh
 # Compile frontend once to check for type errors
 pnpm compile

 # Watch mode
 pnpm compile:watch
 ```

 ## Style guide

 We follow the
 [Google JavaScript Style Guide](https://google.github.io/styleguide/javascriptguide.xml)
 with a few exceptions. When in doubt, remain consistent with the surrounding
 code.

 In addition, we encourage the use of [ESLint](http://eslint.org/). It is
 available as a command-line utility as well as a plugin for most editors and
 IDEs.

 We have an ESLint flat config in `polygerrit-ui/app/eslint-bazel.config.js`
 configured to enforce the preferred style of the PolyGerrit project.

 Some useful commands:

 * Run ESLint on the whole app:

 ```sh
 pnpm eslint
 ```

 * Run ESLint and apply automatic fixes:

 ```sh
 pnpm eslintfix
 ```

 * Run ESLint on a specific subdirectory:

 ```sh
 pnpm exec eslint --config polygerrit-ui/app/eslint-bazel.config.js \
   --ext .html,.js,.ts polygerrit-ui/app/$YOUR_DIR_HERE
 ```

 * Run ESLint on all locally changed frontend files:

 ```sh
 git diff --name-only HEAD | xargs pnpm exec eslint \
   --config polygerrit-ui/app/eslint-bazel.config.js \
   --ext .html,.js,.ts
 ```

 When running ESLint manually, invoke it from the repository root so that
 repo-root-relative paths in the flat config resolve correctly.

 ## Contributing

 Our users report bugs and feature requests related to the UI through the Gerrit
 Tracker in the
 [WebFrontend](https://issues.gerritcodereview.com/issues?q=componentid:1369968)
 component.

 If you want to help, feel free to pick one of the `New` issues without assignees
 and send us a change.

 If you don't know who to assign as reviewer for your change, then you can use
 this special account:

 `gerrit-fe-reviewers@api-project-164060093628.iam.gserviceaccount.com`

 Assigning that account automatically picks two volunteers from the frontend
 reviewer queue.

 If you are willing to join that queue and help review community changes, then
 create an issue through Gerrit issue tracker and ask to join.
	# Gerrit Lit Frontend

	Follow the
	[setup instructions for Gerrit backend developers](https://gerrit-review.googlesource.com/Documentation/dev-readme.html)
	where applicable. The most important command is:

	```sh
	git clone --recurse-submodules https://gerrit.googlesource.com/gerrit
	```

	The `--recurse-submodules` option is needed on `git clone` to ensure that the
	core plugins, which are included as git submodules, are also cloned.

	Then make sure to install the commit hook that will set up the `Change-Id` for
	each push to Gerrit:

	```sh
	cd gerrit && (
	cd .git/hooks
	ln -s ../../resources/com/google/gerrit/server/tools/root/hooks/commit-msg
	)
	```

	## Installing [Bazel](https://bazel.build/)

	Follow the instructions
	[here](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_installation)
	to get and install Bazel. Using Bazelisk is usually the easiest option.

	## Installing [Node.js](https://nodejs.org/en/download/) yarn and pnpm

	Use a recent Node.js version that is supported by the repository. If in doubt,
	use the version that is used in CI or documented in the root `package.json`.

	Examples:

	```sh
	# Debian / Ubuntu
	sudo apt-get install nodejs npm

	# macOS with Homebrew
	brew install node
	```

	All other platforms:
	[download from nodejs.org](https://nodejs.org/en/download/),

	or use [nvm - Node Version Manager](https://github.com/nvm-sh/nvm).

	Install Yarn:

	```sh
	npm install -g yarn
	```

	Install pnpm:

	```sh
	npm install -g pnpm
	```

	## Dependency Management (Yarn → pnpm Transition)

	- yarn.lock is authoritative
	- pnpm-lock.yaml is generated via `pnpm import`
	- Do NOT edit pnpm-lock.yaml manually

	## Expected Bazel Behavior

	First run may fail with:

	pnpm-lock.yaml file updated. Please run your build again.

	Rerun the same command.

	## Workflow

	1. Edit package.json
	2. Run: yarn install
	3. Run: bazel build gerrit
	4. If lock updated → rerun build

	## Why Yarn stays

	- gradual migration from `yarn` to `pnpm`
	- stable dependency resolution
	- avoids breaking workflows

	## DO NOT RUN

	```sh
	pnpm install
	```

	It creates a different dependency graph.

	## Long-term

	Eventually:
	- pnpm-lock.yaml becomes canonical
	- yarn.lock removed

	## Setup TypeScript support in the IDE

	Modern IDEs should automatically handle TypeScript settings from
	`polygerrit-ui/app/tsconfig.json`. The `tsc` compiler places compiled files in
	the `.ts-out/pg` directory at the root of the Gerrit workspace, and you can
	configure the IDE to exclude the whole `.ts-out` directory. In IntelliJ IDEA,
	right-click the directory and select Mark Directory As > Excluded.

	If your IDE still reports errors, then you can try configuring TypeScript
	manually. For example, if IntelliJ IDEA shows
	`Cannot find parent 'tsconfig.json'`, then set the TypeScript options to:

	```sh
	--project polygerrit-ui/app/tsconfig.json
	```

	## Developing locally

	The preferred method for development is to serve the web files locally using the
	Web Dev Server and then view a running Gerrit instance (local or otherwise) and
	replace its web client with the local one using the Gerrit FE Dev Helper
	extension.

	### Web Dev Server

	The [Web Dev Server](https://modern-web.dev/docs/dev-server/overview/) serves
	the compiled web files and dependencies unbundled over localhost. Start it with:

	```sh
	pnpm start
	```

	To inject plugins or other files, we use the
	[Gerrit FE Dev Helper](https://chrome.google.com/webstore/detail/gerrit-fe-dev-helper/jimgomcnodkialnpmienbomamgomglkd)
	Chrome extension.

	If you run into problems, refer to the troubleshooting section below or contact
	the team.

	### Chrome extension: Gerrit FE Dev Helper

	To help frontend development, including bypassing auth in local dev workflows,
	we created this Chrome extension:
	[Gerrit FE Dev Helper](https://chrome.google.com/webstore/detail/gerrit-fe-dev-helper/jimgomcnodkialnpmienbomamgomglkd).

	It basically works as a proxy that blocks or redirects requests from the current
	site to a configured URL according to rules.

	The source code is in
	[Gerrit - gerrit-fe-dev-helper](https://gerrit-review.googlesource.com/q/project:gerrit-fe-dev-helper),
	and contributions are welcome.

	To use this extension, follow its
	[README](https://gerrit.googlesource.com/gerrit-fe-dev-helper/+/master/README.md).

	### Running locally against a Gerrit test site

	Set up a local test site once:

	1. [Build Gerrit](https://gerrit-review.googlesource.com/Documentation/dev-bazel.html#_gerrit_development_war_file)
	2. [Set up a local test site](https://gerrit-review.googlesource.com/Documentation/dev-readme.html#init)
	3. Optionally [populate](https://gerrit.googlesource.com/gerrit/+/master/contrib/populate-fixture-data.py)
	your test site with test data

	For running a locally built Gerrit war against your test instance use
	[this command](https://gerrit-review.googlesource.com/Documentation/dev-readme.html#run_daemon).

	If you want to serve the Lit frontend directly from the sources in
	`polygerrit-ui/app/` instead of from the war:

	1. Start the [Web Dev Server](#web-dev-server)
	2. Add the `--dev-cdn` option:

	```sh
	$(bazel info output_base)/external/local_jdk/bin/java \
	-DsourceRoot=$(bazel info workspace) \
	-jar bazel-bin/gerrit.war daemon \
	-d $GERRIT_SITE \
	--console-log \
	--dev-cdn http://localhost:8081
	```

	The Web Dev Server currently does not serve fonts or some other static assets.
	Follow
	[Issue 40015119](https://issues.gerritcodereview.com/issues/40015119)
	for updates.

	Note: You can also use another CDN here, for example:
	https://cdn.googlesource.com/polygerrit_ui/678.0

	## Running tests

	For daily development you typically only want to run and debug individual tests.
	Our tests run using the
	[Web Test Runner](https://modern-web.dev/docs/test-runner/overview/).

	Common commands:

	* Run all tests once:

	```sh
	pnpm test
	```

	* Run all tests in watch mode. Changing a file reruns affected tests:

	```sh
	pnpm test:watch
	```

	* Run all tests once under Bazel:

	```sh
	./polygerrit-ui/app/run_test.sh
	```

	* Run a single test file and rerun when affected files change:

	```sh
	pnpm test:single "**/gr-comment_test.ts"
	```

	### Screenshot tests

	We use screenshot tests to prevent unintended visual regressions.

	To run the screenshot tests:

	```sh
	pnpm test:screenshot
	```

	Or via Bazel, which matches what CI runs and uses the Bazel-managed
	dependency tree:
	```sh
	bazelisk test //polygerrit-ui:web_test_runner_screenshots
	```

	The `//polygerrit-ui:web_test_runner_all` target runs both the unit and
	screenshot buckets in a single invocation. Both screenshot targets are
	tagged `manual`, so they are never picked up by a bare `bazel test //...`
	and must be named explicitly.

	If a test fails, then the component's appearance has changed. New screenshots
	are generated in the `polygerrit-ui/screenshots/Chromium/failed/` directory.
	If an existing baseline differs, then a diff image is also created there.

	If the change is intended, then approve the new screenshots as the baseline by
	moving the new screenshot files from `failed` to `baseline`, overwriting the old
	ones. The diff images in `failed` can be deleted.

	```sh
	mv polygerrit-ui/screenshots/Chromium/failed/*.png \
	polygerrit-ui/screenshots/Chromium/baseline/
	```

	After moving the file(s), run `pnpm test:screenshot` again to confirm they pass.

	### Compiling code

	```sh
	# Compile frontend once to check for type errors
	pnpm compile

	# Watch mode
	pnpm compile:watch
	```

	## Style guide

	We follow the
	[Google JavaScript Style Guide](https://google.github.io/styleguide/javascriptguide.xml)
	with a few exceptions. When in doubt, remain consistent with the surrounding
	code.

	In addition, we encourage the use of [ESLint](http://eslint.org/). It is
	available as a command-line utility as well as a plugin for most editors and
	IDEs.

	We have an ESLint flat config in `polygerrit-ui/app/eslint-bazel.config.js`
	configured to enforce the preferred style of the PolyGerrit project.

	Some useful commands:

	* Run ESLint on the whole app:

	```sh
	pnpm eslint
	```

	* Run ESLint and apply automatic fixes:

	```sh
	pnpm eslintfix
	```

	* Run ESLint on a specific subdirectory:

	```sh
	pnpm exec eslint --config polygerrit-ui/app/eslint-bazel.config.js \
	--ext .html,.js,.ts polygerrit-ui/app/$YOUR_DIR_HERE
	```

	* Run ESLint on all locally changed frontend files:

	```sh
	git diff --name-only HEAD \| xargs pnpm exec eslint \
	--config polygerrit-ui/app/eslint-bazel.config.js \
	--ext .html,.js,.ts
	```

	When running ESLint manually, invoke it from the repository root so that
	repo-root-relative paths in the flat config resolve correctly.

	## Contributing

	Our users report bugs and feature requests related to the UI through the Gerrit
	Tracker in the
	[WebFrontend](https://issues.gerritcodereview.com/issues?q=componentid:1369968)
	component.

	If you want to help, feel free to pick one of the `New` issues without assignees
	and send us a change.

	If you don't know who to assign as reviewer for your change, then you can use
	this special account:

	`gerrit-fe-reviewers@api-project-164060093628.iam.gserviceaccount.com`

	Assigning that account automatically picks two volunteers from the frontend
	reviewer queue.

	If you are willing to join that queue and help review community changes, then
	create an issue through Gerrit issue tracker and ask to join.