🎨 **AI-Powered React Component Generation**
🎨 AI-Powered React Component Generation
Vibe Overlord is a TypeScript library that uses AI to generate React components from natural language prompts. It leverages LLMs to create production-ready components with automatic discovery of your existing components and utilities.
- Features
- Installation
- Quick Start
- Advanced Features
- Configuration
- API Reference
- Examples
- Security
- Troubleshooting
mdx-bundler for immediate rendering``bash`
npm install vibe-overlord mdx-bundler ai zod @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
Required Dependencies:
- mdx-bundler - Core MDX compilation engineai
- - AI SDK framework for provider integration zod
- - Runtime schema validation@ai-sdk/openai
- - OpenAI provider (GPT-4, etc.)@ai-sdk/anthropic
- - Anthropic provider (Claude)@ai-sdk/google
- - Google provider (Gemini)
Create a .env.local file with at least one API key:
`bashOpenAI (default)
OPENAI_API_KEY=your_openai_key_here
$3
`typescript
import { generateComponent } from 'vibe-overlord';
import path from 'path'; const { code, frontmatter } = await generateComponent({
prompt: "Create a blue button with rounded corners",
projectPath: path.resolve(process.cwd())
});
`$3
API Route (
app/api/generate/route.ts):
`typescript
import { generateComponent } from 'vibe-overlord';
import { NextResponse } from 'next/server';
import path from 'path';export async function POST(request: Request) {
const { prompt } = await request.json();
const { code, frontmatter } = await generateComponent({
prompt,
projectPath: path.resolve(process.cwd()),
provider: { provider: 'openai' }
});
return NextResponse.json({ code, frontmatter });
}
`Client Component (
app/page.tsx):
`typescript
'use client';
import { useState } from 'react';
import { getMDXComponent } from 'vibe-overlord/client';export default function Home() {
const [code, setCode] = useState('');
const generate = async (prompt: string) => {
const response = await fetch('/api/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ prompt })
});
const { code } = await response.json();
setCode(code);
};
const Component = code ? getMDXComponent(code) : null;
return (
{Component && }
);
}
`Advanced Features
$3
Automatically discover and use your existing components and utilities.
1. Create Configuration (
vibe-overlord.config.ts):`typescript
import { VibeOverlordConfig } from 'vibe-overlord';const config: VibeOverlordConfig = {
componentGlobs: ['src/components/*/.{tsx,jsx}'],
utilityGlobs: ['src/utils/*/.{ts,tsx}'],
autoDetectAliases: true,
useTwoPhaseGeneration: true,
enableSelfHealing: true,
useAstValidation: true,
allowTypescript: true
};
export default config;
`2. Use in API Route:
`typescript
import { generateComponent, loadConfig, scanProject } from 'vibe-overlord';
import path from 'path';// Cache the catalog
let catalogCache = null;
let lastScan = 0;
const CACHE_TTL = 5 60 1000; // 5 minutes
export async function POST(request: Request) {
const { prompt } = await request.json();
const projectPath = path.resolve(process.cwd());
// Load config
const config = await loadConfig(projectPath);
// Scan project (with caching)
const now = Date.now();
if (!catalogCache || now - lastScan > CACHE_TTL) {
catalogCache = await scanProject(projectPath, config);
lastScan = now;
}
// Generate with auto-discovery
const { code, frontmatter, spec } = await generateComponent({
prompt,
projectPath,
config,
catalog: catalogCache
});
return NextResponse.json({ code, frontmatter, spec });
}
`What Gets Auto-Discovered:
Your components:
`typescript
// src/components/Button.tsx
/**
* @description A customizable button with variants
*/
export const Button = ({ variant, children }) => {
// AI will know about this and use it!
};
`Your utilities:
`typescript
// src/utils/api.ts
/**
* @description Fetch user data from API
*/
export async function fetchUsers() {
// AI will know about this and use it!
}
`$3
Generate components in two phases for better architecture.
Enable in config:
`typescript
{
useTwoPhaseGeneration: true
}
`Phase 1 - Planning: AI creates a component specification
Phase 2 - Implementation: AI generates code from the spec
View the spec:
`typescript
const { code, frontmatter, spec } = await generateComponent({
prompt: 'Create a data table with sorting',
projectPath,
config
});console.log(spec.name); // Component name
console.log(spec.state); // State management
console.log(spec.props); // Props definition
console.log(spec.interactions); // User interactions
`$3
Learn from built-in patterns for better results.
Built-in Templates:
- Form with validation
- Data table with sorting
- Modal dialog with accessibility
Add Custom Templates:
`typescript
// vibe-overlord.config.ts
{
templates: {
enabled: true,
customTemplatesDir: './src/templates'
}
}
`Create MDX templates:
`mdx
---
title: "My Custom Pattern"
description: "Description"
category: "ui"
tags: ["custom"]
pattern: "custom-pattern"
---import React from 'react';
export const MyPattern = () => {
// Your example implementation
};
`Configuration
$3
Create
vibe-overlord.config.ts in your project root:`typescript
import { VibeOverlordConfig } from 'vibe-overlord';const config: VibeOverlordConfig = {
// Scanning patterns
componentGlobs: [
'src/components/*/.{tsx,jsx}',
'app/components/*/.{tsx,jsx}'
],
utilityGlobs: [
'src/utils/*/.{ts,tsx}',
'lib/*/.{ts,tsx}'
],
excludeGlobs: [
'*/.test.{ts,tsx}',
'*/.spec.{ts,tsx}',
'/node_modules/'
],
// Aliases
autoDetectAliases: true, // Detect from tsconfig.json
aliases: {
'@': './src',
'@/components': './src/components'
},
// Context
maxContextItems: 10,
useEmbeddings: false, // Requires OpenAI key
// Generation
allowTypescript: true,
useTwoPhaseGeneration: true,
enableSelfHealing: true,
maxRetries: 1,
// Validation
useAstValidation: true,
allowedImports: [
'react',
'react-dom',
'next',
'lucide-react' // Add your libraries
],
// Templates
templates: {
enabled: true,
customTemplatesDir: './src/templates'
}
};
export default config;
`$3
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
componentGlobs | string[] | ['src/components/*/.{tsx,jsx}'] | Patterns to find components |
| utilityGlobs | string[] | ['src/utils/*/.{ts,tsx}'] | Patterns to find utilities |
| autoDetectAliases | boolean | true | Auto-detect from tsconfig.json |
| maxContextItems | number | 10 | Max items to inject into context |
| useTwoPhaseGeneration | boolean | false | Use plan → implement flow |
| enableSelfHealing | boolean | true | Auto-retry on errors |
| useAstValidation | boolean | true | Use AST-based validation |
| allowTypescript | boolean | false | Allow TypeScript output |API Reference
$3
Generates a React component from a text prompt.
Parameters:
`typescript
interface GenerateComponentOptions {
prompt: string; // Component description
projectPath: string; // Absolute path to project
provider?: { // AI provider config
provider: 'openai' | 'anthropic' | 'google';
model?: string;
};
config?: VibeOverlordConfig; // Optional config
catalog?: ScannedCatalog; // Optional pre-scanned catalog
}
`Returns:
`typescript
{
code: string; // Compiled MDX code
frontmatter: { // Component metadata
title?: string;
description?: string;
category?: string;
tags?: string[];
version?: string;
};
spec?: ComponentSpec; // Planning phase output (if two-phase enabled)
}
`$3
Scans project for components and utilities.
Returns:
`typescript
{
components: AvailableComponent[];
utilities: AvailableUtility[];
embeddings?: Map;
}
`$3
Loads configuration from
vibe-overlord.config.ts.$3
Creates a React component from compiled MDX code (client-side).
Examples
$3
`typescript
const { code } = await generateComponent({
prompt: 'Create a blue button with rounded corners',
projectPath: process.cwd()
});
`$3
`typescript
// Your Button component will be auto-discovered
const { code } = await generateComponent({
prompt: 'Create a pricing page using Button and Card components',
projectPath: process.cwd()
});
`$3
`typescript
// Your fetchUsers utility will be auto-discovered
const { code } = await generateComponent({
prompt: 'Create a user list that fetches users and displays them in cards',
projectPath: process.cwd()
});
`$3
`typescript
const { code, spec } = await generateComponent({
prompt: 'Create a data table with sorting, pagination, and row actions',
projectPath: process.cwd(),
config: {
useTwoPhaseGeneration: true,
enableSelfHealing: true
}
});// View the planning phase
console.log('Component spec:', spec);
`$3
`typescript
// OpenAI (default)
const { code } = await generateComponent({
prompt: 'Create a modal dialog',
projectPath: process.cwd(),
provider: { provider: 'openai' }
});// Anthropic Claude
const { code } = await generateComponent({
prompt: 'Create a modal dialog',
projectPath: process.cwd(),
provider: { provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' }
});
// Google Gemini
const { code } = await generateComponent({
prompt: 'Create a modal dialog',
projectPath: process.cwd(),
provider: { provider: 'google', model: 'gemini-2.5-pro-latest' }
});
`Security
$3
- Input Validation: All prompts validated with Zod schemas
- AST-Based Validation: Robust checks using Babel parser
- Import Allowlist: Only approved imports allowed
- Sanitization: Removes dangerous patterns
- Secure Logging: Redacts sensitive information
$3
Blocked Patterns:
-
eval(), Function() constructor
- Direct network calls (fetch, XMLHttpRequest)
- Process/global object access
- innerHTML, outerHTML assignments
- Node.js built-ins
- Cookie manipulationExample Usage with Security:
`typescript
import {
generateComponent,
RateLimiter,
validateEnvironment
} from 'vibe-overlord';// Rate limiting
const rateLimiter = new RateLimiter({
windowMs: 60 * 1000,
maxRequests: 10
});
// Environment validation
const envValidation = validateEnvironment();
if (!envValidation.isValid) {
console.error(envValidation.errors);
}
export async function POST(request: Request) {
const clientIP = request.headers.get('x-forwarded-for');
if (!rateLimiter.isAllowed(clientIP)) {
return new Response('Rate limit exceeded', { status: 429 });
}
// Generate component securely
const { code } = await generateComponent({
prompt: await request.text(),
projectPath: process.cwd()
});
return Response.json({ code });
}
`Troubleshooting
$3
"Cannot find module 'vibe-overlord'"
`bash
Install dependencies
npm install vibe-overlord mdx-bundler ai zod @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
`"Module not found: @babel/parser"
`bash
Dependencies are included, try:
npm install
npm run build
`$3
"No components discovered"
- Check
componentGlobs patterns in config
- Ensure components are exported
- Verify components are in the specified directories"Generated code has errors"
- Enable
allowTypescript: true if using TypeScript
- Check autoDetectAliases: true is set
- Verify imports in allowedImports list"Generation is slow"
- Reduce
maxContextItems in config
- Disable useTwoPhaseGeneration for simple components
- Implement catalog caching (see Advanced Features)"Component doesn't use my components"
- Ensure components have JSDoc descriptions
- Try mentioning them explicitly in prompt
- Check scanning patterns in config
$3
"Import validation failed"
`typescript
// Add to allowedImports in config
{
allowedImports: [
'react',
'react-dom',
'your-library-name' // Add your library
]
}
`"Security violation"
- Review the error message
- Check if using forbidden patterns
- Use provided utilities for network calls
Performance Optimization
$3
`typescript
let catalogCache = null;
let lastScan = 0;
const CACHE_TTL = 5 60 1000; // 5 minutesexport async function POST(request: Request) {
const now = Date.now();
if (!catalogCache || now - lastScan > CACHE_TTL) {
catalogCache = await scanProject(projectPath, config);
lastScan = now;
}
const { code } = await generateComponent({
prompt,
projectPath,
catalog: catalogCache // Use cached catalog
});
}
`$3
`typescript
{
maxContextItems: 10, // Don't inject too many items
useTwoPhaseGeneration: false, // Disable for simple components
useEmbeddings: false, // Unless needed for semantic search
templates: {
enabled: false // Disable if not using templates
}
}
`Supported AI Providers
| Provider | Models | Default Model |
|----------|--------|---------------|
| OpenAI | gpt-4o, gpt-4o-mini, gpt-4-turbo | gpt-4o |
| Anthropic | claude-3-5-sonnet-20241022, claude-3-haiku | claude-3-5-sonnet-20241022 |
| Google | gemini-2.5-pro-latest, gemini-1.5-flash | gemini-2.5-pro-latest |
Example Project
Check out the included example in the
./example directory:`bash
cd example
npm install
npm run dev
`The example demonstrates:
- Auto-discovery of components/utilities
- Two-phase generation with spec viewer
- All AI providers
- Template library usage
- Real-time rendering
Requirements
- Node.js 18+
- React 18+
- At least one AI provider API key
Migration from v1.x
No breaking changes! All existing code works without modifications.
To use new features:
1. Create
vibe-overlord.config.ts
2. Enable features in config
3. Auto-discovery works automaticallyContributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
ISC
Acknowledgments
Built on mdx-bundler by Kent C. Dodds.
Support
- GitHub Issues
- Example Project
- Implementation Summary
Releasing (npm)
This repo uses Changesets + GitHub Actions to publish to npm and create GitHub Releases automatically.
$3
- Set repository secret
NPM_TOKEN with an npm token that has publish access
- The workflow .github/workflows/release.yml already has the right permissions:
- contents: write and pull-requests: write
- Uses Changesets’ built‑in GitHub Release creation (createGithubReleases: true)$3
1) Create a changeset (choose patch/minor/major):
`bash
npx @changesets/cli add
git add .
git commit -m "chore: add changeset"
git push
`2) The Release PR is opened automatically by the workflow (title: "Release"). Review and merge it.
3) When the Release PR merges into
main, the workflow:
- builds the package
- publishes to npm (new version)
- creates a Git tag vX.Y.Z
- creates a GitHub Release with notesThat’s it—no manual tagging or publishing required.
$3
`bash
enter prerelease mode (publishes under the
next dist-tag)
npx @changesets/cli pre enter nextadd a tiny patch changeset and commit
npx @changesets/cli add
git add .
git commit -m "chore: prerelease test"
git pusha Release PR will open; merge it → publish to
nextafter testing, exit prerelease mode so future releases are normal
npx @changesets/cli pre exit
git add .changeset/pre.json || true
git commit -m "chore: exit prerelease mode" || true
git push
`$3
- The publish step is idempotent (we ignore EPUBLISHCONFLICT/“previously published version” on reruns)
- If a job is retried after a successful publish, it will still pass
- GitHub Release creation is handled by Changesets, so tag/release races are avoided
$3
- "Cannot publish over previously published version" during a retry: expected; rerun succeeds due to idempotent publish
- "Resource not accessible by integration" creating the Release PR: ensure workflow
permissions: contents: write and pull-requests: write
- Do not force‑push main during a release; if you do, just let the workflow rerun—publishing is safe
- To rollback what users install without deleting versions: use npm dist-tag add vibe-overlord@ and/or npm deprecate`