A companion app for the Nimble TTRPG. A comprehensive digital character sheet application for the Nimble RPG system. Built as a Turborepo monorepo with Next.js, Express.js, Astro Starlight, TypeScript, and Tailwind CSS, featuring offline-first architecture with local storage persistence and optional Google authentication.
Features three main applications:
- Character Sheet App - Digital character management and dice rolling
- API Server - Authentication and cloud sync backend
- RPG Vault - Complete Nimble RPG documentation and rules reference
- Complete Rules Reference - 450+ markdown files with comprehensive Nimble RPG documentation
- Astro Starlight Framework - Fast, searchable documentation site with beautiful presentation
- Fantasy Theme - Custom parchment background with Beaufort Pro Heavy and Avenir Next Condensed fonts
- Organized Sidebar - Categorized sections for Heroes, Magic, Items, Foes, Game System, and Homebrew content
- Mobile Responsive - Optimized for desktop and mobile reading
- Search Functionality - Built-in search across all content
- Auto-Generated Navigation - Sidebar automatically generated from markdown file structure
- Upload and crop character portraits with intuitive interface
- Client-side image processing with automatic resizing (100x100px profile, 50x50px thumbnail)
- Image history management - browse and switch between previous portraits
- IndexedDB storage for offline functionality
- NEW: Automatic cloud backup to Vercel Blob Storage (when configured)
- NEW: Bidirectional sync - images sync with character data
- Redesigned character header with avatar display
- SVG placeholder for characters without images
- Graceful degradation when server unavailable
- Optional Google OAuth login for user authentication
- Secure session management with Express.js backend
- User profiles with avatar display
- Persistent login state across sessions
- Features can now grant multiple effects (abilities, resources, boosts, etc.)
- Improved effect tracking system with granular source attribution
- New UI components for displaying complex feature effects
- Better support for multi-benefit class and ancestry features
- Multiple Characters: Create, switch between, and manage multiple characters
- App Modes: Basic mode (simplified) or Full mode (complete character sheet)
- Class System: Four core classes (Fighter, Wizard, Cleric, Rogue) with level progression
- Subclass System: Specialized subclasses unlock at appropriate levels with unique features
- Ancestry System: Character origins with size categories, stat boosts, proficiencies and resistances
- Background System: Character histories with passive features and cultural descriptions
- Custom Content: Upload and manage custom classes, ancestries, backgrounds, abilities, and spells
- Level Progression: Automatic feature grants and hit dice advancement
- Attributes: Strength, Dexterity, Intelligence, Will (range: -2 to 10)
- Hit Points: Current/Max HP with temporary HP support (D&D 5e rules)
- Action Tracker: Combat action management with encounter tracking
- Skills: 10 predefined skills with attribute associations and custom modifiers
- Dice System: Advanced d20 mechanics with advantage/disadvantage
- Attack Rolls: Exploding criticals, miss on natural 1
- Ability Rolls: Custom dice expressions with attribute modifiers
- Saving Throws: Separate buttons for each attribute
- Activity Log: Comprehensive action and dice roll tracking
- Ability System: Freeform and action abilities with usage tracking
- Frequency Types: Per-turn, per-encounter, and at-will abilities
- Roll Integration: Abilities can trigger custom dice rolls
- Smart Resets: Automatic ability resets on turn/encounter end
- Actions Panel: Quick access to equipped weapons and usable abilities
- Equipment Management: Weapons, armor, and freeform items
- Armor Types: Main armor vs supplementary armor with automatic replacement
- Size-Based Limits: Configurable weapon size restrictions
- Smart Inventory: Equipped items don't count toward size limits
- Dex Bonus Calculation: Armor-aware dexterity bonus with visual indicators
- Generic Resources: Customizable resource pools (mana, fury, focus, stamina, etc.)
- Color Schemes: 8 predefined color schemes with percentage-based gradients
- Icon System: 23+ categorized icons (magic, combat, nature, etc.)
- Reset Conditions: Per-turn, per-encounter, safe rest, never, or manual
- Reset Types: To maximum, to zero, or to custom default value
- Resource Bar: Visual progress bars with color-coded status
- Quick Actions: Fast spend/restore buttons (1, 3, 5) plus custom amounts
- Activity Logging: Comprehensive tracking of resource usage
- Class Progression: Automatic feature grants based on class and level
- Subclass Selection: Choose specializations that provide unique abilities
- Feature Tracking: Complete history of granted features with validation
- Temporary HP: D&D 5e compliant damage absorption
- Encounter Management: Turn-based mechanics with action tracking
- Settings Panel: Global app configuration and mode switching
- Character Selector: Easy character creation and switching
- Responsive Design: Mobile-first with collapsible sections
- Offline-First: No server required, works completely offline
- Auto-Save: All data persists to local storage automatically
- Google OAuth: Sign in with Google account (optional)
- User Profiles: Display user name and avatar when logged in
- Session Persistence: Stay logged in across browser sessions
- Secure Backend: Express.js API server with Passport.js authentication
- Privacy First: Authentication is optional, app works fully offline
- Node.js 18.0 or higher
- npm or yarn package manager
# Clone the repository
git clone <repository-url>
cd nimble
# Install dependencies
npm install
# Configure Google OAuth (optional)
# 1. Copy apps/sidekick-api/.env.example to apps/sidekick-api/.env
# 2. Add your Google OAuth credentials (see apps/sidekick-api/README.md for setup)
# Start development servers (all apps)
npm run dev
# Or run them separately:
npm run dev:web # Character sheet app (port 3000)
npm run dev:api # API server (port 3001)
npm run dev:vault # Documentation site (port 4321)
# Open your browser to:
# - Character Sheet: http://localhost:3000
# - Documentation: http://localhost:4321# Create production build
npm run build
# Start production server
npm start- App Menu: Click the gear icon to access settings and character selection
- Mode Selection: Choose Basic mode (simplified) or Full mode (complete)
- Character Creation: Use the character selector to create new characters
- Character Switching: Easily switch between existing characters
- Name: Click the character name to edit
- Class Selection: Choose from Fighter, Wizard, Cleric, or Rogue
- Ancestry Selection: Choose from Human, Elf, Dwarf, Halfling, or upload custom ancestries
- Background Selection: Choose from Noble, Scholar, Soldier, Folk Hero, or upload custom backgrounds
- Level Progression: Set character level to automatically grant class features
- Subclass Choice: Select subclass specializations when they become available
- Attributes: Use the number inputs to set attribute values (-2 to 10)
- Hit Points: Set max HP and track current/temporary HP with hit dice
- Skills: Adjust skill modifiers (0-20) for each of the 10 skills
- Resources: Configure custom resource pools with color schemes and icons
- Abilities: Add custom abilities with usage frequencies and roll mechanics
- Advantage/Disadvantage: Use the global toggle at the top
- Attribute Rolls: Click "Roll" for checks or "Save" for saving throws
- Skill Rolls: Roll individual skills with automatic attribute bonuses
- Attack Rolls: Equip weapons to see attack actions with damage
- Ability Rolls: Use abilities that automatically trigger custom dice rolls
- Initiative: Roll initiative to start encounters and set action counts
- Action Tracker: Monitor current actions during encounters
- End Turn: Reset actions and per-turn abilities
- End Encounter: Exit combat and reset all abilities
- Actions Panel: Quick access to weapons and abilities
- Equipment: Use inventory to add items, toggle equip/unequip for weapons and armor
- Resources: Create custom pools with color schemes and icons, use quick adjustment buttons
- Health: Use quick damage/heal buttons or enter custom amounts, temporary HP absorbs damage first
- Combat: Roll initiative to start encounters, use action tracker to manage turn-based combat
- Build System: Turborepo for efficient monorepo management
- Workspaces: npm workspaces for dependency management
- Framework: Next.js 14 with App Router
- Language: TypeScript for type safety
- Styling: Tailwind CSS + shadcn/ui components
- Validation: Zod for runtime type checking
- Storage: Local Storage with repository abstraction
- Icons: Lucide React icons
- Framework: Express.js REST API
- Authentication: Passport.js with Google OAuth 2.0
- Session Management: express-session with secure cookies
- Environment: dotenv for configuration
- Development: tsx for TypeScript execution
- Framework: Astro with Starlight theme
- Content: 450+ Markdown files with frontmatter
- Styling: Custom CSS with fantasy theme
- Fonts: Beaufort Pro Heavy + Avenir Next Condensed
- Features: Search, responsive design, auto-generated navigation
npm run dev- Start all development servers (web + API + vault)npm run dev:web- Start only character sheet appnpm run dev:api- Start only API servernpm run dev:vault- Start only documentation sitenpm run build- Build all apps for productionnpm run lint- Run ESLint checks on all workspacesnpm run typecheck- Run TypeScript type checking
npx turbo dev --filter=@nimble/web- Run character sheet app onlynpx turbo dev --filter=@nimble/api- Run API server onlynpx turbo dev --filter=@nimble/vault- Run documentation site only
- TypeScript: Strict type checking enabled
- ESLint: Code linting with Next.js recommended rules
- Type Safety: Runtime validation with Zod schemas
- Component Architecture: Modular, reusable components
The app is built as a static Next.js application and can be deployed to any static hosting service:
- Vercel: Deploy directly from Git repository
- Netlify: Drag and drop the
outfolder afternpm run build - GitHub Pages: Use the static export output
- Any CDN: Upload the build output to your preferred hosting
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is open source and available under the MIT License.
Sidekick is designed for the Nimble RPG system. For game rules and additional resources, visit the official Nimble RPG website.
Built with ❤️ for the Nimble RPG community
