Lichess UI Development

Getting started

If you haven't already, install the tools described on the main onboarding page.

Learn about pnpm here. In most cases, it has the same behavior and syntax as both npm and yarn. Just as you might use npm install or yarn add to add a package with those tools, either pnpm install or pnpm add can be used to do the same with pnpm.

Building the client involves tsc to transpile typescript code to javascript, dart-sass to compile *.scss SASS files into CSS, and esbuild to bundle javascript dependencies into individual modules suitable for linkage in an HTML <script> tag.

Using ui/build

Client assets are built with a node application wrapped in a bash script (ui/build). The node application manages tsc, dart-sass, esbuild, and (mostly) pnpm under the hood so you don't have to. The source code can be found here.

ui/build --help lists the arguments.

It acts on the package.json file for each top level package in the ui folder to generate assets. This process is fully documented by the README.md in the ui sources folder.

Customizing linked pnpm modules

How about when you need to make changes to a module from the npm registry such as chessground? For that, you can use pnpm link.

Clone the repo you want to modify to <your-local-package>. Then cd to the using module directory - the one containing the package.json you want to link to your package. Finally, type pnpm link <relative-path-to-your-local-package>. Run ui/build again to pick up your changes.

For example, to work on pgn-viewer: First git clone https://github.com/lichess-org/pgn-viewer into a directory adjacent to lila root. We'll use the lichess forum code to test our local pgn-viewer. Forum stuff lives in the ui/site module and lichess-pgn-viewer is linked in that module's package.json. So:

cd <lila-root>/ui/site
pnpm link ../../../pgn-viewer # relative path to your local package

IMPORTANT

Notice that pnpm link actually modifies the pnpm-lock.yaml file in lila root. You don't want to check that modification into git.

Here are some useful links:

• Symbols you can use on lichess webpages (defined in public/font/lichess.sfd)
• add some links