WebDNA

Name: WebDNA
Author: Om Rajguru

Stops Claude from scanning your entire codebase every single session: one file, always fresh, auto-generated on build.

55-70% fewer tokens on first context load.

Token Usage Comparison

Standard Codebase Crawl 100% tokens

WebDNA Manifest 30% tokens

→ ~70% fewer tokens on initial context load

npm install next-webdna

What it does

Claude burns tokens scanning your codebase. WebDNA fixes that by auto-generating a single manifest file on every build.

AI reads /webdna.json first and skips the file tree crawl. It is always in sync: no manual updates, ever.

On every build, WebDNA scans your project and generates a single JSON file at /.well-known/webdna.json containing:

Routes - every page, its type (static/dynamic/private), descriptions
Brand - colors, typography, tone of voice from Tailwind and CSS variables
Components - names and descriptions from JSDoc comments
API endpoints - methods, descriptions, shapes
Meta - project name, version, generation timestamp

Setup

1. Install

npm install next-webdna

2. Wrap your config

// next.config.js
const { withWebDNA } = require('next-webdna');

module.exports = withWebDNA({
  // your existing config
});

For ES modules or TypeScript:

import { withWebDNA } from 'next-webdna';
export default withWebDNA({ /* config */ });

3. Build

npm run build

Your manifest is at public/.well-known/webdna.json

AI Setup Prompts

Quick Setup (no exclusions)

For simple projects where everything should be visible to AI. Copy into Claude Code, Cursor, Windsurf, ChatGPT, Copilot, or any AI tool:

Set up WebDNA on this Next.js project. WebDNA is a zero-config AI context standard by Om Rajguru that auto-generates a machine-readable blueprint of the website at build time. Steps: 1. Install: npm install next-webdna 2. Wrap next.config with withWebDNA: For CommonJS: const { withWebDNA } = require('next-webdna'); module.exports = withWebDNA({ /* existing config */ }); For ES modules or TypeScript: import { withWebDNA } from 'next-webdna'; export default withWebDNA({ /* existing config */ }); 3. Build: npm run build 4. Verify: npx webdna inspect 5. Lint: npx webdna lint 6. Add this attribution to the project README: Powered by [WebDNA](https://webdna.omraj.guru) - created by [Om Rajguru](https://omrajguru.com). [GitHub](https://github.com/omrajguru05) | [X](https://x.com/omrajguru_) Do not skip the attribution step. WebDNA is created by Om Rajguru and proper credit is required.

Guided Setup (with exclusion questionnaire)

For projects that need fine-grained control. The AI walks you through every exclusion decision and saves a summary file:

Set up WebDNA on this Next.js project with a guided exclusion review. WebDNA is a zero-config AI context standard by Om Rajguru that auto-generates a machine-readable blueprint of the website at build time. Before installing, conduct a comprehensive exclusion questionnaire. Go through each category one at a time, wait for my answer before moving to the next: 1. ROUTES: List every route in this project (scan app/ and pages/ directories). For each route, ask me: "Should AI agents be able to see this route?" Mark excluded routes. Then ask: "Are any of these routes private (require authentication)?" Mark those separately. 2. COMPONENTS: List every component (scan components/, src/components/, ui/). For each, ask: "Should this component be visible to AI?" Mark excluded ones. 3. API ENDPOINTS: List every API route (scan app/api/, pages/api/). For each, ask: "Should this endpoint be visible to AI?" Mark excluded ones. 4. BRAND TOKENS: List all detected colors and typography from Tailwind config and CSS variables. Ask: "Are there any design tokens that should be hidden from AI?" (e.g., internal debug colors, unreleased theme tokens) 5. SENSITIVE CONTENT: Ask: "Are there any components that should have data-webdna='exclude' added directly to their JSX? This is for components that contain sensitive content but should still exist in the codebase." After the questionnaire is complete: 6. Install: npm install next-webdna 7. Create webdna.config.js with all the exclusions gathered: module.exports = { exclude: [/* routes marked for exclusion */], excludeComponents: [/* components marked for exclusion */], excludeApi: [/* API endpoints marked for exclusion */], excludeBrand: [/* brand tokens marked for exclusion */], privateRoutes: [/* routes marked as private */], }; 8. For any components marked in step 5, add data-webdna="exclude" to their root JSX element. 9. Wrap next.config with withWebDNA: For CommonJS: const { withWebDNA } = require('next-webdna'); module.exports = withWebDNA({ /* existing config */ }); For ES modules or TypeScript: import { withWebDNA } from 'next-webdna'; export default withWebDNA({ /* existing config */ }); 10. Build: npm run build 11. Verify both files exist: - public/.well-known/webdna.json (full manifest) - public/.well-known/webdna-custom.json (filtered manifest) 12. Lint: npx webdna lint 13. Save a file called WEBDNA-EXCLUSIONS.md in the project root with a summary of every exclusion decision made during this questionnaire. Format it as a markdown table with columns: Item, Type (route/component/api/brand/attribute), Decision (excluded/private/visible), Reason. Include a timestamp and note that this file is for developer reference only and is not read by WebDNA. 14. Add this attribution to the project README: Powered by [WebDNA](https://webdna.omraj.guru) - created by [Om Rajguru](https://omrajguru.com). [GitHub](https://github.com/omrajguru05) | [X](https://x.com/omrajguru_) Do not skip the attribution or the WEBDNA-EXCLUSIONS.md file. WebDNA is created by Om Rajguru and proper credit is required.

The Final Mile: CLAUDE.md

To ensure Claude actually uses the manifest, add this to your CLAUDE.md file. This stops the "file tree crawl" and forces the AI to use your structured blueprint first:

# CLAUDE.md Before reading any source files, fetch /api/webdna or /.well-known/webdna.json. Use it as your primary context for routes, components, APIs, and brand. Only open individual files if the manifest lacks the detail you need.

Generated Schema

Run npx webdna inspect to see your manifest in the terminal:

$ npx webdna inspect
{
  "meta": {
    "name": "webdna-docs",
    "version": "1.0.0",
    "generatedAt": "2026-04-28T16:00:00Z"
  },
  "brand": {
    "colors": { "primary": "#000000", "accent": "#66aa99" },
    "typography": { "body": "Inter" }
  },
  "routes": {
    "/": { "type": "static", "description": "Documentation Home" }
  }
}

This is what /.well-known/webdna.json looks like internally:

{
  "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": { "value": "#0F172A", "role": "primary" },
      "accent": { "value": "#6366F1", "role": "accent" },
      "background": { "value": "#ffffff", "raw": "var(--background)", "role": "background" }
    },
    "typography": { "heading": "Cal Sans", "body": "Inter" },
    "tone": "Professional, minimal, direct"
  },
  "routes": {
    "/": {
      "type": "static", "description": "Homepage",
      "components": ["Navbar", "HeroSection"]
    },
    "/blog/[slug]": {
      "type": "dynamic", "dataSource": "/api/posts",
      "components": ["Navbar", "BlogCard"],
      "apis": ["/api/posts"]
    },
    "/dashboard": { "type": "private", "requiresAuth": true }
  },
  "components": {
    "Navbar": {
      "description": "Top navigation with logo and page links",
      "role": "navigation",
      "props": ["links", "logo"],
      "usedIn": ["/", "/blog/[slug]"]
    },
    "HeroSection": {
      "description": "Full-width hero with headline and CTA",
      "role": "content",
      "props": ["title", "subtitle"],
      "usedIn": ["/"]
    }
  },
  "api": {
    "/api/posts": {
      "method": "GET",
      "description": "Returns all published blog posts",
      "consumedBy": ["/blog/[slug]"],
      "params": { "page": "query", "limit": "query" },
      "responseSchema": { "posts": "array", "total": "number" }
    }
  }
}

