🏗️ Architecture

Which package owns what, and why is the seam where it is?

2 min readView as markdown

The packages

@getnarro/core          the runtime: Presentation, Slide, navigation, motion
@getnarro/shared-ui     ~50 slide components, no runtime dependency on core
@getnarro/markdown      the markdown/MDX dialect + its Vite plugin
@getnarro/marketplace   themes, colour schemes, template metadata
@getnarro/cli           new / dev / build / export / import
@getnarro/mcp-server    MCP tools and resources for AI assistants
@getnarro/docs          these pages as data + the generated API reference
create-narro            npm create narro

Why the seams are there

core and shared-ui are separate because they change at different rates and for different reasons. core owns behaviour — how navigation works, when a slide is active, how transitions run. shared-ui owns appearance. A deck can use core alone and hand-write its markup, which is exactly what the minimal template did until the docs made shared-ui the assumed baseline.

shared-ui has no i18n and no state. Components take text as props. That keeps them usable from markdown, from React, and from generated code without each caller having to set up a provider.

markdown does not live in cli. The dialect is a library — the Vite plugin, the compiler, and the layouts are all importable — so a scaffolded project can use it without depending on the CLI’s much heavier install (Playwright, sharp, the Google APIs client).

create-narro does not live in cli either, and cannot: npm create narro resolves the create-narro package specifically, and scaffolding has to run before anything is installed. @getnarro/cli depends on it so narro create and create-narro share one implementation and one copy of the templates.

How a deck renders

Both modes converge on the same runtime.

React mode. Your App.tsx composes Presentation and Slide directly. Vite builds it like any other React app.

Markdown mode. The @getnarro/markdown Vite plugin compiles deck.md into virtual modules:

virtual:narro/deck            the deck component
virtual:narro/deck.css        Tailwind, scanning the deck for utility classes
virtual:narro/slot/<i>/<n>    one compiled MDX module per slot
virtual:narro/layout/<name>   a resolved layout component

The result is a tree of Presentation and Slide — the same components React mode uses. This is why the two modes share navigation, transitions, presenter view, and export: there is only one runtime, and markdown is a front end to it.

Editing the deck recompiles only the slots whose content changed.

Core concepts

A slide is a component. No slide registry, no ordering metadata — order is source order, and a slide is addressable by id.

Activity is context, not a prop. useSlideActive() tells a component whether its slide is on screen. This is what lets animations start when the audience sees them, and lets off-screen backgrounds stop doing work.

Fragments are navigation steps. They participate in the same next/previous sequence as slides, which is why a fragment reveal and a slide advance feel identical to the presenter.

Layouts resolve by name, most specific first. A deck’s own layouts/ directory shadows the theme, which shadows the built-ins. Overriding one layout never means forking the rest.

IntroductionWhat is Narro, and should I be writing markdown or React?
InstallationWhat do I install, and what does the project look like afterwards?
First DeckWhat does a working React deck look like, end to end?
Markdown ModeHow do I split a slide, style one word, or reveal a line — without leaving the markdown file?
Writing AI PromptsWhat do I tell an AI so the deck it writes actually builds?
Rules for AI AgentsWhat do I paste into my repo so an agent stops writing decks that build wrong?
React APIWhich component or hook do I import, and what does it take?
CLIWhich command do I run, and what are its flags?
Markdown APIHow do I read, edit, or validate a deck file from my own code instead of by hand?
Component ReferenceWhat props does this component take, and which package do I import it from?
Verifying a deckHow do I know my deck is actually correct?
AnimationHow do I reveal a list one line at a time, or move between slides with something other than a cut?
NavigationHow does the audience move through the deck, and how do I present it?
Canvas & PositioningHow do I put something at an exact position instead of in the flow?
Images & MediaHow do I use an image as a background, tint it, or embed a video?
ArchitectureWhich package owns what, and why is the seam where it is?
Transform ModeHow do I zoom and pan across one big canvas instead of cutting between slides?
Import & ExportHow do I get this deck out as PPTX, PDF, or one file I can email?
AI IntegrationHow do I wire an AI assistant up to Narro so it can write and build decks?
ThemingHow do I change the colours, fonts, and overall look of a deck?
Deck TemplatesHow do I define one house style with named layouts my slides can reference, like a PowerPoint master?
TroubleshootingSomething is wrong with my deck. What is it, and how do I fix it?
LimitationsWhat can't Narro do, and what do I do instead?