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.