Ecosystem Overview

RANDSUM is a monorepo with three layers: a notation parser, a dice engine, and game-specific packages. Every package is TypeScript-first, ships ESM + CJS with full type declarations, and is published to npm under @randsum.

Dependency diagram

@randsum/notation              (zero dependencies)
  |
  +-- @randsum/roller          (core dice engine)
  |     |
  |     +-- @randsum/games     (TTRPG game packages)
  |     |     +-- /blades        (Blades in the Dark)
  |     |     +-- /daggerheart   (Daggerheart)
  |     |     +-- /fifth         (D&D 5e)
  |     |     +-- /pbta          (Powered by the Apocalypse)
  |     |     +-- /root-rpg      (Root RPG)
  |     |     +-- /salvageunion  (Salvage Union)
  |     |
  |     +-- @randsum/display-utils       (UI helpers, peers on roller)
  |           |
  |           +-- @randsum/component-library (React components, also peers on notation + react)

Every package depends only on packages above it in the tree. Game packages never depend on each other. The component library depends on display-utils (dev), and peers on notation, roller, and react.

Packages by layer

Foundation: Notation

@randsum/notation

Zero-dependency dice notation parser, validator, and type system. Parses strings like "4d6L" into structured options, validates user input, and provides the shared types that the rest of the ecosystem builds on.

Learn more

Core: Roller

@randsum/roller

The dice rolling engine. Accepts numbers, notation strings, or options objects and returns typed roll results with full modifier support. Re-exports three notation functions (isDiceNotation, notation, validateNotation) for convenience — most projects only need this package.

Learn more

Game packages

@randsum/games

Code-generated TTRPG game packages, each available as a subpath export. Every game wraps @randsum/roller with game-specific dice pools, modifiers, and outcome interpretation — generated from .randsum.json specs.

Learn more

Currently supported games: Blades in the Dark, D&D 5e, Daggerheart, Powered by the Apocalypse, Root RPG, and Salvage Union.

Tools

@randsum/display-utils

Internal package for step visualization, modifier documentation, and StackBlitz integration. Not installed directly — consumed by the component library to share display logic across RANDSUM UI surfaces.

Learn more

@randsum/component-library

React component library providing interactive dice rolling UI elements. Depends on roller, notation, and display-utils.

Learn more

Discord Bot

Roll dice directly in Discord with slash commands. Supports all game packages with rich embeds.

Learn more

Where to start

Pick the package that matches your use case:

Use case	Install	Start here
Roll dice in any JS/TS project	bun add @randsum/roller	Roller Getting Started
Parse or validate notation strings without rolling	bun add @randsum/notation	Notation Getting Started
Build a TTRPG app with game-specific mechanics	bun add @randsum/games	Games Getting Started
Add dice UI components to a React app	bun add @randsum/component-library	Component Library

Most developers should start with @randsum/roller. It re-exports the three most common notation functions (isDiceNotation, notation, validateNotation) plus all types, so most projects only need one install. Add @randsum/notation if you need notationToOptions, optionsToNotation, tokenize, or other transform functions.

Design principles

• Zero core dependencies — @randsum/notation has no runtime dependencies; @randsum/roller depends only on notation
• Throws on invalid input — roll() throws typed errors on bad input (ValidationError, ModifierError, or NotationParseError); validate user-provided strings with isDiceNotation() or validateNotation() before rolling
• Game packages are code-generated — every game is defined as a .randsum.json spec and transformed into TypeScript by an internal codegen pipeline
• Strict TypeScript — isolatedDeclarations, exactOptionalPropertyTypes, noUncheckedIndexedAccess, no any
• Bundle size enforced — roller under 10KB, notation under 13KB, game packages under 8KB each