WebDNA auto-generates a structured, machine-readable blueprint of your site at build time. Zero config. Always in sync. Every route, component, design token, and API endpoint - mapped for AI.
AI agents have to figure out your entire project from scratch every time. Raw HTML tells them almost nothing useful.
Raw HTML with navbars, JS bundles, and ads. No brand context. No component awareness. No API understanding. AI guesses everything.
Structured JSON with every route, component, design token, and API shape. Colors, typography, tone of voice. Complete context in one file.
Three steps. Under a minute. Works with Next.js 13+ including Turbopack.
npm install next-webdna
// next.config.js const { withWebDNA } = require('next-webdna'); module.exports = withWebDNA({ // your existing Next.js config });
For ES modules or TypeScript:
import { withWebDNA } from 'next-webdna'; export default withWebDNA({ /* config */ });
npm run build
Your manifest is at /.well-known/webdna.json
Copy this prompt into Claude Code, Cursor, Windsurf, ChatGPT, Copilot, or any AI coding assistant to set up WebDNA automatically.
A single JSON file with everything an AI agent needs to understand your site.
{ "meta": { "name": "My Portfolio", "description": "Personal portfolio and blog", "version": "1.0.0", "generatedAt": "2026-04-01T12:00:00Z", "tier": "auto", "generator": "next-webdna" }, "brand": { "colors": { "primary": "#0F172A", "accent": "#6366F1" }, "typography": { "heading": "Cal Sans", "body": "Inter" }, "tone": "Professional, minimal, direct" }, "routes": { "/": { "type": "static", "description": "Homepage" }, "/blog/[slug]": { "type": "dynamic", "dataSource": "/api/posts" }, "/dashboard": { "type": "private", "requiresAuth": true } }, "components": { "Navbar": "Top navigation with logo and page links", "HeroSection": "Full-width hero with headline and CTA", "BlogCard": "Card showing title, date, and excerpt" }, "api": { "/api/posts": { "method": "GET", "description": "Returns all published blog posts" } } }
WebDNA reads your project at build time and extracts everything an AI needs.
Scans app/ and pages/ directories. Detects static, dynamic, and private routes. Extracts descriptions from metadata exports.
Reads Tailwind config for colors and fonts. Falls back to CSS custom properties in globals.css. Supports tone of voice config.
Scans component directories for React components. Extracts names and descriptions from JSDoc comments above exports.
Detects route handlers in app/api/ and pages/api/. Identifies HTTP methods and extracts descriptions from comments.
Reads package.json for name, description, and version. Stamps the manifest with generation time and tier info.
Pulls colors, typography, and spacing from your Tailwind config and CSS variables into structured brand data.
Zero config by default. Granular control when you need it.
Generated automatically on every build. Full read access to all public content. No configuration needed. Perfect for portfolios, blogs, landing pages.
Developer-filtered access via webdna.config.js. Exclude pages, mark private routes, add auth scopes. AI agents check Custom first, fall back to Auto.
Generate, validate, and inspect your manifest from the terminal.
npx webdna generate
Generate the WebDNA manifest for this project
npx webdna lint
Validate the manifest and check for issues
npx webdna inspect
Pretty-print the current manifest to stdout
Optional. Only needed when you want to exclude pages or mark private routes.
// webdna.config.js module.exports = { name: "My Website", description: "A brief description of my site", tone: "Professional, minimal, direct", // Pages to exclude from the manifest exclude: ['/pricing', '/internal'], // Pages that require authentication privateRoutes: ['/dashboard', '/settings'], // Custom component descriptions components: { HeroSection: "Full-width hero with animated headline and CTA", BlogCard: "Card showing post title, date, tag, and excerpt" } };
Exclude specific content from the manifest using a data attribute:
<p data-webdna="exclude"> This paragraph is invisible to any AI reading WebDNA. </p>
Running into problems? Here are the most common issues and how to fix them.
This happens on Next.js 15+ or 16 with Turbopack enabled. The withWebDNA wrapper injects a Webpack plugin, but Turbopack doesn't use the Webpack plugin lifecycle.
// package.json - update your build script "build": "npx webdna generate && next build"
WebDNA scans app/ and pages/ directories relative to your project root. If your source lives in src/, it checks src/app/ and src/pages/ automatically.
WebDNA looks for a tailwind.config.js/ts file and CSS variables in globals.css. If you use a different setup, colors won't be extracted automatically.
WebDNA extracts descriptions from JSDoc comments above component exports. Without them, it falls back to a generic label.
/** Top navigation bar with logo and page links */ export default function Navbar() { ... }
If you mark a route as private in webdna.config.js, the linter expects you to declare which OAuth scopes are required. This is intentional - it's a safety check.
TypeScript configs work fine. Make sure you're using the ES module import syntax:
import { withWebDNA } from 'next-webdna'; import type { NextConfig } from 'next'; const config: NextConfig = { /* your config */ }; export default withWebDNA(config);
How WebDNA compares to other approaches for giving AI context about websites.
| Feature | sitemap.xml | llms.txt | MCP | WebDNA |
|---|---|---|---|---|
| Zero config | Partial | No | No | Yes |
| Component info | - | - | Partial | Yes |
| Brand / design tokens | - | - | - | Yes |
| Dynamic content schema | - | - | Yes | Yes |
| API examples | - | - | Partial | Yes |
| Auth / private routes | - | - | Yes | Yes |
| Element-level exclusion | - | - | - | Yes |
| Validator / linter | - | - | - | Yes |
| Always in sync | Yes | No | Partial | Yes |
WebDNA is read-only by design. This is a core principle, not a limitation.
The manifest is a plain JSON file. It cannot execute code, run scripts, or modify anything.
Private routes declare auth requirements but never store tokens, passwords, or API keys in the file.
All private and dynamic access requires explicit user authorization via OAuth 2.0 flows.
No AI agent can ever write to or modify WebDNA. The manifest is generated from source code only.
Where WebDNA is headed.