Ward

Warning

Ward is in early development (alpha). Core features are still being built. Expect bugs, missing functionality, and breaking changes. Feedback welcome!

Next.js-native observability. See everything happening in your app - from Server Components to client hydration - with a local dashboard and AI-powered debugging via MCP.

Packages

Package	Description
@useward/instrumentation	Next.js instrumentation SDK
@useward/devtools	Development server and local dashboard
@useward/mcp	MCP server for AI coding assistants

Quick Start

1. Install

npm install @useward/instrumentation

2. Add instrumentation

// instrumentation.ts
import { register as registerWard } from '@useward/instrumentation';

export async function register() {
  if (process.env.NODE_ENV === 'development') {
    await registerWard();
  }
}

// instrumentation-client.ts
import { register as registerWard } from '@useward/instrumentation/client';

export function register() {
  if (process.env.NODE_ENV === 'development') {
    registerWard();
  }
}

3. Add middleware (optional)

For trace context propagation across requests:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { wardMiddleware } from '@useward/instrumentation/middleware';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  return wardMiddleware(request, response);
}

4. Run the devtools

npx @useward/devtools

Open http://localhost:19393 to see your traces.

MCP Integration

Ward includes an MCP server that exposes your app's telemetry to AI coding assistants:

{
  "mcpServers": {
    "ward": {
      "command": "npx",
      "args": ["@useward/mcp"]
    }
  }
}

Works with Claude Code, Cursor, and other MCP-compatible tools.

Features

Server-Side Tracing

• RSC (React Server Components) render timing
• Server Actions execution
• API route performance
• Database query detection
• Fetch request waterfalls

Client-Side Tracing

• Hydration timing
• Navigation events
• Web Vitals (FCP, LCP)
• Client-side fetches
• Long task detection

Issue Detection

• N+1 query patterns
• Waterfall request chains
• Missing cache configurations
• RSC sequential fetches

Requirements

• Next.js 15+
• React 18+
• Node.js 22+

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run development mode
pnpm dev

License

License