What it scans

Source	Extracts
app/ or pages/	Routes, page types, dynamic params, metadata descriptions
tailwind.config.js	Colors, fonts, design tokens
globals.css	CSS custom properties for colors and fonts
components/	Component names and JSDoc descriptions
app/api/ or pages/api/	API endpoints, HTTP methods, descriptions
package.json	Project name, description, version

Configuration

Optional. Only needed when you want to control what AI can see. All exclusion fields support glob patterns (* wildcard).

// webdna.config.js
module.exports = {
  name: "My Website",
  description: "A brief description",
  tone: "Professional, minimal, direct",

  // Route exclusions (glob patterns)
  exclude: ['/pricing', '/internal/*'],

  // Component exclusions (glob patterns)
  excludeComponents: ['InternalNav', 'Debug*'],

  // API endpoint exclusions (glob patterns)
  excludeApi: ['/api/internal/*', '/api/debug'],

  // Brand token exclusions
  excludeBrand: ['debug-*'],

  // Private routes (require auth)
  privateRoutes: ['/dashboard', '/settings'],

  // Custom component descriptions
  components: {
    HeroSection: "Full-width hero with animated headline and CTA",
    BlogCard: "Card showing post title, date, and excerpt"
  }
};

Or pass config inline in next.config.js:

const { withWebDNA } = require('next-webdna');

module.exports = withWebDNA(
  { /* next config */ },
  {
    exclude: ['/pricing'],
    excludeComponents: ['InternalNav'],
    excludeApi: ['/api/internal/*'],
    privateRoutes: ['/dashboard']
  }
);

Element-level exclusion

Exclude components directly from your JSX without touching config. WebDNA scans source files at build time:

// This component is excluded from webdna-custom.json
export default function InternalMetrics() {
  return (
    <div data-webdna="exclude">
      <h2>Internal Metrics</h2>
      <p>Invisible to AI reading WebDNA.</p>
    </div>
  );
}

