Built by MoreThought.
Point it at a local app. FlowMap reads the routes, builds the journeys people take, photographs each screen (including multi-step forms, overlays, and signed-in paths when you ask), lays visits on the path when Analytics is connected, scores how easy each path looks structurally, and lets you save a PDF or send the board to Figma. With Designer Preflight installed, it also checks every screen before you share the app.
You need Node.js 18 or newer, and Google Chrome.
npm install
npm start- Choose folder, optionally set the app URL if it’s already running, and optionally add a login email/password so FlowMap can photograph the signed-in product.
- Click Map paths. FlowMap starts that app’s dev server if needed, walks the journeys, and captures screenshots.
- Switch Paths on the board to move between journeys. Zoom with the controls or the trackpad; click a screen to enlarge it.
- Save as PDF prints the board. Export to Figma places one frame per step (see below). Open site jumps to the running local app when FlowMap knows its URL.
If Chrome is installed somewhere else, start FlowMap with CHROME_PATH set to that app. To change the port, set FLOWMAP_PORT (default 3920).
- Keep FlowMap running.
- In Figma: Plugins → Development → Import plugin from manifest…
- Choose
figma-plugin/manifest.jsonin this project. - Run FlowMap Import. It places one frame per step, with the screenshot.
FlowMap does more than a flat route list:
- Journeys (Paths) — product flows assembled from the home screen and linked routes, not one endless crawl.
- Happy path, “When it goes wrong”, and Other screens — main steps, error/empty/validation states where they can be found, and screens nothing links to.
- Multi-step forms — wizards and staged signup/onboarding are captured step by step when the code exposes those stages.
- Overlays on the same URL — dialogs, sheets, and preview/order-style panels discovered from common UI patterns, photographed when FlowMap can open them.
- Signed-in journeys — optional credentials in the Choose folder dialog (or env vars below) so capture can log in and map the product behind auth.
- Ease of use — each journey gets a structural score (“Easy / OK / Hard to use”) based on path length, forms, and recovery — not a claim about how the product feels.
When the project has git history or a changelog, each journey can name the latest change. Connect Google to show how many visits reached each screen, filter by device (computers / phones / tablets) and traffic source (search, ads, social, email, and so on), and switch accounts when you need a different Analytics property.
The project needs a Google tag or Tag Manager snippet for the Connect Google control to appear. Mapping and screenshots work without it.
- Open the Google Auth clients page. If it says the auth platform is not configured, click Get started.
- Enable the Google Analytics Data API and the Google Analytics Admin API.
- Create a client and choose Desktop app. Download the JSON. Allow this redirect:
http://127.0.0.1:3920/api/google/callback - On Audience, add the Google account that can see Analytics as a test user.
- In FlowMap, click Connect Google and choose that JSON. It is saved on this computer in
~/.flowmap/, not in this repo. If several sites are available, use Choose site (the status line can prompt you).
While the Google app stays in Testing, connect again after 7 days.
You can set FLOWMAP_GOOGLE_CLIENT_ID and FLOWMAP_GOOGLE_CLIENT_SECRET instead of choosing the file. Do not commit either value.
If the GitHub CLI is installed and signed in, a production deploy can move the date of a change. Without it, FlowMap uses the changelog or the commit day.
FlowMap works with Designer Preflight, a free pre-launch check for apps built with AI help. It looks for leaked keys, open databases, accessibility problems, iPhone and Android issues, and leftovers from earlier versions, and explains each one in plain language.
- Install Designer Preflight (see its README). FlowMap finds it automatically (
PREFLIGHT_DIR/PREFLIGHT_BINif it’s somewhere unusual). - Map a project, then click Check. Nothing in the project changes.
- Problems appear as badges on each screen. Click one to see what is wrong, why it matters, and how to fix it.
- Choose Fix this or It’s fine as it is on each problem.
- Click Take “before” pictures, then Fix what I approved. An AI agent (Claude Code, Cursor, or Codex — whichever is installed) fixes only what you approved, on a separate
preflight/branch. - Click Compare with before to see exactly what changed on every screen, at phone, tablet, and desktop sizes.
Ask for a review lets the agent read the code and add anything the automatic checks missed. It doesn’t change project files on purpose, and FlowMap warns you if anything outside .preflight/ changed.
For the Cursor agent, FlowMap uses the cursor-agent command if it is installed. To use the Cursor SDK instead, run npm install @cursor/sdk here and set CURSOR_API_KEY (optional FLOWMAP_CURSOR_MODEL).
FlowMap also works the other way round: Designer Preflight can ask FlowMap for the screen list (preflight scan --routes-from flowmap) via the CLI below.
npx flowmap map <folder> [--json]
npx flowmap capture <folder> [--url http://localhost:3000] [--viewport iphone|android|tablet|desktop] [--out <folder>] [--json]- map — lists screens, journeys, “When it goes wrong” states, and orphan screens (JSON for tools).
- capture — starts the app (or uses
--url), screenshots every screen, writes PNGs under<folder>/.flowmap/shots/by default.
Copy the names you need into a local .env or your shell. Never commit real secrets.
| Variable | Purpose |
|---|---|
FLOWMAP_PORT |
Server port (default 3920) |
CHROME_PATH |
Path to Chrome if it isn’t in the usual place |
FLOWMAP_LOGIN_EMAIL / FLOWMAP_LOGIN_PASSWORD |
Default signed-in capture (UI overrides these) |
FLOWMAP_GOOGLE_CLIENT_ID / FLOWMAP_GOOGLE_CLIENT_SECRET |
Analytics OAuth without picking a JSON file |
PREFLIGHT_DIR / PREFLIGHT_BIN |
Where Designer Preflight lives |
CURSOR_API_KEY / FLOWMAP_CURSOR_MODEL |
Cursor SDK agent (optional) |
Project-specific login fallbacks also exist (FLOWMAP_FAMILYTREE_*, FLOWMAP_PLANE_*, FLOWMAP_GHOST_*) for apps you map often.
