| Understand what DeepChat is and when to use it |
DeepChat Overview |
Use DeepChat when you need a drop-in chat widget with minimal configuration. Use Chatbot UI or Vercel AI Chat when you need full control over UI/UX. |
| Install and configure DeepChat in Next.js |
Installation & Setup |
Use dynamic import with ssr: false for all DeepChat instances in Next.js. DeepChat is a web component that requires browser APIs. |
| Configure the connect property and interceptors |
Connect Configuration |
Use connect property to define API endpoint and headers. Use interceptors to inject context, track threads, or modify requests/responses. |
| Create Next.js API route handlers |
Next.js API Routes |
Use proxy pattern for Drupal/external backends. Use CSRF flow for Drupal with OAuth + CSRF. |
| Handle CSRF tokens and authentication |
Next.js API Routes |
Use proxy pattern for Drupal/external backends. Use CSRF flow for Drupal with OAuth + CSRF. |
| Implement SSE streaming responses |
Streaming Responses |
Use SSE streaming for AI chat responses. Use ReadableStream with transform for OpenAI/Anthropic. |
| Structure messages and handle history |
Message Formats & History |
Send only current message + thread_id for Drupal/session backends. Send full history for stateless backends. |
| Integrate with Drupal AI module |
Drupal Backend Integration |
Use Drupal AI module endpoints when ai_chatbot and ai_assistant_api modules are installed. Use CSRF token in query parameter, not header. |
| Connect directly to OpenAI or Anthropic |
AI Provider Integration |
Use Drupal AI module when available. Use direct provider integration for simple Next.js apps. |
| Style and theme DeepChat |
Styling & Theming |
Use CSS variables for brand colors. Use messageStyles for message bubbles. |
| Upload files and images |
File Upload & Attachments |
Use images for image upload/analysis. Use mixedFiles for any file type (PDFs, docs). |
| Add custom request handlers |
Custom Handlers |
Use custom handler for complex request flow or retry logic. Use interceptors for simple transforms. |
| Implement authentication and sessions |
Authentication & Sessions |
Use NextAuth + Bearer token for user-specific chat. Use OAuth + CSRF flow for Drupal backend. |
| Follow architecture best practices |
Best Practices & Patterns |
Lazy load when chat not immediately visible. Use error boundaries in production. |
| Prevent XSS attacks and secure the app |
Security |
Always sanitize AI output on server. Never expose API keys client-side. |
| Avoid common mistakes |
Anti-Patterns & Common Mistakes |
Common mistakes and anti-patterns to avoid in DeepChat + Next.js integration |