Development

The repository is a pnpm workspace of TypeScript packages. TypeScript project references build all packages in the correct sequence.

Install and build

pnpm install
pnpm build

pnpm build operates tsc -b. It builds each package into its dist folder.

The packages

Add a package

Use the scaffold of the repository. Do not write a package.json file yourself.

pnpm new --name my-package --config node

The scaffold makes the folder, the package.json and tsconfig.json files, and the reference in the root tsconfig.json. It adds the devDependencies that the config needs, for example @types/node for node, with the versions of the workspace. It does not write over a folder or a package name that exists. Add --force to make the files again in a folder that exists: then it keeps src/index.ts.

Tests

The test strategy explains each type of test.

The site build

pnpm --filter @lag/site build makes the site in packages/site/dist. After the Vite build, the plugin in build/static-site-plugin.ts does these steps:

1. It opens each page of the site in Chromium. The pages are the home page, each MDX page, the playground, the list of test runs and the views of each run.
2. It waits until the page is ready. A page is ready when no element has aria-busy="true" and the page does not change for 200 ms.
3. It writes the HTML of the page into the HTML file of the page. Search engines and link previews read this HTML without JavaScript.
4. It adds the head tags of the page (build/head-tags.ts): the title, the description, the canonical URL, Open Graph and the Twitter card. It also adds the structured data (JSON-LD).
5. It makes an Open Graph image of 1200 × 630 pixels for each page, in dist/og/ (build/og-image.ts). The image shows the group, the title and the description of the page, with a lag chart. Each page gets different bars in the chart.
6. It writes sitemap.xml, robots.txt and 404.html. The pages of a test run and 404.html have noindex, and the sitemap does not contain them.

When the app starts in the browser, it renders the page into a hidden element. When that page is ready, the app removes the HTML from the build and shows its own page (src/app/prerender-handoff.ts). Thus the reader sees the full page from the start, and the charts and the playground operate after the change.

During the prerender, the monitors of the playground and of the home page do not start. Thus the HTML does not contain the values of the build machine.

A component that loads code or data must have aria-busy="true" while it loads. If it does not, the build can keep the HTML of a page that is not complete.

The build needs Chromium. Install it one time:

pnpm --filter @lag/site exec playwright install chromium

The social preview of the repository is .github/social-preview.png (1280 × 640 pixels). To make it again, use pnpm --filter @lag/site social-preview. Then upload the file in the settings of the repository on GitHub.

Rules for a change

• Give each new part its dependencies as arguments. Do not read browser globals outside the browser adapter.
• Add the metrics of a new monitor to the metric catalog. The catalog test makes sure that the code agrees with it.
• Write a unit test for each rule, with fake time. Write a browser test for each behavior that depends on a real browser.
• Write the comments and the pages with the writing style, and operate pnpm lint:ste.
• Make sure that pnpm build, the tests and the linter pass before you commit.

Release

The workflow release.yml publishes @mark1russell7/lag to npm. To release a version, do these steps:

1. Set the new version in packages/lag/package.json, and merge the change to main.
2. Push a tag with the same version and the prefix v, for example v0.2.0.

The workflow stops when the tag and the version are different. It tests and builds the package, packs it with pnpm pack, and publishes the tarball with a provenance statement. The workflow uses npm trusted publishing, thus the repository has no npm token. The owner of the package sets the trusted publisher on npm one time.