3.0 KiB
Architecture Decision Records
ADR-1: The toolkit is TypeScript source, linked into the applications
Status: Accepted
Context: manage-ui and sql-query-webui share their server helpers and web components. The applications run their servers with Node's type stripping and build their web code with Vite. The toolkit is to be published to Gitea later; until then it is developed next to them.
Decision: The toolkit ships its .ts and .tsx files without a build, with three entry points:
./server, ./web and ./vite. The applications depend on the checkout by a file: path, which
npm links; Node runs the server helpers from the checkout's real path, where type stripping
applies, and Vite compiles the web code. The server helpers import only Node's modules at run
time, and types of Fastify; the Vite helpers import only types of Vite, taking loadEnv's answer
from the application. The web code's React, MUI and Emotion come from the application, which
dedupes them with TOOLKIT_RESOLVE. The peer dependencies are optional, as an application uses
only some of the entry points, and are development dependencies for the toolkit's own checks.
Consequences: The applications need the checkout at ../sk-react-toolkit, and their container
builds cannot install it until it is published. Node refuses type stripping in node_modules,
so the published package is compiled (ADR-2).
ADR-2: The published package is built in dist/ and published to Gitea by a tag
Status: Accepted
Context: An installed package lives in node_modules, where Node does not strip types, so the
published package has to be JavaScript, while the linked checkout stays TypeScript source. The
repository is on Gitea, which has an npm registry per owner and Actions mostly compatible with
GitHub's.
Decision: build.mjs compiles the toolkit with tsconfig.build.json, which rewrites the .ts
import extensions to .js, into dist/ with declarations, and writes dist/package.json with
exports of the compiled files and declarations; the package published is dist/, while the
source package.json stays private with exports of the source. The name is
@koszewscy/sk-react-toolkit, scoped to the owner, so an application takes only this scope from
Gitea; it imports it as sk-react-toolkit by an npm alias, so the switch from the checkout to the
published package changes only the dependency. The package is built and published only by the
Release workflow, which follows linux-cloud-router's: it runs for each tag and on demand, with
the secrets CI_URL, CI_OWNER and CI_TOKEN, and skips a version already published.
actions/setup-node gives npm the registry of the package's scope and the token, so the package
carries no registry; release.mjs refuses a tag x.y.z that is not the version of
package.json.
Consequences: A release raises the version in both CHANGELOG.md and package.json, and a
re-run, or a tag x.y.z-n, publishes nothing. The declarations of renderApp reference the
declaration of the virtual:font module, which build.mjs copies into dist/.