WebDNA

Zero-config AI context standard for Next.js.

I built WebDNA because every time an AI agent touches a website, it has to figure out the entire project from scratch - squinting at raw HTML, guessing brand colors, and completely missing component structure. That's a terrible developer experience.

WebDNA auto-generates a structured, machine-readable blueprint of your website at build time. It gives AI agents, coding tools, and LLMs complete, structured, consent-based read access to your site's architecture, brand, routes, components, and API structure - without any manual setup.

Think of it as the brand guidelines document for AI - auto-written by your framework on every single build.

/.well-known/webdna.json

About

I'm Om Rajguru. I designed and built WebDNA because I believe AI tools deserve structured context about the websites they work with, and developers shouldn't have to write that context by hand.

• Website: omrajguru.com
• GitHub: @omrajguru05
• X: @omrajguru_
• Docs: webdna.omraj.guru

WebDNA is an original concept and specification by Om Rajguru (April 2026). The NPM package is publicly available. The source code is proprietary.

Why I Built This

| What AI Gets Today | What AI Gets With WebDNA | |---|---| | Raw HTML with navbars, ads, JS bundles | Structured JSON with every route, component, and design token | | No brand context | Colors, typography, tone of voice | | No component awareness | Full component hierarchy with descriptions | | No API understanding | Endpoint shapes with example requests/responses |

Existing solutions like llms.txt, sitemap.xml, and OpenAPI specs each solve a piece of the puzzle, but none of them give an AI agent a complete briefing about a website. WebDNA does, and it requires zero configuration.

Quick Start

1. Install

npm install next-webdna

2. Add to Your Next.js Config

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

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

That's it. On your next build, WebDNA generates public/.well-known/webdna.json automatically.

3. Verify

npx webdna inspect

What Gets Generated

{
  "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"]
    }
  },
  "components": {
    "Navbar": {
      "description": "Top navigation bar 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", "ctaText"],
      "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" }
    }
  }
}

Custom Configuration

For granular control over what AI can access, create a webdna.config.js:

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

  // Routes to exclude from the manifest (glob patterns supported)
  exclude: ['/pricing', '/internal/*'],

  // Components to exclude by name (glob patterns supported)
  excludeComponents: ['InternalNav', 'Debug*'],

  // API endpoints to exclude (glob patterns supported)
  excludeApi: ['/api/internal/*', '/api/debug'],

  // Brand tokens to exclude
  excludeBrand: ['debug-*', 'internal-red'],

  // Routes that require authentication
  privateRoutes: ['/dashboard', '/settings'],

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

Or pass config inline:

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

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

All exclusion fields support glob patterns. * matches any sequence of characters.

Element-Level Exclusion

I designed WebDNA to support excluding specific content from the manifest using the data-webdna attribute directly in your JSX:

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

WebDNA scans your source files at build time for data-webdna="exclude" attributes. Any component with this attribute on its root element is automatically excluded from the custom manifest. No config needed.

This works alongside the config-based exclusions. Both sources are combined when generating webdna-custom.json.

How the Two-Tier System Handles Exclusions

When any exclusions are present (via config or data-webdna attribute):

1. webdna.json is always generated with the full, unfiltered manifest
2. webdna-custom.json is generated with all exclusions applied
3. Dangling references are automatically cleaned up (if you exclude a component, routes that reference it will have that reference removed)

AI agents check for Custom first, fall back to Auto. This gives you complete control over what AI sees.

CLI

# Generate the manifest
npx webdna generate

# Validate the manifest
npx webdna lint

# Pretty-print the manifest
npx webdna inspect

Lint Checks

The linter catches common issues before they reach production:

• Private routes with no auth scopes = Error
• Dynamic routes with no schema = Warning
• Components with no 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 = Warning

Two-Tier System

| Tier | File | When Generated | |---|---|---| | Auto | /.well-known/webdna.json | Always (full manifest, zero config) | | Custom | /.well-known/webdna-custom.json | When any exclusions exist (config or data-webdna attributes) |

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

How It Works

1. Build time: WebDNA scans your Next.js project's route tree, Tailwind config, component directories, and API routes
2. Extraction: Design tokens, route metadata, component names, and API shapes are collected
3. Generation: A structured JSON manifest is written to public/.well-known/webdna.json
4. Serving: Next.js serves the file as a static asset at /.well-known/webdna.json

WebDNA is read-only by design. No AI agent can ever write to or modify the manifest. This is a core principle, not a limitation.

What WebDNA Scans

| Source | What It Extracts | |---|---| | app/ or pages/ directory | Routes, page types, dynamic params | | tailwind.config.js | Colors, fonts, design tokens | | CSS variables (globals.css) | Custom properties for colors and fonts | | components/ directory | Component names and JSDoc descriptions | | app/api/ or pages/api/ | API endpoints, methods, descriptions | | package.json | Project name, description, version | | Next.js metadata exports | Page descriptions |

How AI Agents Access WebDNA

WebDNA is accessible 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, serves with CORS headers) | | /webdna.json | Rewrite alias for /.well-known/webdna.json |

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 and marked with @generated by next-webdna. It will not overwrite any file you created yourself at that path.

Security

I take security seriously in the design of WebDNA:

• 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 are ever stored in the file
• Write access is permanently disabled - no AI agent can modify WebDNA
• The manifest is generated from your source code, never from external input

Roadmap

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

AI Setup Prompts

Quick Setup (No Exclusions)

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

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 over what AI can see. The AI will walk you through every exclusion decision and save a summary for reference:

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.

Contact

Have questions, feedback, or running into issues? Reach out to me:

• Website: omrajguru.com/contact
• X: @omrajguru_

License

All rights reserved. The NPM package (next-webdna) is freely available for use in your projects. The source code is proprietary and not open source.

WebDNA is an original concept and specification by Om Rajguru, April 2026.