Packages

idocs is five packages, versioned together. Most people only ever install create-idocs, which pulls in the rest.

Package	Role	You install it
create-idocs	Scaffolds a new site: npm create idocs@latest.	never; npm create runs it
@the-package-labs/idocs	The command line, idocs.	as a dev dependency
@the-package-labs/idocs-astro	The Astro integration and the <Diagram> component.	in your site
@the-package-labs/idocs-react	The interactive diagram component and its styles.	in your site
@the-package-labs/idocs-core	Schema, compiler, layout, router and timeline.	pulled in by the others

All five need Node 22 or later. All are published under the MIT license.

create-idocs

npm create idocs@latest my-docs

Copies the starter project into a folder that does not exist yet or is empty, filling in its name. The project uses pnpm. It carries its own copy of the template, so it works without any template repository.

@the-package-labs/idocs

The idocs command. See the CLI reference.

@the-package-labs/idocs-astro

Export	What it is
default	The Astro integration: idocs({ dir }).
./Diagram.astro	The <Diagram> component.
./starlight.css	The Starlight bridge stylesheet.
./virtual	Types for virtual:idocs/diagrams.

Needs astro 6 or later. See props and options.

@the-package-labs/idocs-react

Export	What it is
DiagramView	The whole interactive diagram: the canvas with the panel floating over it (outline and views), the bar under it (scenarios, player, slider and steps), and the drawer.
NodeCard, Icon, IconTile	The building blocks of a card.
SequenceView	The sequence presentation of a scenario.
./styles.css	The renderer’s styles and tokens.

Needs react and react-dom 19 or later.

@the-package-labs/idocs-core

Two entry points.

@the-package-labs/idocs-core

Browser-safe: no node:*, YAML, Zod or Iconify. This is the part the client bundle gets.

Area	What it provides
Types	CompiledDiagram, CompiledNode, CompiledEdge, CompiledView, CompiledScenario, Layout and friends. All plain JSON.
layoutView	Places a view’s nodes, zones and edges, given measured card sizes.
routeEdges	The orthogonal edge router.
buildStory	Turns a scenario into the lanes, boxes and links of the story view.
buildTimeline, frameAt	Turns a scenario into a timeline, and a time into a frame. Pure.
attachNested, nestedDiagrams, linkDiagrams	Put the diagrams a diagram can open inside it as nested (loadProject does this for you), find them, and check what spans diagrams. See nested diagrams.
scopeSvgIds	Gives an inline SVG’s ids a prefix, so two copies on a page do not collide.
Constants	The built-in node and edge kinds, step kind colours and the default card width.

@the-package-labs/idocs-core/node

Node only. Everything that reads files or parses YAML.

Export	What it does
loadProject(root, dir?)	Loads and compiles every diagram under <root>/<dir>. Returns { diagrams, diagnostics, watch }.
compileDiagram(source)	Compiles one diagram. The result also carries a non-enumerable where that finds a path in the source files, for linkDiagrams.
formatDiagnostic(d)	Formats a diagnostic as file:line:col severity message.
resolveIcon(spec), searchIcons(query)	Find icons in the bundled sets.
renderMarkdown(md)	The Markdown renderer used for notes and node docs. Raw HTML is dropped.
authoringJsonSchema()	The JSON Schema written by idocs schema.
RootSchema, FamilySchema, KNOWN_KEYS	The Zod schema, for tooling.

Keep the entry points apart

Importing @the-package-labs/idocs-core/node from code that ships to the browser pulls YAML, Zod and the icon sets into your bundle. Compile on the server or in a build script, and pass the JSON to the client.

Versions

The five packages are versioned together, so upgrade them together:

pnpm up "@the-package-labs/idocs-*" idocs create-idocs --latest

In the idocs repository, each package’s exports point at TypeScript sources so nothing has to be built to develop. The published packages point at compiled dist/ files.