Build and check

Build the project

No need to stop npm run dev. In a second terminal, in the my-hud folder, run:

$ npm run build

> my-hud@1.0.0 build
> racelink-overlay typegen && tsc --noEmit && vite build

Already up to date.
vite v8.3.6 building client environment for production...
✓ 9 modules transformed.
dist/index.html                   0.39 kB │ gzip:  0.26 kB
dist/assets/index-DwLSqiF8.css    0.92 kB │ gzip:  0.53 kB
dist/assets/index-CdIWPwfm.js   147.16 kB │ gzip: 52.83 kB
✓ built in 79ms
[racelink] Package built: 4 files in dist/. To publish it, add preview/preview.png or capture a preview in Racelink Studio.

The build does four things in order:

racelink-overlay typegen

Updates src/racelink-settings.ts from the manifest. “Already up to date” means it already matches.

tsc --noEmit

Checks the types of the whole project. The dev server does not, so mistakes it let through are found here.

vite build

Builds the code and styles into a few small files in the dist/ folder.

The package check

The Racelink plugin copies the manifest and the images from preview/ into dist/ and checks the package. The [racelink] line at the end is its verdict.

Package built means the package is built but has no Workshop preview yet. We add one below.

What went into dist

index.html

The overlay’s page with links to the built files.

assets/

The code and styles built from src/, together with React. Names with a hash, such as index-CdIWPwfm.js, change whenever the code does.

racelink.overlay.json

A copy of the manifest.

preview/

The Workshop preview and screenshots, when there are any.

That is exactly what goes to the Workshop: no sources and no node_modules. Do not change anything in dist/ by hand: the next build overwrites it.

The built overlay in Racelink

Open Studio and select My HUD. Its card has a Project path: Development, Build, Check, Preview, Publishing. After a build, Build says “dist/ is ready”.

The project no longer depends on the dev server. Stop npm run dev (Ctrl + C): My HUD stays in Studio and in Add overlay, and it can go on any layout — Racelink takes the built package from dist/.

Make the Workshop preview

An overlay cannot be published without its main picture: players see it in the Workshop catalogue. The easiest way is to capture it in Studio:

1. In Studio select My HUD and find Workshop preview.
2. In Preview background pick a background: a track (Nürburgring, Bathurst, Suzuka, also in the rain), Dark, Light or Your photo — a screenshot from the game.
3. Press Capture an animated preview. For about 6 seconds Racelink records the overlay on demo data and saves preview/preview.gif in the project and in dist/.

You can also make the picture yourself: put preview/preview.png (or .jpg, .gif) — up to 1 MB, sides from 256 to 2048 pixels, square looks best. Put up to 9 more pictures in preview/screenshots/: players browse them on the overlay’s page. After adding your own pictures run npm run build so they reach dist/.

Check the package

Racelink checks the package before publishing. You can run the same check yourself:

$ npm run validate

Without a preview it says what is missing:

Checked C:\Users\you\Documents\racelink-overlays\my-hud\dist: 4 files.
  preview/preview.png: add a preview image or capture one in Racelink Studio [PREVIEW_MISSING]
The overlay package is invalid.

With one, that all is well:

Checked C:\Users\you\Documents\racelink-overlays\my-hud\dist: 5 files.
No problems found.

In Studio the Check button does the same, and the project path shows “no errors” at Check. The code in square brackets, such as [PREVIEW_MISSING], names the problem: find it in the list below or in the error reference node_modules/@racelink/overlay/docs/errors.md.

If something goes wrong

• PREVIEW_TOO_LARGE, PREVIEW_DIMENSIONS — the picture is over 1 MB or its sides are outside 256–2048 pixels. Shrink it or capture the preview in Studio.
• FILE_TYPE_NOT_ALLOWED — the package has a file a web page does not need (a .ts or an .exe, say). Usually something extra went into public/ or preview/.
• MANIFEST_FIELD — a field of the manifest is wrong; the path after the colon names it.
• PACKAGE_NOT_BUILT in Studio — the project has not been built yet. Run npm run build.