SHD.build
A SvelteKit community application for The Division Resurgence. SHD.build combines a public game database, loadout builder, shared builds, guides, account management, and the ISAC data-management console.
See docs/architecture.md for the implementation model.
Database
The server uses the in-process @tursodatabase/database package and a local
SQLite-compatible file. Turso Cloud is not required.
Create or update the local database:
npm run db:migrate
The default file is data/shd-build.db. Copy .env.example to .env and
set a different location if needed.
Store custom avatars as metadata-free 256 × 256 WebP files. Set
TDR_AVATAR_STORAGE_PATH to a persistent, writable directory in production;
it defaults to data/avatars. The same configuration works on Windows and
Linux.
Seed the initial local accounts once:
npm run db:seed-users
The seed creates administrator Aewyn and standard user Quartermaster.
It generates and displays strong temporary passwords once, then stores only
salted Argon2id hashes.
Develop
npm run dev
Encrypted environment files
Keep development, staging, and production settings in the committed, encrypted
.env.development, .env.staging, and .env.production files. Keep private
decryption keys only in the ignored .env.keys file and back it up in a
password manager.
npm run env:decrypt # decrypt all environment files for editing
npm run env:encrypt # encrypt all environment files again
npm run env:stage # encrypt and git-add all environment files
npm run env:decrypt:development # operate on one environment
npm run env:decrypt:staging
npm run env:decrypt:production
npm run env:sync:staging-credentials # copy shared Discord/SMTP values from development
The repository pre-commit hook runs env:stage and replaces staged plaintext
environment files with encrypted versions. Git has no pre-add hook. Use
npm run env:stage instead of directly adding these two files.
Keep .env.keys out of Git and retain a backup. Production deployments receive
DOTENV_PRIVATE_KEY_PRODUCTION through their secret manager; do not copy the
keys file to the server.
Containers and staging deployment
The application uses the official SvelteKit Node adapter and a multi-stage
Dockerfile. Keep database files, database backups, user avatars, and uploaded
game-data icons under /app/data on a persistent volume. Inject runtime secrets
when the container starts; keep them out of the image.
docs/DEPLOYMENT.md documents the staging Compose topology
and Gitea Actions deployment. A push to main validates the application,
builds the candidate image while staging stays online, stops the application
and scheduler for the database backup and migration, then starts the release.
Passwordless authentication
Use passkeys as the preferred sign-in method. Set APP_ORIGIN to the exact
public origin for registration and authentication. Set PASSKEY_RP_ID to that
hostname or a registrable parent domain. Hosted environments use shd.build,
which permits credentials on shd.build and dev.shd.build. Use localhost
for direct local development.
Magic links require SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER,
SMTP_PASSWORD, and SMTP_FROM. Use SMTP_SECURE=true on port 465. Use
false on port 587 and upgrade with STARTTLS. An account owner activates an
email identity by following a 15-minute, single-use verification link.
Validate
npm run check
npm run build
sv creates and configures Svelte projects.
Creating a project
# create a new project
npx sv create my-app
To recreate this project with the same configuration:
# recreate this project
npx sv@0.16.5 create --template minimal --types ts --install npm .
Developing
Install dependencies with npm install (or pnpm install or yarn), then
start a development server:
npm run dev
# or start the server and open the app in a new browser tab
npm run dev -- --open
Building
Build a production version:
npm run build
Preview the production build with npm run preview.
Deployments may require an adapter for the target environment.
The shared visual language and dashboard conventions are documented in docs/DESIGN_SYSTEM.md.
Empirically derived weapon and gear level-range calculations, rounding rules, validation boundaries, and regression observations are documented in docs/STAT_LEVEL_SCALING.md.