ShadowSIN

Shadowrun is a tabletop RPG set in a dystopian near-future where magic and technology collide. Characters ("runners") have a lot going on — attributes, skills, augmentations, gear, spells, vehicles, contacts — and keeping track of it all on paper is a pain.

ShadowSIN is a digital character sheet that makes that easier. Load up your runner, check your stats, track damage, and get back to the action.

⚠️ Work in progress - here be dragons. This project is early in development choom. Expect missing features, rough edges, and the occasional fire.

---

Contributing / Getting Started

Prerequisites

Tool	Version	Notes
Node.js	>=25.0.0	Check with node -v
Yarn	4.x (via Corepack)	See below

Enable Corepack to get the correct Yarn version automatically:

npm install -g corepack
corepack enable

After that, yarn commands will use the version pinned in package.json automatically — no global install needed.

First-time setup

# 1. Clone the repo
git clone git@github.com:CptnFizzbin/shadow-sin.git
cd shadow-sin

# 2. Install dependencies
yarn install

# 3. Start the dev server
yarn dev

Then open http://localhost:3000. The dev server supports HMR — changes are reflected immediately without a full reload.

Note: src/routeTree.gen.ts is auto-generated by the Vite plugin on yarn dev / yarn build. Never edit it manually — your changes will be overwritten.

---

Tech Stack

Layer	Technology
UI framework	React 19
Routing	TanStack Router (file-based)
State management	TanStack Store (StoreSlice)
Component library	MUI v7
Build tool	Vite 8 + Rolldown
Language	TypeScript 6
Unit tests	Vitest + Testing Library
E2E tests	Playwright
Linting	ESLint (TypeScript-ESLint)
Runtime validation	Zod

---

Project Structure

src/
  character/        Character loading, saving, and migrations
  components/       React components (character sheet, builder, gear, UI)
  integrations/     TanStack Query/Router/Form wiring, MUI theme setup
  lib/              Generic utilities (storage, number/merge helpers)
  routes/           File-based TanStack Router routes
  system/           Domain types — CharacterSheet, gear, magic, skills, etc.
  env.ts            Environment variable declarations (@t3-oss/env-core)
  main.tsx          App entry point

testUtils/          Shared test helpers and fixtures
e2e/                Playwright end-to-end specs

Key conventions:

• Path alias #/ → src/ (configured in tsconfig.json)
• All local imports must include the file extension (.ts or .tsx)
• Character state lives in CharacterSheetStore — subscribe reactively via useCharacterSheet(selector)

---

Commands

yarn dev            # Dev server on :3000 with HMR
yarn build          # Production build
yarn preview        # Preview the production build locally

yarn test           # Run unit tests once (alias for test:unit)
yarn test:unit      # Vitest unit tests (run once)
yarn test:unit:ui   # Vitest with browser UI
yarn test:e2e       # Playwright end-to-end tests
yarn test:e2e:ui    # Playwright with browser UI
yarn test:all       # Unit + E2E in parallel

yarn fix            # Auto-fix all lint and formatting issues ✅ run this before committing
yarn lint           # Check lint without fixing
yarn tsc            # TypeScript type-check (no emit)

Before opening a PR: run yarn fix to ensure formatting, linting, and types are clean.

---

Adding a New Route

Create a file under src/routes/ — TanStack Router's Vite plugin picks it up automatically and regenerates src/routeTree.gen.ts on the next yarn dev / yarn build.

---

Disclaimer: ShadowSIN is an independent fan project and is not affiliated with, endorsed by, or connected to Catalyst Game Labs. Shadowrun and all related content are trademarks and/or copyrights of Catalyst Game Labs. All rights reserved.