API reference

LessonKit publishes TypeScript declarations on npm (dist/*.d.ts) and documents behavior in the guides below.

Guides vs reference

Read this when…	Start here
Learning workflows (first course, LMS export, theming)	React developer guides
Validating props, IDs, manifest fields, CLI flags	Reference pages on this site (below) + Block catalog
TypeScript signatures only	TypeDoc (built on Read the Docs; regenerate locally with npm run docs:api)

TypeDoc lists signatures — high-traffic exports include @example blocks in source (regenerate with npm run docs:api). For behavior, prefer narrative guides first, then reference contracts.

When TypeDoc and guides disagree

When TypeDoc and guides disagree, the narrative guide wins until the release noted in CHANGELOG. File an issue if TypeDoc shows a public export with no guide coverage.

Before opening a GitHub issue for API usage: Check Components and hooks, the relevant component page, and narrative references below. TypeDoc signatures alone are not the supported learning path for runtime behavior.

Generated API (TypeDoc)

Browse generated TypeScript API docs (built with the docs site on Read the Docs). Each row links TypeDoc to the narrative guide to read first.

Package	Generated reference	Narrative guide
@lessonkit/react	TypeDoc — react	Components and hooks · LessonkitConfig
@lessonkit/react/blocks	TypeDoc — react/blocks	Block catalog · Block cookbook
@lessonkit/react/testing	TypeDoc — react/testing	Contributing
@lessonkit/core	TypeDoc — core	Core reference
@lessonkit/core/testing	TypeDoc — core/testing	Contributing
@lessonkit/cli	TypeDoc — cli	CLI reference · Packaging and CLI
@lessonkit/xapi	TypeDoc — xapi	xAPI reference · Telemetry and xAPI
@lessonkit/lxpack	TypeDoc — lxpack	Packaging reference · packageLessonkitCourse
@lessonkit/lxpack/bridge	TypeDoc — lxpack/bridge	LXPack bridge
@lessonkit/themes	TypeDoc — themes	Theming reference
@lessonkit/accessibility	TypeDoc — accessibility	Accessibility reference

Packaging API highlights

Export	Package	Narrative
packageLessonkitCourse	@lessonkit/lxpack	Packaging reference · LMS Go-Live
createXAPIClient	@lessonkit/xapi	xAPI reference · LRS operations
LessonkitConfig	@lessonkit/react	LMS Go-Live · Components and hooks

Full index: TypeDoc home.

Monorepo maintainers regenerate locally: npm run build:packages && npm run docs:api. TypeDoc output lives under docs/_static/typedoc/ and is generated on Read the Docs — local Sphinx builds show broken TypeDoc links until you run docs:api. See Contributing — TypeDoc generation.

Also use:

1. IDE — Go to Definition on @lessonkit/react imports in a scaffolded project

2. Storybook — component states and props visually

3. Narrative guides — Components and hooks · Block catalog

Interactive

Resource	URL
Storybook (component states)	GitHub Pages · npm run storybook in the monorepo
Live course demos	Examples

Packages

Package	Types	Narrative docs
@lessonkit/react	import type { … } from "@lessonkit/react"	Components and hooks
@lessonkit/react/blocks	Block components only (tree-shake friendly)	Block catalog
@lessonkit/react/testing	Test reset helpers (see table below)	Contributing
@lessonkit/core	import type { … } from "@lessonkit/core"	Core reference
@lessonkit/core/testing	Headless test reset helpers (see table below)	Contributing
@lessonkit/xapi	import type { … } from "@lessonkit/xapi"	xAPI reference
@lessonkit/lxpack	Packaging API	Packaging reference
@lessonkit/themes	Theme presets and tokens	Theming reference
@lessonkit/accessibility	Focus and motion utilities	Accessibility reference

@lessonkit/react/testing exports

Export	Purpose
resetQuizWarningsForTests	Clear Quiz dev warnings between tests
resetAssessmentWarningsForTests	Clear assessment guard warnings
resetLessonMountRegistryForTests	Reset lesson mount registry
resetCompoundValidationWarningsForTests	Clear compound child validation warnings
resetLessonkitProviderStorageForTests	Clear session storage used by provider
resetCourseStartedTrackingFlightForTests	Reset course_started delivery flight state

@lessonkit/core/testing exports

Export	Purpose
resetTelemetryBuilderWarningsForTests	Clear telemetry builder dev warnings
resetStoragePortForTests	Reset default storage port
resetSharedVolatileSessionIdForTests	Reset tab session id helper state
resetCourseStartedEmitFlightForTests	Reset headless course_started emit flight

Prefer these subpaths over deprecated main-entry reset helpers.

Shared assessment and bridge types

Import from @lessonkit/core (re-exported by @lessonkit/react where relevant):

Type	Purpose
McqAssessmentProps	Props shape for Quiz, KnowledgeCheck, and MCQ-style assessments (replaces deprecated McqAssessmentDescriptor from lxpack)
LmsBridgeMode	"auto" | "off" — controls forwarding telemetry to the LXPack parent iframe bridge

Production guardrails

API	Package	Purpose
assertProductionCourseConfig(config)	@lessonkit/react	Throws in production when console telemetry/xAPI sinks, tracking enabled without delivery, or required observability hooks are missing
shouldEnforceProductionGuard()	@lessonkit/react	Returns false in test mode (import.meta.env.MODE === "test") even when NODE_ENV=production
onXapiTransportError	config.observability	Required when xAPI delivery is configured; called when transport fails after retries (statement re-queued)

See the production checklist for the full observability hook matrix (1–6 hooks depending on tracking/xAPI configuration).

Framework 1.5 blocks

Export from @lessonkit/react: BranchingScenario, BranchNode, BranchChoice, Embed, Chart, useBranchingScenario. See Block catalog — 1.5 and Migration 1.4 → 1.5.

Framework 1.6 blocks

Export from @lessonkit/react / @lessonkit/react/blocks (catalog v3, framework 1.6.0+):

Block	Role
Table, Timeline, ImageJuxtaposition, ImageSequence, Collage, AudioRecorder, QrContent, AdventCalendar	Content
CombinationLock, Crossword, WordSearch	Assessment (checkId required)
GameMap, MapStage, MapExit	Compound (spatial map; blockId on container)

Full prop contracts: Block catalog — 1.6.0 · generated prop tables. Discover blocks from CLI: lessonkit blocks list --json.

Framework 1.7 blocks

Export from @lessonkit/react / @lessonkit/react/blocks (catalog v3, framework 1.7.0+):

Block	Role
SortParagraphs, GuessTheAnswer, MultimediaChoice	Assessment (checkId required)
SingleChoiceSet	Compound (child Quiz / KnowledgeCheck only)

Quiz / KnowledgeCheck variants: answers, shuffleChoices, shuffleSeed, choiceFeedback — see Migration 1.6 → 1.7.

Full prop contracts: Block catalog — 1.7.0 · generated prop tables.

Machine-readable contracts

Artifact	Package path
Block catalog v1–v3	@lessonkit/react/block-catalog.v3.json
Block contract v1–v3	@lessonkit/react/block-contract.v3.json
Telemetry catalog	@lessonkit/core/telemetry-catalog.v3.json
Identity contract	@lessonkit/core/identity-contract.v1.json

See Block catalog and Glossary for version naming.

IDE tips

In a scaffolded course, run npm run dev and use Go to Definition on imports from @lessonkit/react. For headless APIs (createLessonkitRuntime, plugins), import from @lessonkit/core directly. In tests, prefer @lessonkit/react/testing and @lessonkit/core/testing over deprecated main-entry reset helpers.