@vibeship/devtools
Version:
Comprehensive markdown-based project management system with AI capabilities for Next.js applications
378 lines (286 loc) • 9.06 kB
Markdown
# @vibeship/devtools
Transform your markdown documentation into an intelligent project management system with AI capabilities for Next.js applications.
[](https://www.npmjs.com/package/@vibeship/devtools)
[](https://opensource.org/licenses/MIT)
## 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
```bash
npx @vibeship/devtools init
```
This 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
```bash
npm install @vibeship/devtools
```
### 3. Start your dev server
```bash
npm run dev
```
### 4. 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:
```bash
npx @vibeship/devtools init
```
### Standard Setup
Creates separate API routes for better organization:
```bash
npx @vibeship/devtools init --level standard
```
### Advanced Setup
Full control with all configuration options:
```bash
npx @vibeship/devtools init --level advanced
```
## Manual Setup
### App Router
```typescript
// app/layout.tsx
import { VibeshipProviderWithDeps } from '@vibeship/devtools';
export default function RootLayout({ children }) {
return (
<html>
<body>
<VibeshipProviderWithDeps>
{children}
</VibeshipProviderWithDeps>
</body>
</html>
);
}
```
### Pages Router
```typescript
// 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
1. **Install optional AI dependencies** (only what you need):
```bash
# For OpenAI
npm install openai
# For Anthropic
npm install @anthropic-ai/sdk
# For streaming UI helpers
npm install ai
```
2. **Configure AI in your app** (optional - for custom AI providers):
```typescript
import { AISettingsProvider } from '@vibeship/devtools';
export default function RootLayout({ children }) {
return (
<html>
<body>
<AISettingsProvider>
{children}
</AISettingsProvider>
</body>
</html>
);
}
```
3. **Add AI chat route** (if using AI features):
```typescript
// app/api/vibeship/ai/chat/route.ts
export { POST } from '@vibeship/devtools/api';
```
### Using AI Features
1. Open DevTools (`Ctrl+Shift+D`)
2. Go to Settings → AI Settings
3. Choose your provider (OpenAI, Anthropic, or XAI)
4. Enter your API key (securely encrypted in browser)
5. Select your preferred model
6. 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:
```typescript
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
```typescript
// app/api/vibeship/tasks/route.ts
export { GET, POST } from '@vibeship/devtools/api';
```
### Files API
```typescript
// app/api/vibeship/files/route.ts
export { GET, POST } from '@vibeship/devtools/api';
```
### AI Chat API
```typescript
// app/api/vibeship/ai/chat/route.ts
export { POST } from '@vibeship/devtools/api';
```
## Advanced Usage
### Custom API Client
```typescript
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
```typescript
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:
```typescript
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
```bash
# .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=true
```
## CLI Reference
```bash
# 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 value
```
## TypeScript Support
Full TypeScript support with exported types:
```typescript
import type {
Task,
FileInfo,
VibeshipConfig,
VibeshipProvider
} from '@vibeship/devtools';
```
## Troubleshooting
### DevTools not showing up
1. Check that the provider is added to your layout
2. Verify API routes are created
3. Try the hotkey (Cmd+Shift+K on Mac, Ctrl+Shift+K on Windows/Linux)
4. Check browser console for errors
### AI Settings Panel not showing
See our [Troubleshooting Guide](./docs/TROUBLESHOOTING.md#ai-settings-panel-component-not-provided) for detailed solutions.
### API errors
1. Ensure all API routes are properly set up
2. Check CORS settings if using custom domain
3. Verify environment variables are set
### Build errors
1. Clear `.next` cache: `rm -rf .next`
2. Reinstall dependencies: `rm -rf node_modules && npm install`
3. Check for version mismatches
For more detailed troubleshooting, see our [Troubleshooting Guide](./docs/TROUBLESHOOTING.md).
## Contributing
We welcome contributions! Please see our [Contributing Guide](https://github.com/vibeship/devtools/blob/main/CONTRIBUTING.md) for details.
## License
MIT © Vibeship
## Links
- [Documentation](https://vibeship.dev/docs)
- [GitHub Repository](https://github.com/vibeship/devtools)
- [NPM Package](https://www.npmjs.com/package/@vibeship/devtools)
- [Changelog](https://github.com/vibeship/devtools/blob/main/CHANGELOG.md)
---
Made with ❤️ by the Vibeship team