Introduction

What is Narro, and should I be writing markdown or React?

4 min readView as markdown6 chunks · 1.5k tokens in docspack

Narro builds presentations out of web technology. A deck is either a markdown file or a tree of React components; either way it renders in a browser, lives in Git, and exports to PPTX, PDF, or a single self-contained HTML file.

Two ways to write a deck

Both modes use the same runtime, the same navigation, and the same export pipeline. Pick by how much control you want, not by how big the deck is — markdown decks can drop into React wherever they need to.

Markdown mode

One .md file, no project to scaffold:

npx @getnarro/cli new deck.md
npx @getnarro/cli dev deck.md

The dialect is designed as a ladder with no cliff: plain markdown → layout directives → per-element Tailwind → your own React layouts → full MDX with live components. You climb it without ever rewriting the deck. See Markdown mode.

React mode

A Vite project where every slide is a component:

npm create narro@latest my-deck

Reach for this when slides need real application logic — live data, custom interaction, a component you already have. See First deck.

And video

@getnarro/video renders a React composition to MP4. It is a separate package with the same shape of idea: the narration is a list of sentences, the visuals are components, and every duration is measured from the audio rather than typed. Edit a sentence and the cut moves, the captions re-page and the .srt regenerates — which is what makes a translation cost what the original did.

npx narro-video new ./launch-teaser
npx narro-video render ./launch-teaser

See Video.

And terminal demos

@getnarro/terminal holds a terminal session as text: the commands, the pauses, the moments worth naming — and, once you have run it, the bytes they actually printed. From that one file comes a GIF, an animated SVG, a still, a terminal on a slide, an embeddable player, or a shot in a video.

npx narro-terminal render demo.term.json          # a GIF
npx narro-terminal record demo.term.json --check  # fail when the demo goes stale

Rendering never runs anything — a deck build draws the commands being typed — and record is the one command that executes, after printing what it is about to run. The pair is what a screen recording cannot be: --check re-runs the demo and tells you the tool stopped saying what the demo says.

See Terminal.

Why not PowerPoint

Narro is worth the setup when you need something a WYSIWYG tool cannot give you:

  • Code that is really code — a fence in your deck is the same text your editor lints, syntax highlighted at build time, and live components if you want them running on the slide
  • Version control — a deck is text, so it diffs and merges
  • Reuse — a slide is a component; a component works in the next deck too
  • Generation — text in, deck out, which is what makes AI authoring practical

If your deck is five bullet points and a photo, use PowerPoint. Narro is for the cases where you have been fighting the tool.

Packages

PackageWhat it is
@getnarro/annotateFeedback on a Narro recording — typed notes anchored to a moment, staleness against the cast they were written about, and a briefing a coding agent can act on
@getnarro/atlasA spatial canvas for Narro — a camera path as text, one pure camera function over it, and scene providers a deck, a video and a web page all render the same way
@getnarro/cliCLI tools for creating and managing Narro presentations
@getnarro/coreThe React runtime for Narro presentations — Presentation, Slide, navigation, transitions, and speaker notes
@getnarro/docsNarro’s documentation as data — markdown pages, a generated component API reference, and llms.txt
@getnarro/docspackNarro’s documentation as a docspack — version-locked chunks an agent installs once and searches offline
@getnarro/markdownMarkdown & MDX authoring for Narro presentations
@getnarro/marketplaceThemes, colour schemes, and templates for Narro presentations
@getnarro/mcp-serverMCP (Model Context Protocol) server for AI-assisted Narro presentation creation
@getnarro/replayRecord a web app once and replay it as real DOM — a portable cast format, an embeddable player, and a self-contained HTML page
@getnarro/shared-uiSlide components for Narro presentations — headings, text, lists, code, media, charts, and layouts
@getnarro/terminalTerminal playbooks for Narro — a text format for a terminal session, a screen that is a pure function of the frame number, and a renderer that draws it on a grid
@getnarro/videoFrame-deterministic video framework for Narro — a brand system, a React timeline runtime, narration-derived timing, a headless-Chrome renderer, and a scrub studio
@getnarro/video-marketingMarketing scene components for @getnarro/video — lower thirds, stat counters, feature grids, pull quotes, device frames, callouts and end cards, all brand-driven and frame-deterministic
create-narroScaffold a new Narro presentation

The npm package named narro is unrelated to this project. Everything here is under the @getnarro/ scope. The binary called narro comes from @getnarro/cli.

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?
Zooming canvasHow do I zoom and pan across one big canvas instead of cutting between slides?
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?
VideoHow do I turn a story into a video, and keep it right when the words, the product or the source changes?
Recording a web appHow do I put a demo of my product in a deck or on a landing page without shipping a video of it?
Embedding a replayHow do I embed a recorded demo of my app in my React app, my Astro site, or any other page?
TerminalHow do I put a terminal demo in a deck, a README or a video, and find out when the tool it demonstrates stops saying what the demo says?
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?