Add Runtime Context to Your AI Coding Workflow (Next.js + Frontman)

This is a practical walkthrough. We'll take a Next.js app with a layout bug, install Frontman, and fix the bug by clicking the broken element in the browser instead of describing it to an AI that can't see it.

By the end you'll know whether runtime-aware AI coding actually saves time or is just a debugger with extra steps. (Spoiler: it's both.)

Prerequisites

• A Next.js 14 or 15 project (or npx create-next-app@latest to create one)
• An API key from Claude, OpenAI, or OpenRouter
• 5 minutes

Step 1: Install Frontman

npx @frontman-ai/nextjs install

That's it for setup. The installer handles your config automatically. Start your dev server:

npm run dev

When you open your app in the browser, you'll see a small Frontman toolbar. Click it and enter your AI key (Claude, OpenAI, or OpenRouter). The key is stored locally in your browser — it's never sent anywhere except directly to your AI provider.

Step 2: The Bug

Let's create a realistic layout bug. Here's a card grid component with a subtle problem:

// src/components/CardGrid.tsx
export function CardGrid({ items }: { items: Item[] }) {
  return (
    <div className="grid grid-cols-3 gap-6 p-8">
      {items.map((item) => (
        <div key={item.id} className="rounded-lg bg-white p-6 shadow-sm">
          <h3 className="text-lg font-semibold">{item.title}</h3>
          {item.featured && (
            <span className="mt-2 inline-block rounded-full bg-blue-100 px-3 py-1 text-sm text-blue-800">
              Featured
            </span>
          )}
          <p className="mt-4 text-gray-600">{item.description}</p>
        </div>
      ))}
    </div>
  );
}

This looks fine in your source code. But when 2 of 6 items are featured, the cards with the badge are taller than the ones without, breaking the grid alignment. The bottom row doesn't align. The gap-6 interacts with the conditional badge in a way that isn't obvious from reading the JSX.

What Cursor/Copilot Would Do

You'd describe the bug: "The cards in CardGrid aren't aligning properly — some are taller than others."

The AI would read the source, see grid-cols-3 gap-6, and probably suggest one of:

• Adding h-full to the cards (might work, might cause other issues)
• Adding min-h-[200px] (arbitrary, fragile)
• Restructuring the component entirely (overkill)

It can't see that the actual problem is the conditional featured badge pushing content down, and that the real fix is just adding flex flex-col to the card and mt-auto to the description paragraph. The AI is guessing because it doesn't see the rendered layout.

Step 3: Fix It With Runtime Context

With Frontman running, open the page in your browser. You can see the misaligned cards.

Click the misaligned card. Frontman highlights it and shows you:

• The component: CardGrid at src/components/CardGrid.tsx:5
• The element: <div class="rounded-lg bg-white p-6 shadow-sm">
• Computed styles: the actual padding, dimensions, and flex/grid properties as the browser computed them
• Parent layout: the grid container with its resolved gap, column widths, and row heights
• Children: what's actually inside this card (including the conditional badge)

Now describe the fix:

"Make all cards the same height and align the description text at the bottom, regardless of whether the Featured badge is present."

Frontman sends the AI:

1. Your description
2. The source code of CardGrid.tsx
3. The computed layout: actual grid dimensions, card heights, which cards have the badge
4. The component tree context

The AI generates a targeted edit — adding flex flex-col to the card wrapper and mt-auto to the description paragraph. It knows this is the right fix because it can see the actual height difference between cards with and without the badge.

The edit is applied to your source file. Hot reload shows the result immediately. Cards align.

Step 4: What Just Happened Under the Hood

Here's the flow:

1. You clicked an element in the browser
2. Frontman's client-side code identified the React component
   and resolved it to a source file:line via sourcemaps
3. The click target + component info were sent to the
   Frontman middleware running inside the Next.js dev server
4. The middleware gathered:
   - Source code of the component
   - Computed styles from the browser
   - Component tree (parent/child relationships)
   - Server-side context (routes, module graph)
5. All of this was packaged as MCP tool responses
   and sent to the AI alongside your description
6. The AI generated a source code edit
7. The edit was written to disk
8. Next.js HMR hot-reloaded the change
9. The browser updated — you see the fix immediately

The key insight: the AI didn't guess what the layout looks like. It knew — because Frontman gave it the computed layout data from the browser. The fix was targeted instead of speculative.

Step 5: Beyond CSS — What Else You Can Do

The card grid example is simple. Here are more realistic scenarios where runtime context helps:

Debugging a 404

Your page returns a 404 but the file exists. Instead of manually checking the route table, middleware chain, and rewrites:

"Why is /api/users/me returning 404?"

Frontman gives the AI access to the registered route table and middleware state. The AI can see that a middleware redirect is firing before the route matches, or that the file-based route doesn't resolve to what you expect.

Fixing a Hydration Mismatch

A component renders differently on server and client. Server logs show a hydration warning but you can't tell which component caused it:

Click the component in the browser. Frontman shows the server-rendered HTML vs. the client-rendered DOM, plus the component's source location. The AI can see the mismatch directly.

Understanding an Unfamiliar Codebase

You joined a project and need to understand what renders the dashboard sidebar:

Click the sidebar. Frontman tells you: DashboardLayout > Sidebar at src/layouts/DashboardLayout.tsx:23. You have your answer in 2 seconds instead of grepping through the component tree.

Step 6: Try It Yourself

# Next.js
npx @frontman-ai/nextjs install

# Or Astro
astro add @frontman-ai/astro

# Or Vite (React, Vue, Svelte)
npx @frontman-ai/vite install

Full setup instructions and documentation: frontman.sh

frontman-ai / frontman

The AI agent that lives in your framework/browser

Ship frontend changes from your browser — no code editor needed

---

Frontman is an open-source AI coding agent that lives in your browser. It hooks into your dev server as middleware and sees the live DOM, component tree, CSS styles, routes, and server logs. Click any element in your running app, describe what you want changed in plain English, and Frontman edits the actual source files with instant hot reload. It supports Next.js, Astro, and Vite (React, Vue, Svelte). Free and open-source — Apache 2.0 (client libraries) / AGPL-3.0 (server). Bring your own API keys (Claude, ChatGPT, or OpenRouter).

Who Is This For?

Frontend developers who want richer context than terminal-based AI tools provide. Frontman reads the rendered page, not just the source files, so it knows what your CSS actually computes to and which component renders which DOM node.

Designers and product managers who want to change copy, adjust…

View on GitHub

When NOT to Use This

Runtime-aware AI coding is not a silver bullet. Don't use it for:

• Complex state logic — the visual output doesn't tell you if your reducer logic is correct
• Performance optimization — Frontman sees the DOM, not your render cycles or bundle size
• As a substitute for understanding your code — if you can't explain the AI's diff to a colleague, don't commit it

The runtime context gap is real, and closing it saves time on a specific class of problems (visual bugs, layout issues, routing confusion, server-side debugging). But it doesn't replace engineering judgment. It just means the AI has to guess less.

---

Frontman is open source on GitHub. This tutorial uses Next.js, but the workflow is identical for Astro and Vite projects — just swap the package name.