@vibeship/devtools
v1.1.4
Published
Comprehensive markdown-based project management system with AI capabilities for Next.js applications
Maintainers
h0bb5Readme
@vibeship/devtools
Transform your markdown documentation into an intelligent project management system with AI capabilities for Next.js applications.
Features
- 📝 Living Documentation: Interactive markdown files that update in real-time
- 🤖 AI Integration: Built-in support for OpenAI, Anthropic, and XAI
- 📋 Smart Task Extraction: Automatically finds TODO, FIXME, and other markers in your code
- 🚀 Real-time Updates: Hot reload and SSE for instant feedback
- 🎨 Modern UI: Beautiful, responsive floating panel interface
- 🔧 Zero Config: Works out of the box with sensible defaults
- 🏗️ Framework Support: Full support for Next.js App Router and Pages Router
- 🔐 Secure API Keys: Client-side encryption for API key storage
- 💬 AI Chat Interface: Streaming responses with model selection
- ⚙️ Multi-Provider: Choose your preferred AI provider and model
Quick Start
1. Install in your Next.js project
npx @vibeship/devtools initThis will:
- Detect your Next.js setup (App/Pages Router, src directory)
- Create necessary API routes
- Set up configuration file
- Add provider to your layout
2. Install the package
npm install @vibeship/devtools3. Start your dev server
npm run dev4. Open the DevTools
Press Ctrl+Shift+D (or Cmd+Shift+D on Mac) to toggle the DevTools panel.
Setup Levels
Quick Setup (Default)
Creates a single API route file that handles all endpoints:
npx @vibeship/devtools initStandard Setup
Creates separate API routes for better organization:
npx @vibeship/devtools init --level standardAdvanced Setup
Full control with all configuration options:
npx @vibeship/devtools init --level advancedManual Setup
App Router
// app/layout.tsx
import { VibeshipProviderWithDeps } from '@vibeship/devtools';
export default function RootLayout({ children }) {
return (
<html>
<body>
<VibeshipProviderWithDeps>
{children}
</VibeshipProviderWithDeps>
</body>
</html>
);
}Pages Router
// pages/_app.tsx
import { VibeshipProviderWithDeps } from '@vibeship/devtools';
export default function MyApp({ Component, pageProps }) {
return (
<VibeshipProviderWithDeps>
<Component {...pageProps} />
</VibeshipProviderWithDeps>
);
}AI Features (New in v1.1.0!)
The AI Settings Panel is included by default when using VibeshipProviderWithDeps. You can access it through the Settings tab in the DevTools panel.
Setting Up AI
- Install optional AI dependencies (only what you need):
# For OpenAI
npm install openai
# For Anthropic
npm install @anthropic-ai/sdk
# For streaming UI helpers
npm install ai- Configure AI in your app (optional - for custom AI providers):
import { AISettingsProvider } from '@vibeship/devtools';
export default function RootLayout({ children }) {
return (
<html>
<body>
<AISettingsProvider>
{children}
</AISettingsProvider>
</body>
</html>
);
}- Add AI chat route (if using AI features):
// app/api/vibeship/ai/chat/route.ts
export { POST } from '@vibeship/devtools/api';Using AI Features
- Open DevTools (
Ctrl+Shift+D) - Go to Settings → AI Settings
- Choose your provider (OpenAI, Anthropic, or XAI)
- Enter your API key (securely encrypted in browser)
- Select your preferred model
- Start chatting with AI about your project!
Security
- API keys are encrypted client-side using Web Crypto API
- Keys never leave your browser unencrypted
- No vendor lock-in - use your own API keys
- Provider selection is completely flexible
Configuration
Create a vibeship.config.ts file in your project root:
import { defineConfig } from '@vibeship/devtools/config';
export default defineConfig({
// Paths to scan for tasks
scanPaths: ['./src', './app', './docs'],
// Features to enable
features: {
tasks: true,
ai: true,
realtime: true,
commandPalette: true,
fileEditing: true,
markdownPreview: true,
},
// UI preferences
ui: {
theme: 'system',
position: 'bottom-right',
defaultSize: { width: '400px', height: '600px' },
hotkey: 'ctrl+shift+d',
showInProduction: false,
},
});API Routes
The DevTools require API routes for functionality. The init command creates these automatically, but you can also create them manually:
Tasks API
// app/api/vibeship/tasks/route.ts
export { GET, POST } from '@vibeship/devtools/api';Files API
// app/api/vibeship/files/route.ts
export { GET, POST } from '@vibeship/devtools/api';AI Chat API
// app/api/vibeship/ai/chat/route.ts
export { POST } from '@vibeship/devtools/api';Advanced Usage
Custom API Client
import { VibeshipProvider } from '@vibeship/devtools';
import { VibeshipAPIClient } from '@vibeship/api-client';
const apiClient = new VibeshipAPIClient({
baseURL: '/api/vibeship',
timeout: 30000,
headers: {
'X-Custom-Header': 'value'
}
});
export default function App({ children }) {
return (
<VibeshipProvider apiClient={apiClient}>
{children}
</VibeshipProvider>
);
}Custom Task Fetching
import { VibeshipProviderWithDeps } from '@vibeship/devtools';
const getProjectTasks = async (params) => {
const response = await fetch(`/api/tasks?${new URLSearchParams(params)}`);
const data = await response.json();
return data.tasks;
};
export default function App({ children }) {
return (
<VibeshipProviderWithDeps getProjectTasks={getProjectTasks}>
{children}
</VibeshipProviderWithDeps>
);
}Custom UI Components
You can provide custom implementations for any UI component:
import { VibeshipProviderWithDeps, AISettingsPanel } from '@vibeship/devtools';
import { MyCustomAISettingsPanel } from './components/MyCustomAISettingsPanel';
export default function App({ children }) {
return (
<VibeshipProviderWithDeps
// Use custom AI Settings Panel
AISettingsPanel={MyCustomAISettingsPanel}
>
{children}
</VibeshipProviderWithDeps>
);
}Note: If you don't provide custom components, default implementations are included automatically.
Environment Variables
# .env.local
# Security
VIBESHIP_DISABLE_FILE_WRITES=false
# API Configuration
NEXT_PUBLIC_VIBESHIP_API_PATH=/api/vibeship
# AI Provider Keys (optional)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=...
# Feature Flags
NEXT_PUBLIC_VIBESHIP_FEATURE_AI=true
NEXT_PUBLIC_VIBESHIP_FEATURE_TASKS=trueCLI Reference
# Initialize DevTools
npx @vibeship/devtools init [options]
-l, --level <level> Setup level: quick, standard, or advanced
-y, --yes Skip confirmation prompts
-f, --force Overwrite existing files
# Configure DevTools
npx @vibeship/devtools config <action> [options]
list List current configuration
get <key> Get a configuration value
set <key> <value> Set a configuration valueTypeScript Support
Full TypeScript support with exported types:
import type {
Task,
FileInfo,
VibeshipConfig,
VibeshipProvider
} from '@vibeship/devtools';Troubleshooting
DevTools not showing up
- Check that the provider is added to your layout
- Verify API routes are created
- Try the hotkey (Cmd+Shift+K on Mac, Ctrl+Shift+K on Windows/Linux)
- Check browser console for errors
AI Settings Panel not showing
See our Troubleshooting Guide for detailed solutions.
API errors
- Ensure all API routes are properly set up
- Check CORS settings if using custom domain
- Verify environment variables are set
Build errors
- Clear
.nextcache:rm -rf .next - Reinstall dependencies:
rm -rf node_modules && npm install - Check for version mismatches
For more detailed troubleshooting, see our Troubleshooting Guide.
Contributing
We welcome contributions! Please see our Contributing Guide for details.
License
MIT © Vibeship
Links
Made with ❤️ by the Vibeship team