hsr-optimizer computes builds and scores relics for Honkai Star Rail

Three tools in one static page

The project presents itself as tools for optimizing your Honkai Star Rail builds, and the README names two of them directly. The Character Optimizer is the headline tool, and the Relic Scorer is a separate entry with its own view. A third capability appears in the README as a relic organizer and recommendations screen. The repository description is broader still, listing a relic scorer, a damage calculator and various other tools for building and gearing characters. All of it is delivered as a static web application, with the homepage pointing at fribbels.github.io/hsr-optimizer and the same address used for the optimizer and the relic scorer views. The architecture choice is worth noting because it defines what the project can and cannot do. There is no server, no account and no database in the core product, which means the whole thing can be hosted on GitHub Pages and the deploy script in the package manifest is exactly that, a gh-pages publish of the dist directory. It also means the calculation happens in your browser, on data that shipped with the page.

Game data arrives as files, which is the fragile part

The credits section names who provides what, and the most important line is short. Dim for providing the data files. That single contribution underpins everything else in the project, because a character optimizer that does not know the current stats of a character is not much use. The data lives in the repository rather than being fetched from the game, which makes the whole tool work offline and makes every update a pull request. The other credits describe where the peripheral tools came from. Enka.Network provides the relic scorer API, which is the external service the scorer talks to. Kel-Z built and maintains the relic scanner, which is the component that reads the game client and exports what it finds. IceDynamix and Emma are credited with the Reliquary Archiver, with Emma also credited for live import, and IceDynamix for Estimated TBP. Floods is credited with adding i18n support, various features and maintenance, and Jingna Zhang with UI design and direction. The picture that emerges is a community project where the game data, the scan tooling and the presentation are separate contributions, and where knowing which piece to update is part of using it.

A Vite and TypeScript codebase with a strict toolchain

The package manifest describes a modern front end build, and the toolchain requirements are unusually strict. The package is private, the type is module, the package manager is pinned to npm 11.13.0, and the engines field requires Node 26 or newer with npm 11 or newer, while pnpm and yarn are pinned to a version of 999.0.0, which is a way of saying do not use them. The scripts cover the whole lifecycle. The dev server is vite, with a mobile variant that binds to the host, a production build, and a preview. Linting is oxlint and formatting runs a script that converts relative imports before calling dprint fmt, with a.dprint.jsonc configuration at the repository root and a.oxlintrc.json. The type checker is tsgo rather than tsc, with a fast variant using a separate tsconfig.fast.json, and the typecheck script first runs update-resources, which regenerates the i18n type definitions. The postinstall step runs patch-package against a patches/ directory, so the project depends on patched dependencies, and there is a.nvmrc pinning the Node version. The result is a codebase with a lot of enforced consistency, which pays off in a project with many contributors and hurts when you just want to run it.

The clone step in the README is:

git clone --filter=blob:none https://github.com/fribbels/hsr-optimizer.git

The partial clone filter keeps the initial checkout small, which matters on a repository with a large history and a lot of binary assets.

Two test layers and a build for the leaderboard

The testing story has two layers and each covers something the other cannot. Unit and integration tests run under vitest, with a fast variant that excludes the simulation orchestrator tests, a silent variant and a watch mode. The end to end tests run under Playwright against a local server, with a codegen script to open the app in a browser and record interactions, a UI mode for the test runner and a report viewer. The leaderboard has its own build path, using a separate vite configuration file and a Node script run with an 8 GB heap allowance, which tells you the leaderboard computation is heavy enough to need its own memory budget. A separate tsconfig.fast.json also exists for a quicker type check, and the repository carries a tests/ directory, a docs/ directory, a public/ directory and a src/ directory, with index.html at the root for the single page entry point. The contributor guide is linked from the README for full setup instructions, and the clone command the README recommends uses a partial clone filter.

Localisation runs through Crowdin and a generated type file

Localisation is not an afterthought here, and the mechanism is visible in the scripts. There is a crowdin.yml at the repository root, which is the configuration for the Crowdin translation service, and the update-resources script runs a code generator that reads the English locale files in public/locales/en_US and writes a resources.d.ts type declaration under src/types. The point of generating that declaration is that translation keys become type checked, so a key that exists in the interface but not in the locale bundle is a compile error rather than a runtime blank. It also means the typecheck script depends on the resource generation having run, which is why typecheck calls update-resources first and why there is a faster typecheck that skips it. The i18n support itself is credited to Floods, who also handles maintenance on the project. A translation platform plus generated types is the combination that keeps a large community project consistent across many languages, and it is one of the reasons the build configuration is as elaborate as it is.

Editorial conclusion

Adopt hsr-optimizer if you play Honkai Star Rail and want to model a build numerically rather than by guesswork, or if you want to score the relics you already own against what a character needs. Do not adopt it as an authoritative data source, since the game data is contributed as files and can lag a patch, and do not build automation on the relic scanner without reading the contributor notes. Verify first that the data files match your game version, that the relic scorer API you plan to use is reachable, and that the build toolchain on your machine satisfies the Node and npm requirements the project states.

Frequently asked questions

Official sources

1. fribbels/hsr-optimizer on GitHub
2. Issues
3. License: MIT
4. Project website
5. README