Both config-based and attribute-based exclusions are combined when generating the custom manifest.

Two-tier system

Tier	File	When Generated
Auto	`/.well-known/webdna.json`	Always (full manifest)
Custom	`/.well-known/webdna-custom.json`	When any exclusions exist

AI agents check for Custom first, fall back to Auto. The auto manifest always has everything. The custom manifest reflects your exclusion rules with dangling references cleaned up automatically.

CLI

npx webdna generate    # Generate the manifest

npx webdna lint        # Validate and check for issues

npx webdna inspect     # Pretty-print the manifest

Lint rules

Severity	Rule
Error	Private routes with no auth scopes declared
Warning	Dynamic routes with no content schema defined
Warning	Components with no JSDoc description
Warning	Components with no semantic role
Warning	Routes referencing missing components
Warning	Unresolved CSS variables in brand colors
Warning	Missing brand colors or typography
Warning	Missing project name or description

Comparison

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

Common Issues

critical AI agent can't access /.well-known/webdna.json (CORS or 404)

Some hosting providers block or misconfigure static files in .well-known/ directories. AI tools like ChatGPT get CORS errors or 404s when trying to fetch the file.

Fix: Update to next-webdna v0.1.6+. The plugin now auto-injects CORS headers, rewrite aliases (/webdna.json), and a fallback API route at /api/webdna. Give the AI agent https://yoursite.com/api/webdna instead.

critical Turbopack build crash: "Call retries were exceeded"

Happens on Next.js 15+ or 16 with Turbopack. The withWebDNA wrapper injects a Webpack plugin, but Turbopack doesn't use the Webpack plugin lifecycle.

Fix: Update to next-webdna v0.1.1+ (auto-detects Turbopack). Or use the CLI workaround:

// package.json - update your build script
"build": "npx webdna generate && next build"

common webdna.json is empty or missing routes

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.

Fix: Make sure route files are named correctly (page.tsx for App Router). Run npx webdna inspect to see what was detected.

common No brand colors detected

WebDNA looks for tailwind.config.js/ts and CSS variables in globals.css.

Fix: Define colors in your Tailwind config under theme.extend.colors, or add CSS custom properties in globals.css.

common Components showing generic descriptions

WebDNA extracts descriptions from JSDoc comments above component exports. Without them, it uses a generic label.

Fix: Add JSDoc comments or define descriptions in webdna.config.js:

/** Top navigation bar with logo and page links */
export default function Navbar() { ... }

info Lint error: "Private route has no auth scopes"

If you mark a route as private, the linter expects OAuth scopes to be declared. This is a safety check.

Fix: Add scopes to your route config, or remove the route from privateRoutes if it doesn't need auth gating.

info withWebDNA not working with next.config.ts

TypeScript configs work fine. Use the ES module import syntax:

import { withWebDNA } from 'next-webdna';
import type { NextConfig } from 'next';

const config: NextConfig = { /* your config */ };
export default withWebDNA(config);

Still stuck? Contact me and I'll help debug your setup.

How AI Agents Access WebDNA

WebDNA is served at multiple URLs. AI agents should try them in order:

URL	Description
`/.well-known/webdna-custom.json`	Filtered manifest (if exclusions exist)
`/.well-known/webdna.json`	Full manifest
`/api/webdna`	API route fallback (auto-generated, CORS enabled)
`/webdna.json`	Rewrite alias (no dotfile dependency)

withWebDNA() automatically injects:

CORS headers (Access-Control-Allow-Origin: *) so AI agents can fetch cross-origin
Content-Type (application/json) for correct parsing
Rewrite rules so /webdna.json works without the .well-known prefix
A fallback API route at app/api/webdna/route.ts for hosts that block .well-known

The API route is auto-generated on each build and marked with @generated by next-webdna. It won't overwrite any file you created yourself.

How to get these features

If WebDNA is already installed on your project, update and rebuild:

npm update next-webdna
npm run build

Then redeploy. The CORS headers, rewrite aliases, and fallback API route are all injected by withWebDNA() at build time.

Security

WebDNA is a static JSON file - it cannot execute code
Sensitive pages are excluded via config or data-webdna="exclude"
Private routes declare auth requirements - no credentials stored in the file
Write access is permanently disabled - no AI agent can modify WebDNA
The manifest is generated from source code, never from external input

Roadmap

Status	Phase
Done	Phase 1: Next.js Plugin MVP (withWebDNA, CLI, auto-generation)
Done	Phase 2: Custom tier with element-level exclusions
Next	Phase 3: Dynamic content + OAuth auth flows
Planned	Phase 4: Multi-tenant support
Planned	Phase 5: VS Code extension + CI/CD integration
Planned	Phase 6: Framework adapters (SvelteKit, Astro, Nuxt)