Roadmap

Small framework-agnostic TypeScript helpers for building roadmap data and exporting SVG/JSON.

Build

pnpm run build

Basic usage

import {
  Comment,
  Group,
  Left,
  Right,
  Spine,
  Topic,
  addNode,
  createRoadmap,
  exportToJSON,
  exportToSVG,
  removeNode,
  updateNode,
} from '@henryhale/roadmap';

const roadmap = createRoadmap('AI Engineer', () => [
  Spine('intro', { title: 'Introduction' }, () => [
    Right(Topic('what-ai', { title: 'What is AI?', link: 'https://example.com/ai' })),
    Left(
      Group('core-ideas', { title: 'Core Ideas' }, () => [
        Topic('tokens', { title: 'Tokens' }),
        Comment('context-note', { title: 'Context matters' }),
      ]),
    ),
  ]),
]);

const withMore = addNode(
  roadmap,
  'intro',
  Right(Topic('history', { title: 'A brief history of AI' })),
);

const updated = updateNode(withMore, 'tokens', {
  title: 'Tokens and Tokenization',
  description: 'How text becomes model input.',
});

const json = exportToJSON(updated);
const svg = exportToSVG(updated);

Pure data operations

Use node factories to create nodes, then use pure operations to update roadmap data. This works well in UI state because every operation returns a new roadmap object.

let roadmap = createRoadmap('AI Engineer');

roadmap = addNode(roadmap, null, Spine('intro', { title: 'Introduction' }));
roadmap = addNode(
  roadmap,
  'intro',
  Right(Group('core', { title: 'Core Ideas' })),
);
roadmap = addNode(roadmap, 'core', Topic('tokens', { title: 'Tokens' }));
roadmap = updateNode(roadmap, 'tokens', {
  title: 'Tokens and Tokenization',
  link: 'https://example.com/tokens',
});
roadmap = removeNode(roadmap, 'tokens');

Insertion rules are intentionally small:

• addNode(roadmap, null, Spine(...)) appends a spine node.
• addNode(roadmap, spineId, Left(...)) or Right(...) adds a branch to a spine.
• addNode(roadmap, groupId, Topic(...)) or Comment(...) adds a child to a group.

Data shape

interface RoadmapData {
  id: string;
  title: string;
  spine: RoadmapSpineNode[];
}

A spine node has left and right branches. A branch can be a topic, comment, or group. A group can contain topic and comment children.

Licence

© 2026-present Henry Hale - Released under MIT license