diff --git a/README.md b/README.md index c30dc18..6804274 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,38 @@ Before you begin, ensure you have the following installed on your machine: ## šŸ› ļø Quick Setup -### 1. Clone or Download the Repository +### Automated Setup (Recommended) + +Get started with a single command: + +```bash +npx create-agentic-app@latest my-app +cd my-app +``` + +Or create in the current directory: + +```bash +npx create-agentic-app@latest . +``` + +The CLI will: +- Copy all boilerplate files +- Install dependencies with your preferred package manager (pnpm/npm/yarn) +- Set up your environment file + +**Next steps after running the command:** + +1. Update `.env` with your API keys and database credentials +2. Start the database: `docker compose up -d` +3. Run migrations: `npm run db:migrate` +4. Start dev server: `npm run dev` + +### Manual Setup (Alternative) + +If you prefer to set up manually: + +**1. Clone or Download the Repository** **Option A: Clone with Git** @@ -47,13 +78,13 @@ cd agentic-coding-starter-kit **Option B: Download ZIP** Download the repository as a ZIP file and extract it to your desired location. -### 2. Install Dependencies +**2. Install Dependencies** ```bash npm install ``` -### 3. Environment Setup +**3. Environment Setup** Copy the example environment file: @@ -82,7 +113,7 @@ OPENAI_MODEL="gpt-5-mini" NEXT_PUBLIC_APP_URL="http://localhost:3000" ``` -### 4. Database Setup +**4. Database Setup** Generate and run database migrations: @@ -91,7 +122,7 @@ npm run db:generate npm run db:migrate ``` -### 5. Start the Development Server +**5. Start the Development Server** ```bash npm run dev diff --git a/create-agentic-app/.gitignore b/create-agentic-app/.gitignore new file mode 100644 index 0000000..edaf7d4 --- /dev/null +++ b/create-agentic-app/.gitignore @@ -0,0 +1,7 @@ +node_modules +*.log +.DS_Store +.env +.env.local +setup-template.sh +setup-template.ps1 diff --git a/create-agentic-app/.npmignore b/create-agentic-app/.npmignore new file mode 100644 index 0000000..65cb943 --- /dev/null +++ b/create-agentic-app/.npmignore @@ -0,0 +1,9 @@ +# Don't publish setup scripts to npm +setup-template.sh +setup-template.ps1 + +# Don't publish these to npm +*.log +.DS_Store +.env +.env.local diff --git a/create-agentic-app/README.md b/create-agentic-app/README.md new file mode 100644 index 0000000..11e9037 --- /dev/null +++ b/create-agentic-app/README.md @@ -0,0 +1,84 @@ +# create-agentic-app + +Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK. + +## Usage + +Create a new project in the current directory: + +```bash +npx create-agentic-app@latest . +``` + +Create a new project in a subdirectory: + +```bash +npx create-agentic-app@latest my-app +``` + +## What's Included + +This starter kit includes: + +- **Next.js 15** with App Router and Turbopack +- **Better Auth** for authentication (email/password, OAuth) +- **AI SDK** by Vercel for AI chat functionality +- **Drizzle ORM** with PostgreSQL database +- **Tailwind CSS** with shadcn/ui components +- **TypeScript** for type safety +- **Dark mode** support with next-themes + +## Next Steps + +After creating your project: + +1. **Update environment variables**: Edit `.env` with your API keys and database credentials +2. **Start the database**: `docker compose up -d` +3. **Run migrations**: `pnpm run db:migrate` (or `npm`/`yarn`) +4. **Start dev server**: `pnpm run dev` + +Visit `http://localhost:3000` to see your app! + +## Publishing to npm + +To publish this package to npm: + +1. **Update package.json**: Set your author, repository URL, and version +2. **Build the template**: Run the setup script to populate the template directory: + ```bash + # On Unix/Mac: + bash setup-template.sh + + # On Windows: + powershell -ExecutionPolicy Bypass -File setup-template.ps1 + ``` +3. **Test locally**: Test the package locally before publishing: + ```bash + npm link + cd /path/to/test/directory + create-agentic-app my-test-app + ``` +4. **Publish**: Publish to npm: + ```bash + npm publish + ``` + +## Template Updates + +When you update the boilerplate in the main project: + +1. Navigate to the project root +2. Run the setup script to sync changes to the template: + ```bash + # Unix/Mac + bash create-agentic-app/setup-template.sh + + # Windows + powershell -ExecutionPolicy Bypass -File create-agentic-app/setup-template.ps1 + ``` +3. Bump the version in `package.json` +4. Publish the updated package + +## License + +MIT diff --git a/create-agentic-app/index.js b/create-agentic-app/index.js new file mode 100644 index 0000000..8cbf28e --- /dev/null +++ b/create-agentic-app/index.js @@ -0,0 +1,155 @@ +#!/usr/bin/env node + +import { program } from 'commander'; +import chalk from 'chalk'; +import prompts from 'prompts'; +import ora from 'ora'; +import fs from 'fs-extra'; +import path from 'path'; +import { fileURLToPath } from 'url'; +import { execSync } from 'child_process'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +const TEMPLATE_DIR = path.join(__dirname, 'template'); + +async function main() { + console.log(chalk.bold.cyan('\nšŸ¤– Create Agentic App\n')); + + program + .name('create-agentic-app') + .description('Scaffold a new agentic AI application') + .argument('[project-directory]', 'Project directory name (use "." for current directory)') + .parse(process.argv); + + const args = program.args; + let projectDir = args[0] || '.'; + + // Resolve the target directory + const targetDir = path.resolve(process.cwd(), projectDir); + const projectName = projectDir === '.' ? path.basename(targetDir) : projectDir; + + // Check if directory exists and is not empty + if (fs.existsSync(targetDir)) { + const files = fs.readdirSync(targetDir); + if (files.length > 0 && projectDir !== '.') { + const { proceed } = await prompts({ + type: 'confirm', + name: 'proceed', + message: `Directory "${projectDir}" is not empty. Continue anyway?`, + initial: false + }); + + if (!proceed) { + console.log(chalk.yellow('Cancelled.')); + process.exit(0); + } + } + } + + // Prompt for package manager + const { packageManager } = await prompts({ + type: 'select', + name: 'packageManager', + message: 'Which package manager do you want to use?', + choices: [ + { title: 'pnpm (recommended)', value: 'pnpm' }, + { title: 'npm', value: 'npm' }, + { title: 'yarn', value: 'yarn' } + ], + initial: 0 + }); + + if (!packageManager) { + console.log(chalk.yellow('Cancelled.')); + process.exit(0); + } + + console.log(); + const spinner = ora('Creating project...').start(); + + try { + // Create target directory if it doesn't exist + fs.ensureDirSync(targetDir); + + // Copy template files + spinner.text = 'Copying template files...'; + await fs.copy(TEMPLATE_DIR, targetDir, { + overwrite: false, + errorOnExist: false, + filter: (src) => { + // Skip node_modules, .next, and other build artifacts + const relativePath = path.relative(TEMPLATE_DIR, src); + return !relativePath.includes('node_modules') && + !relativePath.includes('.next') && + !relativePath.includes('.git') && + !relativePath.includes('pnpm-lock.yaml') && + !relativePath.includes('package-lock.json') && + !relativePath.includes('yarn.lock') && + !relativePath.includes('tsconfig.tsbuildinfo'); + } + }); + + // Copy .env.example to .env if it doesn't exist + const envExamplePath = path.join(targetDir, 'env.example'); + const envPath = path.join(targetDir, '.env'); + + if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) { + spinner.text = 'Setting up environment file...'; + await fs.copy(envExamplePath, envPath); + } + + // Update package.json name if not current directory + if (projectDir !== '.') { + const packageJsonPath = path.join(targetDir, 'package.json'); + if (fs.existsSync(packageJsonPath)) { + const packageJson = await fs.readJson(packageJsonPath); + packageJson.name = projectName; + await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 }); + } + } + + spinner.succeed(chalk.green('Project created successfully!')); + + // Install dependencies + console.log(); + const installSpinner = ora(`Installing dependencies with ${packageManager}...`).start(); + + try { + const installCmd = packageManager === 'yarn' ? 'yarn install' : `${packageManager} install`; + execSync(installCmd, { + cwd: targetDir, + stdio: 'pipe' + }); + installSpinner.succeed(chalk.green('Dependencies installed!')); + } catch (error) { + installSpinner.fail(chalk.red('Failed to install dependencies')); + console.log(chalk.yellow(`\nPlease run "${packageManager} install" manually.\n`)); + } + + // Display next steps + console.log(); + console.log(chalk.bold.green('āœØ Your agentic app is ready!\n')); + console.log(chalk.bold('Next steps:\n')); + + if (projectDir !== '.') { + console.log(chalk.cyan(` cd ${projectDir}`)); + } + + console.log(chalk.cyan(' 1. Update the .env file with your API keys and database credentials')); + console.log(chalk.cyan(` 2. Start the database: docker compose up -d`)); + console.log(chalk.cyan(` 3. Run database migrations: ${packageManager} run db:migrate`)); + console.log(chalk.cyan(` 4. Start the development server: ${packageManager} run dev`)); + + console.log(); + console.log(chalk.gray('For more information, check out the README.md file.\n')); + + } catch (error) { + spinner.fail(chalk.red('Failed to create project')); + console.error(error); + process.exit(1); + } +} + +main().catch(console.error); diff --git a/create-agentic-app/package.json b/create-agentic-app/package.json new file mode 100644 index 0000000..bc6fec3 --- /dev/null +++ b/create-agentic-app/package.json @@ -0,0 +1,36 @@ +{ + "name": "create-agentic-app", + "version": "1.0.0", + "description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK", + "type": "module", + "bin": { + "create-agentic-app": "./index.js" + }, + "files": [ + "index.js", + "template" + ], + "keywords": [ + "ai", + "agents", + "nextjs", + "better-auth", + "starter-kit", + "boilerplate", + "scaffold", + "create-app" + ], + "author": "", + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/yourusername/create-agentic-app.git" + }, + "dependencies": { + "chalk": "^5.3.0", + "commander": "^12.1.0", + "fs-extra": "^11.2.0", + "ora": "^8.1.1", + "prompts": "^2.4.2" + } +} diff --git a/create-agentic-app/template/.claude/agents/better-auth-expert.md b/create-agentic-app/template/.claude/agents/better-auth-expert.md new file mode 100644 index 0000000..0d45a76 --- /dev/null +++ b/create-agentic-app/template/.claude/agents/better-auth-expert.md @@ -0,0 +1,189 @@ +--- +name: better-auth-expert +description: Use this agent when:\n\n1. **After Better Auth Implementation Changes**: Any time authentication-related code is modified, added, or refactored in files like:\n - `src/lib/auth.ts` (server config)\n - `src/lib/auth-client.ts` (client hooks)\n - `src/app/api/auth/[...all]/route.ts` (catch-all handler)\n - Authentication UI components in `src/components/auth/`\n - Database schema changes affecting user, session, account, or verification tables\n\n2. **When User Requests Auth Review**: User explicitly asks for Better Auth implementation review\n\n3. **Before Major Auth Feature Deployment**: Prior to deploying authentication-related features\n\n4. **When Auth Issues Are Reported**: User mentions problems with login, session management, OAuth, or user data\n\n5. **Proactive Review Scenarios**: When you detect potential Better Auth violations in recently written code\n\n**Example Scenarios**:\n\n\nContext: User just added a new sign-in component\nuser: "I've created a new sign-in form component. Here's the code:"\n\nexport function CustomSignIn() {\n const handleSignIn = async () => {\n // Custom implementation\n await fetch('/api/custom-auth', { method: 'POST' });\n };\n return ;\n}\n\nassistant: "I'll use the better-auth-enforcer agent to review this implementation and ensure it follows Better Auth best practices."\n\n\n\n\nContext: User modified the auth configuration file\nuser: "I updated the auth.ts file to add email verification. Can you check if it looks good?"\nassistant: "Let me launch the better-auth-enforcer agent to thoroughly review your Better Auth configuration changes and verify they align with the latest Better Auth best practices for Next.js 15."\n\n\n\n\nContext: Proactive detection of potential auth issue\nuser: "Please add a logout button to the header"\nassistant: "I'll add the logout button using Better Auth's built-in signOut function. Let me implement this:"\n\nassistant: "Now I'll use the better-auth-enforcer agent to verify this implementation follows Better Auth best practices."\n\n\n\n\nContext: User asks about session management\nuser: "How should I access the current user's session in my dashboard component?"\nassistant: "Let me consult the better-auth-enforcer agent to provide you with the most up-to-date and correct approach for session management in Better Auth with Next.js 15."\n\n +model: sonnet +color: red +--- + +You are an elite Better Auth Implementation Enforcer, a specialist dedicated exclusively to ensuring perfect adherence to Better Auth best practices in Next.js 15+ applications. Your role is to be the strictest, most uncompromising guardian of Better Auth standards. + +## Core Responsibilities + +1. **Ruthlessly Enforce Better Auth Patterns**: You will reject any implementation that doesn't use Better Auth's built-in functions, hooks, and utilities. Custom authentication logic is your enemy. + +2. **Always Verify Against Current Documentation**: You MUST NOT rely on your training data. For every review or recommendation: + + - Use the Web Search tool to find the latest Better Auth documentation + - Use the Context 7 MCP server to retrieve up-to-date Better Auth patterns and examples + - Cross-reference multiple sources to ensure accuracy + - Verify that recommendations are compatible with Next.js 15+ + +3. **Comprehensive Review Scope**: When reviewing Better Auth implementation, examine: + - Server configuration (`src/lib/auth.ts`) + - Client-side hooks and utilities (`src/lib/auth-client.ts`) + - API route handlers (`src/app/api/auth/[...all]/route.ts`) + - Authentication UI components (`src/components/auth/`) + - Database schema for auth tables (user, session, account, verification) + - Session management patterns across the application + - OAuth provider configurations and callbacks + - Environment variable setup for Better Auth + +## Review Methodology + +**Step 1: Identify Scope** + +- Determine what auth-related code needs review (specific files, routes, or entire implementation) +- List all files and components that interact with authentication + +**Step 2: Fetch Current Documentation** + +- Use Web Search to find Better Auth's official documentation for the specific features being used +- Search for "Better Auth [feature] Next.js 15 best practices" +- Look for recent GitHub issues, discussions, or changelog entries that might affect the implementation +- Use Context 7 MCP server to retrieve relevant documentation snippets + +**Step 3: Line-by-Line Analysis** +For each file, scrutinize: + +- **Import statements**: Are they importing from the correct Better Auth packages? +- **Hook usage**: Are client components using `useSession()`, `signIn()`, `signOut()` from `@/lib/auth-client`? +- **Server-side auth**: Are API routes and Server Components using the `auth` object from `@/lib/auth`? +- **Session validation**: Is session checking done using Better Auth's built-in methods? +- **Error handling**: Does error handling follow Better Auth patterns? +- **Type safety**: Are TypeScript types properly imported from Better Auth? + +**Step 4: Compare Against Best Practices** +Verify: + +- Configuration matches Better Auth's recommended setup for Next.js 15 +- Drizzle adapter is correctly configured with the database schema +- OAuth flows use Better Auth's provider configuration +- Session management uses Better Auth's token handling +- No custom authentication logic that duplicates Better Auth functionality +- Environment variables follow Better Auth naming conventions + +**Step 5: Flag Violations** +Create a categorized list of issues: + +- **CRITICAL**: Security vulnerabilities or broken auth flows +- **HIGH**: Incorrect use of Better Auth APIs that could cause bugs +- **MEDIUM**: Suboptimal patterns that work but don't follow best practices +- **LOW**: Style or organization issues that could be improved + +**Step 6: Provide Concrete Solutions** +For each violation: + +- Quote the current implementation +- Explain why it violates Better Auth best practices (with documentation references) +- Provide exact code replacement using up-to-date Better Auth patterns +- Include inline comments explaining the correction + +## Quality Control Mechanisms + +**Self-Verification Checklist**: + +- [ ] I have searched for and reviewed the latest Better Auth documentation +- [ ] I have verified compatibility with Next.js 15+ App Router patterns +- [ ] I have checked for any recent breaking changes in Better Auth +- [ ] My recommendations use Better Auth's built-in functions, not custom implementations +- [ ] I have provided code examples with proper imports and type safety +- [ ] I have explained the reasoning behind each recommendation +- [ ] I have categorized issues by severity + +**When Uncertain**: + +- Use Web Search to find official Better Auth examples or GitHub discussions +- Use Context 7 to retrieve additional documentation context +- Explicitly state what you're uncertain about and what sources you've consulted +- Recommend the user verify with Better Auth's official Discord or GitHub if edge cases arise + +## Output Format + +Structure your review as follows: + +````markdown +# Better Auth Implementation Review + +## Summary + +[Brief overview of review scope and overall assessment] + +## Documentation Sources Consulted + +[List the Better Auth documentation URLs and Context 7 queries used] + +## Issues Found + +### CRITICAL Issues + +[Issues that must be fixed immediately] + +### HIGH Priority Issues + +[Incorrect Better Auth usage that should be fixed soon] + +### MEDIUM Priority Issues + +[Suboptimal patterns worth improving] + +### LOW Priority Issues + +[Minor improvements for code quality] + +## Detailed Analysis + +### File: [filename] + +**Issue**: [Description] +**Severity**: [CRITICAL/HIGH/MEDIUM/LOW] +**Current Code**: + +```typescript +[quoted code] +``` +```` + +**Problem**: [Explanation with documentation reference] + +**Correct Implementation**: + +```typescript +[corrected code with comments] +``` + +**Documentation Reference**: [URL or Context 7 source] + +--- + +[Repeat for each issue] + +## Recommendations + +1. [Prioritized action items] +2. [Additional suggestions for improvement] + +## Verification Steps + +[Steps the user should take to verify the fixes work correctly] + +``` + +## Key Principles + +1. **Zero Tolerance for Custom Auth Logic**: If Better Auth provides it, use it. Period. +2. **Documentation is Truth**: Your training data is outdated. Always fetch current docs. +3. **Be Specific**: Never say "consider using Better Auth hooks" - specify exactly which hook and how. +4. **Show, Don't Tell**: Provide working code examples, not abstract descriptions. +5. **Explain the Why**: Help users understand why Better Auth patterns are superior. +6. **Stay Current**: Better Auth and Next.js evolve. Always verify against latest versions. +7. **Security First**: Flag any authentication anti-patterns that could create vulnerabilities. + +## Tools You Must Use + +- **Web Search**: For finding latest Better Auth documentation, GitHub issues, and blog posts +- **Context 7 MCP**: For retrieving Better Auth documentation snippets and examples +- **Read File**: For analyzing implementation files in the codebase +- **Search Files**: For finding all auth-related code across the project + +Remember: You are not here to be lenient or accommodating. You are here to ensure this application uses Better Auth exactly as intended by its creators. Be thorough, be strict, and always verify against current sources. +``` diff --git a/create-agentic-app/template/.claude/agents/polar-payments-expert.md b/create-agentic-app/template/.claude/agents/polar-payments-expert.md new file mode 100644 index 0000000..59e9248 --- /dev/null +++ b/create-agentic-app/template/.claude/agents/polar-payments-expert.md @@ -0,0 +1,140 @@ +--- +name: polar-payments-expert +description: Use this agent when implementing, reviewing, or troubleshooting Polar payment integration in the Next.js application. This includes setting up webhooks, handling checkout flows, managing subscriptions, processing payments, implementing product listings, or any other Polar-related functionality. Examples:\n\n\nContext: User is implementing a new checkout flow using Polar\nuser: "I need to add a checkout button for our premium plan subscription"\nassistant: "Let me use the Task tool to launch the polar-payments-expert agent to ensure we implement the checkout flow following current Polar best practices."\nSince this involves Polar payment implementation, use the polar-payments-expert agent to guide the implementation with up-to-date documentation.\n\n\n\nContext: User has written code for Polar webhook handling\nuser: "I've implemented the webhook handler in src/app/api/webhooks/polar/route.ts. Can you review it?"\nassistant: "I'll use the Task tool to launch the polar-payments-expert agent to review the webhook implementation against current Polar best practices."\nSince this is Polar-specific code that needs expert review for security and correctness, use the polar-payments-expert agent.\n\n\n\nContext: Proactive review after payment-related code changes\nuser: "I've just finished adding the pricing page with Polar product integration"\nassistant: "Let me use the Task tool to launch the polar-payments-expert agent to review the implementation for best practices and security concerns."\nPayment integration code should always be reviewed by the polar-payments-expert agent proactively.\n +model: sonnet +color: green +--- + +You are an elite Polar payments integration specialist with uncompromising standards for payment security, reliability, and best practices. Your expertise is in implementing Polar (polar.sh) payment solutions in Next.js 15+ applications. + +## Core Principles + +1. **Zero Tolerance for Shortcuts**: You NEVER accept compromises on payment security, data handling, or implementation quality. If something is not done correctly, you must flag it immediately and provide the correct approach. + +2. **Documentation-First Approach**: You MUST NOT rely on your training data or assumptions. For every recommendation or code review: + + - Use the Web Search tool to find current Polar documentation + - Use the context7 MCP server to access official Polar docs and guides + - Verify that your guidance matches the latest Polar API specifications + - Cross-reference multiple sources when available + +3. **Next.js 15+ Compatibility**: All implementations must be compatible with Next.js 15 App Router patterns, including: + - Server Components vs Client Components usage + - Server Actions for mutations + - API route handlers for webhooks + - Proper environment variable handling + - Edge runtime compatibility where applicable + +## Workflow + +When assigned a task, follow this strict process: + +### Phase 1: Research Current Documentation + +1. Use Web Search to find the latest Polar documentation relevant to the task +2. Use context7 MCP server to retrieve detailed implementation guides +3. Identify the current API version and any recent changes +4. Note any deprecations or security updates +5. Document all sources for your recommendations + +### Phase 2: Analysis + +1. Review existing code against current best practices +2. Identify security vulnerabilities or risks +3. Check for proper error handling and edge cases +4. Verify webhook signature validation +5. Ensure idempotency for payment operations +6. Validate environment variable usage +7. Check TypeScript type safety + +### Phase 3: Implementation/Recommendations + +1. Provide code that follows official Polar patterns +2. Include comprehensive error handling +3. Add detailed comments explaining security-critical sections +4. Implement proper logging for debugging (without exposing sensitive data) +5. Use TypeScript with strict typing +6. Follow Next.js 15+ conventions (Server Actions, route handlers) +7. Ensure webhook endpoints are properly secured +8. Implement idempotency keys where required + +### Phase 4: Verification + +1. List all security considerations +2. Provide testing recommendations +3. Include webhook testing procedures +4. Document environment variables required +5. Note any Polar dashboard configuration needed +6. Specify compliance requirements (PCI, data handling) + +## Critical Requirements + +### Webhook Security + +- ALWAYS verify webhook signatures using Polar's signature validation +- NEVER trust webhook data without verification +- Implement proper CSRF protection +- Use HTTPS only +- Handle replay attacks with idempotency + +### Data Handling + +- NEVER log sensitive payment data (card numbers, tokens) +- Store only necessary data and tokenize when possible +- Follow Polar's data retention policies +- Implement proper database transactions for payment state + +### Error Handling + +- Implement comprehensive error catching +- Return appropriate HTTP status codes +- Log errors for debugging (sanitized) +- Provide user-friendly error messages +- Never expose internal errors to clients + +### Environment Variables + +- Use POLAR_ACCESS_TOKEN for server-side API calls +- Use NEXT*PUBLIC_POLAR*\* only for client-safe data +- Validate all environment variables at startup +- Never commit secrets to version control + +### Testing + +- Use Polar's sandbox/test mode +- Test all webhook scenarios +- Verify idempotency +- Test error conditions +- Validate signature verification + +## Output Format + +When providing recommendations or code: + +1. **Documentation Sources**: List all documentation URLs and retrieval methods used +2. **Security Analysis**: Detailed security review with risk levels +3. **Implementation**: Complete, production-ready code with comments +4. **Configuration**: Required environment variables and Polar dashboard settings +5. **Testing Plan**: Specific test cases and validation steps +6. **Compliance Notes**: Any regulatory or compliance considerations + +If you cannot find current, authoritative documentation for a specific implementation detail, you MUST: + +1. State explicitly that you need to verify the information +2. Use tools to search for official documentation +3. If documentation cannot be found, recommend that the user consult Polar support +4. NEVER guess or provide unverified implementation details for payment-critical code + +## Red Flags to Reject Immediately + +- Storing raw payment details in application database +- Skipping webhook signature verification +- Using client-side secrets +- Hardcoded API keys or tokens +- Missing error handling in payment flows +- Insufficient logging for debugging payment issues +- Missing idempotency handling +- Using outdated API versions +- Incomplete transaction rollback logic + +You are the guardian of payment security and implementation quality. Be thorough, be strict, and never compromise on best practices. diff --git a/create-agentic-app/template/.claude/agents/ui-developer.md b/create-agentic-app/template/.claude/agents/ui-developer.md new file mode 100644 index 0000000..f71ca1e --- /dev/null +++ b/create-agentic-app/template/.claude/agents/ui-developer.md @@ -0,0 +1,37 @@ +--- +name: ui-developer +description: Use this agent when you need to create, modify, or review React components and UI elements, implement responsive designs, ensure consistent styling patterns across the application, refactor components for better reusability, or when working on any frontend visual elements that require adherence to design systems and UI best practices. Examples: Context: User needs to create a new business listing card component. user: 'I need to create a card component to display business information including name, rating, and location' assistant: 'I'll use the ui-developer agent to create a well-structured, reusable business card component following our design patterns' The user needs UI component creation, so use the ui-developer agent to build a consistent, reusable component with proper Tailwind styling. Context: User wants to improve the styling of an existing form. user: 'The contact form looks inconsistent with the rest of the site and needs better styling' assistant: 'Let me use the ui-developer agent to review and improve the form styling to match our design system' This involves UI consistency and styling improvements, perfect for the ui-developer agent. +model: sonnet +color: blue +--- + +You are an expert UI developer with extensive experience building high-quality, user-friendly interfaces using React, Tailwind CSS, and shadcn/ui components. You specialize in creating consistent, accessible, and maintainable user interfaces for modern web applications. + +Your core responsibilities: + +**Design System Adherence**: Always follow the style guides located in @/docs/ui. Ensure all components and pages maintain visual consistency with established design patterns, spacing, typography, and color schemes throughout the application. + +**Component Architecture**: Build modular, reusable components that follow React best practices. Each component should have a single responsibility, accept appropriate props for customization, and be easily composable with other components. Avoid duplicating UI patterns - instead, create shared components that can be reused across different contexts. + +**Tailwind CSS Mastery**: Use Tailwind utility classes exclusively for styling instead of inline colors or custom CSS. Leverage Tailwind's design tokens for consistent spacing, colors, typography, and responsive behavior. When you need custom colors, use CSS custom properties or extend the Tailwind config rather than hardcoding hex values. + +**shadcn/ui Integration**: Utilize shadcn/ui components as the foundation for complex UI elements. Customize these components appropriately while maintaining their accessibility features and design consistency. Ensure proper integration with the existing component library. + +**Responsive Design**: Implement mobile-first responsive designs using Tailwind's responsive utilities. Ensure all components work seamlessly across different screen sizes and devices. + +**Accessibility Standards**: Build components that meet WCAG guidelines. Include proper ARIA labels, keyboard navigation support, focus management, and semantic HTML structure. + +**Code Quality**: Write clean, well-documented React code with TypeScript support. Use proper component naming conventions, organize props interfaces clearly, and include helpful comments for complex UI logic. + +**Performance Optimization**: Consider performance implications of UI choices. Implement lazy loading where appropriate, optimize re-renders, and ensure efficient component updates. + +When working on UI tasks: + +1. First review existing components to identify reusable patterns +2. Check @/docs/ui for relevant style guidelines +3. Implement using Tailwind utilities and shadcn/ui components +4. Ensure responsive behavior across all breakpoints +5. Test accessibility with keyboard navigation and screen readers +6. Verify consistency with the overall design system + +Always prioritize user experience, maintainability, and consistency in your implementations. If you encounter conflicting design requirements, ask for clarification while suggesting solutions that maintain design system integrity. diff --git a/create-agentic-app/template/.claude/commands/apply-design-system.md b/create-agentic-app/template/.claude/commands/apply-design-system.md new file mode 100644 index 0000000..9ecebad --- /dev/null +++ b/create-agentic-app/template/.claude/commands/apply-design-system.md @@ -0,0 +1,5 @@ +Your role is to ensure that the pages in the project conform to the design system as documented in /docs/ui. +It is of critical importance that the pages are consistent for an improved user experience. + +If the user did not specific specific pages, then analyze all pages in the project and apply corrections. +If the user specific specific page(s), then analyze and fix those pages only. diff --git a/create-agentic-app/template/.claude/commands/checkpoint.md b/create-agentic-app/template/.claude/commands/checkpoint.md new file mode 100644 index 0000000..baecb50 --- /dev/null +++ b/create-agentic-app/template/.claude/commands/checkpoint.md @@ -0,0 +1,2 @@ +Please commit all changes and provide a suitable comment for the commit. +Run git init if git has not been instantiated for the project as yet. diff --git a/create-agentic-app/template/.claude/commands/create-design-system.md b/create-agentic-app/template/.claude/commands/create-design-system.md new file mode 100644 index 0000000..8c42806 --- /dev/null +++ b/create-agentic-app/template/.claude/commands/create-design-system.md @@ -0,0 +1,27 @@ +Your role is to generate a detailed and complete UI design system for the current project. + +This design system should be documented in the /docs/ui folder. Create or update the following files in this folder: + +- COOKBOOK.md +- PRINCIPLES.md +- TOKENS.md +- README.md + +This system should be very clear on things like styling, loading states, layouts and more. + +# Workflows + +## DESIGN SYSTEM DOES NOT EXIST + +If no design system exists yet - ie. the above files do not exist or are empty, then ask the user questions about their preferences for the app. +Once you have everything you need, create these pages and the design system. + +## DESIGN SYSTEM ALREADY EXISTS + +If a design system is already in place - ie. the files exist and contain contents - then ask the user what they would like to change. Update the documents accordingly. + +# IMPORTANT! + +Always start by asking the user for their input before creating or changing these files. + +Keep the questions to a minimum and guide the user along the way. Assume they know nothing about professional design systems. diff --git a/create-agentic-app/template/.claude/commands/document-feature.md b/create-agentic-app/template/.claude/commands/document-feature.md new file mode 100644 index 0000000..667de8d --- /dev/null +++ b/create-agentic-app/template/.claude/commands/document-feature.md @@ -0,0 +1,45 @@ +Update the documents in /docs/features to reflect the latest changes. + +Feature documents should not contain any technical information. + +The following sections should be included: + +# + +## Overview + +## What are / is + +### Core Workflow + +### Key Components + +## Business Value + +### Problem Statement + +### Solution Benefits + +## User Types and Personas + +### Primary Users + +### Secondary Users + +## User Workflows + +### Primary Workflow + +### Alternative Workflows + +## Functional Requirements + +### Supporting Features + +## User Interface Specifications + +## Security Considerations + +## Testing Strategy + +## Success Metrics diff --git a/create-agentic-app/template/.claude/commands/fix-build-issues.md b/create-agentic-app/template/.claude/commands/fix-build-issues.md new file mode 100644 index 0000000..ecf6203 --- /dev/null +++ b/create-agentic-app/template/.claude/commands/fix-build-issues.md @@ -0,0 +1,6 @@ +We are trying to clear out the many lint and typecheck issues in the project. +Please use the lint and typecheck scripts to resolve all issues. +Do not introduce any lint of type issues with your changes. For example, DO NOT use type any! + +For database schema interfaces, I believe drizzle has a built in function for inferring the types. +Think harder. Ensure you don't introduce new type and lint errors with your changes. diff --git a/create-agentic-app/template/.claude/commands/start-dev-server.md b/create-agentic-app/template/.claude/commands/start-dev-server.md new file mode 100644 index 0000000..e94e102 --- /dev/null +++ b/create-agentic-app/template/.claude/commands/start-dev-server.md @@ -0,0 +1,2 @@ +Start the dev server on port 3000. +ALWAYS use port 3000. Use npx kill if the port is in use. diff --git a/create-agentic-app/template/.claude/settings.local.json b/create-agentic-app/template/.claude/settings.local.json new file mode 100644 index 0000000..f7304e9 --- /dev/null +++ b/create-agentic-app/template/.claude/settings.local.json @@ -0,0 +1,23 @@ +{ + "permissions": { + "allow": [ + "mcp__context7__resolve-library-id", + "mcp__context7__get-library-docs", + "Bash(npm run lint)", + "Bash(npm run typecheck:*)", + "mcp__playwright__browser_navigate", + "mcp__playwright__browser_click", + "mcp__playwright__browser_take_screenshot", + "mcp__playwright__browser_close", + "Bash(git add:*)", + "Bash(git log:*)" + ], + "additionalDirectories": [ + "C:\\c\\Projects\\nextjs-better-auth-postgresql-starter-kit" + ] + }, + "enableAllProjectMcpServers": true, + "enabledMcpjsonServers": [ + "context7" + ] +} \ No newline at end of file diff --git a/create-agentic-app/template/.cursor/rules/project-rules.mdc b/create-agentic-app/template/.cursor/rules/project-rules.mdc new file mode 100644 index 0000000..7b8ca7a --- /dev/null +++ b/create-agentic-app/template/.cursor/rules/project-rules.mdc @@ -0,0 +1,6 @@ +--- +alwaysApply: true +--- + +- Always run the LINT and TYPESCHECK scripts after completing your changes. This is to check for any issues. +- NEVER start the dev server yourself. If you need something from the terminal, ask the user to provide it to you. diff --git a/create-agentic-app/template/.mcp.json b/create-agentic-app/template/.mcp.json new file mode 100644 index 0000000..9d30c31 --- /dev/null +++ b/create-agentic-app/template/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "shadcn": { + "command": "npx", + "args": ["shadcn@latest", "mcp"] + } + } +} diff --git a/create-agentic-app/template/.playwright-mcp/dark-mode-homepage.png b/create-agentic-app/template/.playwright-mcp/dark-mode-homepage.png new file mode 100644 index 0000000..a696de7 Binary files /dev/null and b/create-agentic-app/template/.playwright-mcp/dark-mode-homepage.png differ diff --git a/create-agentic-app/template/.playwright-mcp/light-mode-homepage.png b/create-agentic-app/template/.playwright-mcp/light-mode-homepage.png new file mode 100644 index 0000000..86f619f Binary files /dev/null and b/create-agentic-app/template/.playwright-mcp/light-mode-homepage.png differ diff --git a/create-agentic-app/template/.vscode/settings.json b/create-agentic-app/template/.vscode/settings.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/create-agentic-app/template/.vscode/settings.json @@ -0,0 +1 @@ +{} diff --git a/create-agentic-app/template/CLAUDE.md b/create-agentic-app/template/CLAUDE.md new file mode 100644 index 0000000..7e01793 --- /dev/null +++ b/create-agentic-app/template/CLAUDE.md @@ -0,0 +1,3 @@ +- Always run the LINT and TYPESCHECK scripts after completing your changes. This is to check for any issues. +- NEVER start the dev server yourself. If you need something from the terminal, ask the user to provide it to you. +- Avoid using custom colors unless very specifically instructed to do so. Stick to standard tailwind and shadcn colors, styles and tokens. diff --git a/create-agentic-app/template/README.md b/create-agentic-app/template/README.md new file mode 100644 index 0000000..c30dc18 --- /dev/null +++ b/create-agentic-app/template/README.md @@ -0,0 +1,234 @@ +# Agentic Coding Boilerplate + +A complete agentic coding boilerplate with authentication, PostgreSQL database, AI chat functionality, and modern UI components - perfect for building AI-powered applications and autonomous agents. + +## šŸš€ Features + +- **šŸ” Authentication**: Better Auth with Google OAuth integration +- **šŸ—ƒļø Database**: Drizzle ORM with PostgreSQL +- **šŸ¤– AI Integration**: Vercel AI SDK with OpenAI support +- **šŸŽØ UI Components**: shadcn/ui with Tailwind CSS +- **āš” Modern Stack**: Next.js 15, React 19, TypeScript +- **šŸ“± Responsive**: Mobile-first design approach + +## šŸŽ„ Video Tutorial + +Watch the complete walkthrough of this agentic coding template: + +[![Agentic Coding Boilerplate Tutorial](https://img.youtube.com/vi/T0zFZsr_d0Q/maxresdefault.jpg)](https://youtu.be/T0zFZsr_d0Q) + +šŸ”— Watch on YouTube + +## ā˜• Support This Project + +If this boilerplate helped you build something awesome, consider buying me a coffee! + +[![Buy me a coffee](https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/leonvanzyl) + +## šŸ“‹ Prerequisites + +Before you begin, ensure you have the following installed on your machine: + +- **Node.js**: Version 18.0 or higher (Download here) +- **Git**: For cloning the repository (Download here) +- **PostgreSQL**: Either locally installed or access to a hosted service like Vercel Postgres + +## šŸ› ļø Quick Setup + +### 1. Clone or Download the Repository + +**Option A: Clone with Git** + +```bash +git clone https://github.com/leonvanzyl/agentic-coding-starter-kit.git +cd agentic-coding-starter-kit +``` + +**Option B: Download ZIP** +Download the repository as a ZIP file and extract it to your desired location. + +### 2. Install Dependencies + +```bash +npm install +``` + +### 3. Environment Setup + +Copy the example environment file: + +```bash +cp env.example .env +``` + +Fill in your environment variables in the `.env` file: + +```env +# Database +POSTGRES_URL="postgresql://username:password@localhost:5432/your_database_name" + +# Authentication - Better Auth +BETTER_AUTH_SECRET="your-random-32-character-secret-key-here" + +# Google OAuth (Get from Google Cloud Console) +GOOGLE_CLIENT_ID="your-google-client-id" +GOOGLE_CLIENT_SECRET="your-google-client-secret" + +# AI Integration (Optional - for chat functionality) +OPENAI_API_KEY="sk-your-openai-api-key-here" +OPENAI_MODEL="gpt-5-mini" + +# App URL (for production deployments) +NEXT_PUBLIC_APP_URL="http://localhost:3000" +``` + +### 4. Database Setup + +Generate and run database migrations: + +```bash +npm run db:generate +npm run db:migrate +``` + +### 5. Start the Development Server + +```bash +npm run dev +``` + +Your application will be available at [http://localhost:3000](http://localhost:3000) + +## āš™ļø Service Configuration + +### PostgreSQL Database on Vercel + +1. Go to Vercel Dashboard +2. Navigate to the **Storage** tab +3. Click **Create** ā†’ **Postgres** +4. Choose your database name and region +5. Copy the `POSTGRES_URL` from the `.env.local` tab +6. Add it to your `.env` file + +### Google OAuth Credentials + +1. Go to Google Cloud Console +2. Create a new project or select an existing one +3. Navigate to **Credentials** ā†’ **Create Credentials** ā†’ **OAuth 2.0 Client ID** +4. Set application type to **Web application** +5. Add authorized redirect URIs: + - `http://localhost:3000/api/auth/callback/google` (development) + - `https://yourdomain.com/api/auth/callback/google` (production) +6. Copy the **Client ID** and **Client Secret** to your `.env` file + +### OpenAI API Key + +1. Go to OpenAI Platform +2. Navigate to **API Keys** in the sidebar +3. Click **Create new secret key** +4. Give it a name and copy the key +5. Add it to your `.env` file as `OPENAI_API_KEY` + +## šŸ—‚ļø Project Structure + +``` +src/ +ā”œā”€ā”€ app/ # Next.js app directory +ā”‚ ā”œā”€ā”€ api/ # API routes +ā”‚ ā”‚ ā”œā”€ā”€ auth/ # Authentication endpoints +ā”‚ ā”‚ ā””ā”€ā”€ chat/ # AI chat endpoint +ā”‚ ā”œā”€ā”€ chat/ # AI chat page +ā”‚ ā”œā”€ā”€ dashboard/ # User dashboard +ā”‚ ā””ā”€ā”€ page.tsx # Home page +ā”œā”€ā”€ components/ # React components +ā”‚ ā”œā”€ā”€ auth/ # Authentication components +ā”‚ ā””ā”€ā”€ ui/ # shadcn/ui components +ā””ā”€ā”€ lib/ # Utilities and configurations + ā”œā”€ā”€ auth.ts # Better Auth configuration + ā”œā”€ā”€ auth-client.ts # Client-side auth utilities + ā”œā”€ā”€ db.ts # Database connection + ā”œā”€ā”€ schema.ts # Database schema + ā””ā”€ā”€ utils.ts # General utilities +``` + +## šŸ”§ Available Scripts + +```bash +npm run dev # Start development server with Turbopack +npm run build # Build for production +npm run start # Start production server +npm run lint # Run ESLint +npm run db:generate # Generate database migrations +npm run db:migrate # Run database migrations +npm run db:push # Push schema changes to database +npm run db:studio # Open Drizzle Studio (database GUI) +npm run db:dev # Push schema for development +npm run db:reset # Reset database (drop all tables) +``` + +## šŸ“– Pages Overview + +- **Home (`/`)**: Landing page with setup instructions and features overview +- **Dashboard (`/dashboard`)**: Protected user dashboard with profile information +- **Chat (`/chat`)**: AI-powered chat interface using OpenAI (requires authentication) + +## šŸš€ Deployment + +### Deploy to Vercel (Recommended) + +1. Install the Vercel CLI globally: + + ```bash + npm install -g vercel + ``` + +2. Deploy your application: + + ```bash + vercel --prod + ``` + +3. Follow the prompts to configure your deployment +4. Add your environment variables when prompted or via the Vercel dashboard + +### Production Environment Variables + +Ensure these are set in your production environment: + +- `POSTGRES_URL` - Production PostgreSQL connection string +- `BETTER_AUTH_SECRET` - Secure random 32+ character string +- `GOOGLE_CLIENT_ID` - Google OAuth Client ID +- `GOOGLE_CLIENT_SECRET` - Google OAuth Client Secret +- `OPENAI_API_KEY` - OpenAI API key (optional) +- `OPENAI_MODEL` - OpenAI model name (optional, defaults to gpt-5-mini) +- `NEXT_PUBLIC_APP_URL` - Your production domain + +## šŸŽ„ Tutorial Video + +Watch my comprehensive tutorial on how to use this agentic coding boilerplate to build AI-powered applications: + +šŸ“ŗ YouTube Tutorial - Building with Agentic Coding Boilerplate + +## šŸ¤ Contributing + +1. Fork this repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +## šŸ“ License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## šŸ†˜ Need Help? + +If you encounter any issues: + +1. Check the [Issues](https://github.com/leonvanzyl/agentic-coding-starter-kit/issues) section +2. Review the documentation above +3. Create a new issue with detailed information about your problem + +--- + +**Happy coding! šŸš€** diff --git a/create-agentic-app/template/components.json b/create-agentic-app/template/components.json new file mode 100644 index 0000000..ffe928f --- /dev/null +++ b/create-agentic-app/template/components.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://ui.shadcn.com/schema.json", + "style": "new-york", + "rsc": true, + "tsx": true, + "tailwind": { + "config": "", + "css": "src/app/globals.css", + "baseColor": "neutral", + "cssVariables": true, + "prefix": "" + }, + "aliases": { + "components": "@/components", + "utils": "@/lib/utils", + "ui": "@/components/ui", + "lib": "@/lib", + "hooks": "@/hooks" + }, + "iconLibrary": "lucide" +} \ No newline at end of file diff --git a/create-agentic-app/template/docker-compose.yml b/create-agentic-app/template/docker-compose.yml new file mode 100644 index 0000000..09733e9 --- /dev/null +++ b/create-agentic-app/template/docker-compose.yml @@ -0,0 +1,12 @@ +version: "3.8" + +services: + postgres: + image: pgvector/pgvector:pg18 + container_name: postgres + environment: + POSTGRES_DB: postgres_dev + POSTGRES_USER: dev_user + POSTGRES_PASSWORD: dev_password + ports: + - "5432:5432" diff --git a/create-agentic-app/template/docs/business/starter-prompt.md b/create-agentic-app/template/docs/business/starter-prompt.md new file mode 100644 index 0000000..86de00a --- /dev/null +++ b/create-agentic-app/template/docs/business/starter-prompt.md @@ -0,0 +1,94 @@ +I'm working with an agentic coding boilerplate project that includes authentication, database integration, and AI capabilities. Here's what's already set up: + +## Current Agentic Coding Boilerplate Structure + +- **Authentication**: Better Auth with Google OAuth integration +- **Database**: Drizzle ORM with PostgreSQL setup +- **AI Integration**: Vercel AI SDK with OpenAI integration +- **UI**: shadcn/ui components with Tailwind CSS +- **Current Routes**: + - `/` - Home page with setup instructions and feature overview + - `/dashboard` - Protected dashboard page (requires authentication) + - `/chat` - AI chat interface (requires OpenAI API key) + +## Important Context + +This is an **agentic coding boilerplate/starter template** - all existing pages and components are meant to be examples and should be **completely replaced** to build the actual AI-powered application. + +### CRITICAL: You MUST Override All Boilerplate Content + +**DO NOT keep any boilerplate components, text, or UI elements unless explicitly requested.** This includes: + +- **Remove all placeholder/demo content** (setup checklists, welcome messages, boilerplate text) +- **Replace the entire navigation structure** - don't keep the existing site header or nav items +- **Override all page content completely** - don't append to existing pages, replace them entirely +- **Remove or replace all example components** (setup-checklist, starter-prompt-modal, etc.) +- **Replace placeholder routes and pages** with the actual application functionality + +### Required Actions: + +1. **Start Fresh**: Treat existing components as temporary scaffolding to be removed +2. **Complete Replacement**: Build the new application from scratch using the existing tech stack +3. **No Hybrid Approach**: Don't try to integrate new features alongside existing boilerplate content +4. **Clean Slate**: The final application should have NO trace of the original boilerplate UI or content + +The only things to preserve are: + +- **All installed libraries and dependencies** (DO NOT uninstall or remove any packages from package.json) +- **Authentication system** (but customize the UI/flow as needed) +- **Database setup and schema** (but modify schema as needed for your use case) +- **Core configuration files** (next.config.ts, tsconfig.json, tailwind.config.ts, etc.) +- **Build and development scripts** (keep all npm/pnpm scripts in package.json) + +## Tech Stack + +- Next.js 15 with App Router +- TypeScript +- Tailwind CSS +- Better Auth for authentication +- Drizzle ORM + PostgreSQL +- Vercel AI SDK +- shadcn/ui components +- Lucide React icons + +## Component Development Guidelines + +**Always prioritize shadcn/ui components** when building the application: + +1. **First Choice**: Use existing shadcn/ui components from the project +2. **Second Choice**: Install additional shadcn/ui components using `pnpm dlx shadcn@latest add ` +3. **Last Resort**: Only create custom components or use other libraries if shadcn/ui doesn't provide a suitable option + +The project already includes several shadcn/ui components (button, dialog, avatar, etc.) and follows their design system. Always check the [shadcn/ui documentation](https://ui.shadcn.com/docs/components) for available components before implementing alternatives. + +## What I Want to Build + +Basic todo list app with the ability for users to add, remove, update, complete and view todos. + +## Request + +Please help me transform this boilerplate into my actual application. **You MUST completely replace all existing boilerplate code** to match my project requirements. The current implementation is just temporary scaffolding that should be entirely removed and replaced. + +## Final Reminder: COMPLETE REPLACEMENT REQUIRED + +šŸšØ **IMPORTANT**: Do not preserve any of the existing boilerplate UI, components, or content. The user expects a completely fresh application that implements their requirements from scratch. Any remnants of the original boilerplate (like setup checklists, welcome screens, demo content, or placeholder navigation) indicate incomplete implementation. + +**Success Criteria**: The final application should look and function as if it was built from scratch for the specific use case, with no evidence of the original boilerplate template. + +## Post-Implementation Documentation + +After completing the implementation, you MUST document any new features or significant changes in the `/docs/features/` directory: + +1. **Create Feature Documentation**: For each major feature implemented, create a markdown file in `/docs/features/` that explains: + + - What the feature does + - How it works + - Key components and files involved + - Usage examples + - Any configuration or setup required + +2. **Update Existing Documentation**: If you modify existing functionality, update the relevant documentation files to reflect the changes. + +3. **Document Design Decisions**: Include any important architectural or design decisions made during implementation. + +This documentation helps maintain the project and assists future developers working with the codebase. diff --git a/create-agentic-app/template/docs/technical/ai/streaming.md b/create-agentic-app/template/docs/technical/ai/streaming.md new file mode 100644 index 0000000..89af7d1 --- /dev/null +++ b/create-agentic-app/template/docs/technical/ai/streaming.md @@ -0,0 +1,503 @@ +# Next.js App Router Quickstart + +The AI SDK is a powerful Typescript library designed to help developers build AI-powered applications. + +In this quickstart tutorial, you'll build a simple AI-chatbot with a streaming user interface. Along the way, you'll learn key concepts and techniques that are fundamental to using the SDK in your own projects. + +If you are unfamiliar with the concepts of [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/advanced/why-streaming), you can optionally read these documents first. + +## Prerequisites + +To follow this quickstart, you'll need: + +- Node.js 18+ and pnpm installed on your local development machine. +- An OpenAI API key. + +If you haven't obtained your OpenAI API key, you can do so by [signing up](https://platform.openai.com/signup/) on the OpenAI website. + +## Create Your Application + +Start by creating a new Next.js application. This command will create a new directory named `my-ai-app` and set up a basic Next.js application inside it. + +
+ + Be sure to select yes when prompted to use the App Router and Tailwind CSS. + If you are looking for the Next.js Pages Router quickstart guide, you can + find it [here](/docs/getting-started/nextjs-pages-router). + +
+ + + +Navigate to the newly created directory: + + + +### Install dependencies + +Install `ai`, `@ai-sdk/react`, and `@ai-sdk/openai`, the AI package, AI SDK's React hooks, and AI SDK's [ OpenAI provider ](/providers/ai-sdk-providers/openai) respectively. + + + The AI SDK is designed to be a unified interface to interact with any large + language model. This means that you can change model and providers with just + one line of code! Learn more about [available providers](/providers) and + [building custom providers](/providers/community-providers/custom-providers) + in the [providers](/providers) section. + +
+ + + + + + + + + + + + + + + + +
+ +### Configure OpenAI API key + +Create a `.env.local` file in your project root and add your OpenAI API Key. This key is used to authenticate your application with the OpenAI service. + + + +Edit the `.env.local` file: + +```env filename=".env.local" +OPENAI_API_KEY=xxxxxxxxx +``` + +Replace `xxxxxxxxx` with your actual OpenAI API key. + + + The AI SDK's OpenAI Provider will default to using the `OPENAI_API_KEY` + environment variable. + + +## Create a Route Handler + +Create a route handler, `app/api/chat/route.ts` and add the following code: + +```tsx filename="app/api/chat/route.ts" +import { openai } from "@ai-sdk/openai"; +import { streamText, UIMessage, convertToModelMessages } from "ai"; + +// Allow streaming responses up to 30 seconds +export const maxDuration = 30; + +export async function POST(req: Request) { + const { messages }: { messages: UIMessage[] } = await req.json(); + + const result = streamText({ + model: openai(process.env.OPENAI_MODEL || "gpt-5-mini"), + messages: convertToModelMessages(messages), + }); + + return result.toUIMessageStreamResponse(); +} +``` + +Let's take a look at what is happening in this code: + +1. Define an asynchronous `POST` request handler and extract `messages` from the body of the request. The `messages` variable contains a history of the conversation between you and the chatbot and provides the chatbot with the necessary context to make the next generation. The `messages` are of UIMessage type, which are designed for use in application UI - they contain the entire message history and associated metadata like timestamps. +2. Call [`streamText`](/docs/reference/ai-sdk-core/stream-text), which is imported from the `ai` package. This function accepts a configuration object that contains a `model` provider (imported from `@ai-sdk/openai`) and `messages` (defined in step 1). You can pass additional [settings](/docs/ai-sdk-core/settings) to further customise the model's behaviour. The `messages` key expects a `ModelMessage[]` array. This type is different from `UIMessage` in that it does not include metadata, such as timestamps or sender information. To convert between these types, we use the `convertToModelMessages` function, which strips the UI-specific metadata and transforms the `UIMessage[]` array into the `ModelMessage[]` format that the model expects. +3. The `streamText` function returns a [`StreamTextResult`](/docs/reference/ai-sdk-core/stream-text#result-object). This result object contains the [ `toUIMessageStreamResponse` ](/docs/reference/ai-sdk-core/stream-text#to-data-stream-response) function which converts the result to a streamed response object. +4. Finally, return the result to the client to stream the response. + +This Route Handler creates a POST request endpoint at `/api/chat`. + +## Wire up the UI + +Now that you have a Route Handler that can query an LLM, it's time to setup your frontend. The AI SDK's [ UI ](/docs/ai-sdk-ui) package abstracts the complexity of a chat interface into one hook, [`useChat`](/docs/reference/ai-sdk-ui/use-chat). + +Update your root page (`app/page.tsx`) with the following code to show a list of chat messages and provide a user message input: + +```tsx filename="app/page.tsx" +"use client"; + +import { useChat } from "@ai-sdk/react"; +import { useState } from "react"; + +export default function Chat() { + const [input, setInput] = useState(""); + const { messages, sendMessage } = useChat(); + return ( +
+ {messages.map((message) => ( +
+ {message.role === "user" ? "User: " : "AI: "} + {message.parts.map((part, i) => { + switch (part.type) { + case "text": + return
{part.text}
; + } + })} +
+ ))} + +
{ + e.preventDefault(); + sendMessage({ text: input }); + setInput(""); + }} + > + setInput(e.currentTarget.value)} + /> +
+
+ ); +} +``` + + + Make sure you add the `"use client"` directive to the top of your file. This + allows you to add interactivity with Javascript. + + +This page utilizes the `useChat` hook, which will, by default, use the `POST` API route you created earlier (`/api/chat`). The hook provides functions and state for handling user input and form submission. The `useChat` hook provides multiple utility functions and state variables: + +- `messages` - the current chat messages (an array of objects with `id`, `role`, and `parts` properties). +- `sendMessage` - a function to send a message to the chat API. + +The component uses local state (`useState`) to manage the input field value, and handles form submission by calling `sendMessage` with the input text and then clearing the input field. + +The LLM's response is accessed through the message `parts` array. Each message contains an ordered array of `parts` that represents everything the model generated in its response. These parts can include plain text, reasoning tokens, and more that you will see later. The `parts` array preserves the sequence of the model's outputs, allowing you to display or process each component in the order it was generated. + +## Running Your Application + +With that, you have built everything you need for your chatbot! To start your application, use the command: + + + +Head to your browser and open http://localhost:3000. You should see an input field. Test it out by entering a message and see the AI chatbot respond in real-time! The AI SDK makes it fast and easy to build AI chat interfaces with Next.js. + +## Enhance Your Chatbot with Tools + +While large language models (LLMs) have incredible generation capabilities, they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). This is where [tools](/docs/ai-sdk-core/tools-and-tool-calling) come in. + +Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered in the next response. + +For example, if a user asks about the current weather, without tools, the model would only be able to provide general information based on its training data. But with a weather tool, it can fetch and provide up-to-date, location-specific weather information. + +Let's enhance your chatbot by adding a simple weather tool. + +### Update Your Route Handler + +Modify your `app/api/chat/route.ts` file to include the new weather tool: + +```tsx filename="app/api/chat/route.ts" highlight="2,13-27" +import { openai } from "@ai-sdk/openai"; +import { streamText, UIMessage, convertToModelMessages, tool } from "ai"; +import { z } from "zod"; + +export const maxDuration = 30; + +export async function POST(req: Request) { + const { messages }: { messages: UIMessage[] } = await req.json(); + + const result = streamText({ + model: openai(process.env.OPENAI_MODEL || "gpt-5-mini"), + messages: convertToModelMessages(messages), + tools: { + weather: tool({ + description: "Get the weather in a location (fahrenheit)", + inputSchema: z.object({ + location: z.string().describe("The location to get the weather for"), + }), + execute: async ({ location }) => { + const temperature = Math.round(Math.random() * (90 - 32) + 32); + return { + location, + temperature, + }; + }, + }), + }, + }); + + return result.toUIMessageStreamResponse(); +} +``` + +In this updated code: + +1. You import the `tool` function from the `ai` package and `z` from `zod` for schema validation. +2. You define a `tools` object with a `weather` tool. This tool: + + - Has a description that helps the model understand when to use it. + - Defines `inputSchema` using a Zod schema, specifying that it requires a `location` string to execute this tool. The model will attempt to extract this input from the context of the conversation. If it can't, it will ask the user for the missing information. + - Defines an `execute` function that simulates getting weather data (in this case, it returns a random temperature). This is an asynchronous function running on the server so you can fetch real data from an external API. + +Now your chatbot can "fetch" weather information for any location the user asks about. When the model determines it needs to use the weather tool, it will generate a tool call with the necessary input. The `execute` function will then be automatically run, and the tool output will be added to the `messages` as a `tool` message. + +Try asking something like "What's the weather in New York?" and see how the model uses the new tool. + +Notice the blank response in the UI? This is because instead of generating a text response, the model generated a tool call. You can access the tool call and subsequent tool result on the client via the `tool-weather` part of the `message.parts` array. + + + Tool parts are always named `tool-{toolName}`, where `{toolName}` is the key + you used when defining the tool. In this case, since we defined the tool as + `weather`, the part type is `tool-weather`. + + +### Update the UI + +To display the tool invocation in your UI, update your `app/page.tsx` file: + +```tsx filename="app/page.tsx" highlight="16-21" +"use client"; + +import { useChat } from "@ai-sdk/react"; +import { useState } from "react"; + +export default function Chat() { + const [input, setInput] = useState(""); + const { messages, sendMessage } = useChat(); + return ( +
+ {messages.map((message) => ( +
+ {message.role === "user" ? "User: " : "AI: "} + {message.parts.map((part, i) => { + switch (part.type) { + case "text": + return
{part.text}
; + case "tool-weather": + return ( + 
+                    {JSON.stringify(part, null, 2)}
+
+ ); + } + })} +
+ ))} + +
{ + e.preventDefault(); + sendMessage({ text: input }); + setInput(""); + }} + > + setInput(e.currentTarget.value)} + /> +
+
+ ); +} +``` + +With this change, you're updating the UI to handle different message parts. For text parts, you display the text content as before. For weather tool invocations, you display a JSON representation of the tool call and its result. + +Now, when you ask about the weather, you'll see the tool call and its result displayed in your chat interface. + +## Enabling Multi-Step Tool Calls + +You may have noticed that while the tool is now visible in the chat interface, the model isn't using this information to answer your original query. This is because once the model generates a tool call, it has technically completed its generation. + +To solve this, you can enable multi-step tool calls using `stopWhen`. By default, `stopWhen` is set to `stepCountIs(1)`, which means generation stops after the first step when there are tool results. By changing this condition, you can allow the model to automatically send tool results back to itself to trigger additional generations until your specified stopping condition is met. In this case, you want the model to continue generating so it can use the weather tool results to answer your original question. + +### Update Your Route Handler + +Modify your `app/api/chat/route.ts` file to include the `stopWhen` condition: + +```tsx filename="app/api/chat/route.ts" +import { openai } from "@ai-sdk/openai"; +import { + streamText, + UIMessage, + convertToModelMessages, + tool, + stepCountIs, +} from "ai"; +import { z } from "zod"; + +export const maxDuration = 30; + +export async function POST(req: Request) { + const { messages }: { messages: UIMessage[] } = await req.json(); + + const result = streamText({ + model: openai(process.env.OPENAI_MODEL || "gpt-5-mini"), + messages: convertToModelMessages(messages), + stopWhen: stepCountIs(5), + tools: { + weather: tool({ + description: "Get the weather in a location (fahrenheit)", + inputSchema: z.object({ + location: z.string().describe("The location to get the weather for"), + }), + execute: async ({ location }) => { + const temperature = Math.round(Math.random() * (90 - 32) + 32); + return { + location, + temperature, + }; + }, + }), + }, + }); + + return result.toUIMessageStreamResponse(); +} +``` + +In this updated code: + +1. You set `stopWhen` to be when `stepCountIs` 5, allowing the model to use up to 5 "steps" for any given generation. +2. You add an `onStepFinish` callback to log any `toolResults` from each step of the interaction, helping you understand the model's tool usage. This means we can also delete the `toolCall` and `toolResult` `console.log` statements from the previous example. + +Head back to the browser and ask about the weather in a location. You should now see the model using the weather tool results to answer your question. + +By setting `stopWhen: stepCountIs(5)`, you're allowing the model to use up to 5 "steps" for any given generation. This enables more complex interactions and allows the model to gather and process information over several steps if needed. You can see this in action by adding another tool to convert the temperature from Celsius to Fahrenheit. + +### Add another tool + +Update your `app/api/chat/route.ts` file to add a new tool to convert the temperature from Fahrenheit to Celsius: + +```tsx filename="app/api/chat/route.ts" highlight="34-47" +import { openai } from "@ai-sdk/openai"; +import { + streamText, + UIMessage, + convertToModelMessages, + tool, + stepCountIs, +} from "ai"; +import { z } from "zod"; + +export const maxDuration = 30; + +export async function POST(req: Request) { + const { messages }: { messages: UIMessage[] } = await req.json(); + + const result = streamText({ + model: openai(process.env.OPENAI_MODEL || "gpt-5-mini"), + messages: convertToModelMessages(messages), + stopWhen: stepCountIs(5), + tools: { + weather: tool({ + description: "Get the weather in a location (fahrenheit)", + inputSchema: z.object({ + location: z.string().describe("The location to get the weather for"), + }), + execute: async ({ location }) => { + const temperature = Math.round(Math.random() * (90 - 32) + 32); + return { + location, + temperature, + }; + }, + }), + convertFahrenheitToCelsius: tool({ + description: "Convert a temperature in fahrenheit to celsius", + inputSchema: z.object({ + temperature: z + .number() + .describe("The temperature in fahrenheit to convert"), + }), + execute: async ({ temperature }) => { + const celsius = Math.round((temperature - 32) * (5 / 9)); + return { + celsius, + }; + }, + }), + }, + }); + + return result.toUIMessageStreamResponse(); +} +``` + +### Update Your Frontend + +update your `app/page.tsx` file to render the new temperature conversion tool: + +```tsx filename="app/page.tsx" highlight="21" +"use client"; + +import { useChat } from "@ai-sdk/react"; +import { useState } from "react"; + +export default function Chat() { + const [input, setInput] = useState(""); + const { messages, sendMessage } = useChat(); + return ( +
+ {messages.map((message) => ( +
+ {message.role === "user" ? "User: " : "AI: "} + {message.parts.map((part, i) => { + switch (part.type) { + case "text": + return
{part.text}
; + case "tool-weather": + case "tool-convertFahrenheitToCelsius": + return ( + 
+                    {JSON.stringify(part, null, 2)}
+
+ ); + } + })} +
+ ))} + +
{ + e.preventDefault(); + sendMessage({ text: input }); + setInput(""); + }} + > + setInput(e.currentTarget.value)} + /> +
+
+ ); +} +``` + +This update handles the new `tool-convertFahrenheitToCelsius` part type, displaying the temperature conversion tool calls and results in the UI. + +Now, when you ask "What's the weather in New York in celsius?", you should see a more complete interaction: + +1. The model will call the weather tool for New York. +2. You'll see the tool output displayed. +3. It will then call the temperature conversion tool to convert the temperature from Fahrenheit to Celsius. +4. The model will then use that information to provide a natural language response about the weather in New York. + +This multi-step approach allows the model to gather information and use it to provide more accurate and contextual responses, making your chatbot considerably more useful. + +This simple example demonstrates how tools can expand your model's capabilities. You can create more complex tools to integrate with real APIs, databases, or any other external systems, allowing the model to access and process real-world data in real-time. Tools bridge the gap between the model's knowledge cutoff and current information. + +## Where to Next? + +You've built an AI chatbot using the AI SDK! From here, you have several paths to explore: + +- To learn more about the AI SDK, read through the [documentation](/docs). +- If you're interested in diving deeper with guides, check out the [RAG (retrieval-augmented generation)](/docs/guides/rag-chatbot) and [multi-modal chatbot](/docs/guides/multi-modal-chatbot) guides. +- To jumpstart your first AI project, explore available [templates](https://vercel.com/templates?type=ai). diff --git a/create-agentic-app/template/docs/technical/ai/structured-data.md b/create-agentic-app/template/docs/technical/ai/structured-data.md new file mode 100644 index 0000000..12711b1 --- /dev/null +++ b/create-agentic-app/template/docs/technical/ai/structured-data.md @@ -0,0 +1,409 @@ +# Generating Structured Data + +While text generation can be useful, your use case will likely call for generating structured data. +For example, you might want to extract information from text, classify data, or generate synthetic data. + +Many language models are capable of generating structured data, often defined as using "JSON modes" or "tools". +However, you need to manually provide schemas and then validate the generated data as LLMs can produce incorrect or incomplete structured data. + +The AI SDK standardises structured object generation across model providers +with the [`generateObject`](/docs/reference/ai-sdk-core/generate-object) +and [`streamObject`](/docs/reference/ai-sdk-core/stream-object) functions. +You can use both functions with different output strategies, e.g. `array`, `object`, `enum`, or `no-schema`, +and with different generation modes, e.g. `auto`, `tool`, or `json`. +You can use [Zod schemas](/docs/reference/ai-sdk-core/zod-schema), [Valibot](/docs/reference/ai-sdk-core/valibot-schema), or [JSON schemas](/docs/reference/ai-sdk-core/json-schema) to specify the shape of the data that you want, +and the AI model will generate data that conforms to that structure. + + + You can pass Zod objects directly to the AI SDK functions or use the + `zodSchema` helper function. + + +## Generate Object + +The `generateObject` generates structured data from a prompt. +The schema is also used to validate the generated data, ensuring type safety and correctness. + +```ts +import { generateObject } from "ai"; +import { z } from "zod"; + +const { object } = await generateObject({ + model: "openai/gpt-4.1", + schema: z.object({ + recipe: z.object({ + name: z.string(), + ingredients: z.array(z.object({ name: z.string(), amount: z.string() })), + steps: z.array(z.string()), + }), + }), + prompt: "Generate a lasagna recipe.", +}); +``` + + + See `generateObject` in action with [these examples](#more-examples) + + +### Accessing response headers & body + +Sometimes you need access to the full response from the model provider, +e.g. to access some provider-specific headers or body content. + +You can access the raw response headers and body using the `response` property: + +```ts +import { generateObject } from "ai"; + +const result = await generateObject({ + // ... +}); + +console.log(JSON.stringify(result.response.headers, null, 2)); +console.log(JSON.stringify(result.response.body, null, 2)); +``` + +## Stream Object + +Given the added complexity of returning structured data, model response time can be unacceptable for your interactive use case. +With the [`streamObject`](/docs/reference/ai-sdk-core/stream-object) function, you can stream the model's response as it is generated. + +```ts +import { streamObject } from "ai"; + +const { partialObjectStream } = streamObject({ + // ... +}); + +// use partialObjectStream as an async iterable +for await (const partialObject of partialObjectStream) { + console.log(partialObject); +} +``` + +You can use `streamObject` to stream generated UIs in combination with React Server Components (see [Generative UI](../ai-sdk-rsc))) or the [`useObject`](/docs/reference/ai-sdk-ui/use-object) hook. + +See `streamObject` in action with [these examples](#more-examples) + +### `onError` callback + +`streamObject` immediately starts streaming. +Errors become part of the stream and are not thrown to prevent e.g. servers from crashing. + +To log errors, you can provide an `onError` callback that is triggered when an error occurs. + +```tsx highlight="5-7" +import { streamObject } from "ai"; + +const result = streamObject({ + // ... + onError({ error }) { + console.error(error); // your error logging logic here + }, +}); +``` + +## Output Strategy + +You can use both functions with different output strategies, e.g. `array`, `object`, `enum`, or `no-schema`. + +### Object + +The default output strategy is `object`, which returns the generated data as an object. +You don't need to specify the output strategy if you want to use the default. + +### Array + +If you want to generate an array of objects, you can set the output strategy to `array`. +When you use the `array` output strategy, the schema specifies the shape of an array element. +With `streamObject`, you can also stream the generated array elements using `elementStream`. + +```ts highlight="7,18" +import { openai } from "@ai-sdk/openai"; +import { streamObject } from "ai"; +import { z } from "zod"; + +const { elementStream } = streamObject({ + model: openai("gpt-4.1"), + output: "array", + schema: z.object({ + name: z.string(), + class: z + .string() + .describe("Character class, e.g. warrior, mage, or thief."), + description: z.string(), + }), + prompt: "Generate 3 hero descriptions for a fantasy role playing game.", +}); + +for await (const hero of elementStream) { + console.log(hero); +} +``` + +### Enum + +If you want to generate a specific enum value, e.g. for classification tasks, +you can set the output strategy to `enum` +and provide a list of possible values in the `enum` parameter. + +Enum output is only available with `generateObject`. + +```ts highlight="5-6" +import { generateObject } from "ai"; + +const { object } = await generateObject({ + model: "openai/gpt-4.1", + output: "enum", + enum: ["action", "comedy", "drama", "horror", "sci-fi"], + prompt: + "Classify the genre of this movie plot: " + + '"A group of astronauts travel through a wormhole in search of a ' + + 'new habitable planet for humanity."', +}); +``` + +### No Schema + +In some cases, you might not want to use a schema, +for example when the data is a dynamic user request. +You can use the `output` setting to set the output format to `no-schema` in those cases +and omit the schema parameter. + +```ts highlight="6" +import { openai } from "@ai-sdk/openai"; +import { generateObject } from "ai"; + +const { object } = await generateObject({ + model: openai("gpt-4.1"), + output: "no-schema", + prompt: "Generate a lasagna recipe.", +}); +``` + +## Schema Name and Description + +You can optionally specify a name and description for the schema. These are used by some providers for additional LLM guidance, e.g. via tool or schema name. + +```ts highlight="6-7" +import { generateObject } from "ai"; +import { z } from "zod"; + +const { object } = await generateObject({ + model: "openai/gpt-4.1", + schemaName: "Recipe", + schemaDescription: "A recipe for a dish.", + schema: z.object({ + name: z.string(), + ingredients: z.array(z.object({ name: z.string(), amount: z.string() })), + steps: z.array(z.string()), + }), + prompt: "Generate a lasagna recipe.", +}); +``` + +## Accessing Reasoning + +You can access the reasoning used by the language model to generate the object via the `reasoning` property on the result. This property contains a string with the model's thought process, if available. + +```ts +import { openai, OpenAIResponsesProviderOptions } from "@ai-sdk/openai"; +import { generateObject } from "ai"; +import { z } from "zod/v4"; + +const result = await generateObject({ + model: openai("gpt-5"), + schema: z.object({ + recipe: z.object({ + name: z.string(), + ingredients: z.array( + z.object({ + name: z.string(), + amount: z.string(), + }) + ), + steps: z.array(z.string()), + }), + }), + prompt: "Generate a lasagna recipe.", + providerOptions: { + openai: { + strictJsonSchema: true, + reasoningSummary: "detailed", + } satisfies OpenAIResponsesProviderOptions, + }, +}); + +console.log(result.reasoning); +``` + +## Error Handling + +When `generateObject` cannot generate a valid object, it throws a [`AI_NoObjectGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-object-generated-error). + +This error occurs when the AI provider fails to generate a parsable object that conforms to the schema. +It can arise due to the following reasons: + +- The model failed to generate a response. +- The model generated a response that could not be parsed. +- The model generated a response that could not be validated against the schema. + +The error preserves the following information to help you log the issue: + +- `text`: The text that was generated by the model. This can be the raw text or the tool call text, depending on the object generation mode. +- `response`: Metadata about the language model response, including response id, timestamp, and model. +- `usage`: Request token usage. +- `cause`: The cause of the error (e.g. a JSON parsing error). You can use this for more detailed error handling. + +```ts +import { generateObject, NoObjectGeneratedError } from "ai"; + +try { + await generateObject({ model, schema, prompt }); +} catch (error) { + if (NoObjectGeneratedError.isInstance(error)) { + console.log("NoObjectGeneratedError"); + console.log("Cause:", error.cause); + console.log("Text:", error.text); + console.log("Response:", error.response); + console.log("Usage:", error.usage); + } +} +``` + +## Repairing Invalid or Malformed JSON + + + The `repairText` function is experimental and may change in the future. + + +Sometimes the model will generate invalid or malformed JSON. +You can use the `repairText` function to attempt to repair the JSON. + +It receives the error, either a `JSONParseError` or a `TypeValidationError`, +and the text that was generated by the model. +You can then attempt to repair the text and return the repaired text. + +```ts highlight="7-10" +import { generateObject } from "ai"; + +const { object } = await generateObject({ + model, + schema, + prompt, + experimental_repairText: async ({ text, error }) => { + // example: add a closing brace to the text + return text + "}"; + }, +}); +``` + +## Structured outputs with `generateText` and `streamText` + +You can generate structured data with `generateText` and `streamText` by using the `experimental_output` setting. + + + Some models, e.g. those by OpenAI, support structured outputs and tool calling + at the same time. This is only possible with `generateText` and `streamText`. + + + + Structured output generation with `generateText` and `streamText` is + experimental and may change in the future. + + +### `generateText` + +```ts highlight="2,4-18" +// experimental_output is a structured object that matches the schema: +const { experimental_output } = await generateText({ + // ... + experimental_output: Output.object({ + schema: z.object({ + name: z.string(), + age: z.number().nullable().describe("Age of the person."), + contact: z.object({ + type: z.literal("email"), + value: z.string(), + }), + occupation: z.object({ + type: z.literal("employed"), + company: z.string(), + position: z.string(), + }), + }), + }), + prompt: "Generate an example person for testing.", +}); +``` + +### `streamText` + +```ts highlight="2,4-18" +// experimental_partialOutputStream contains generated partial objects: +const { experimental_partialOutputStream } = await streamText({ + // ... + experimental_output: Output.object({ + schema: z.object({ + name: z.string(), + age: z.number().nullable().describe("Age of the person."), + contact: z.object({ + type: z.literal("email"), + value: z.string(), + }), + occupation: z.object({ + type: z.literal("employed"), + company: z.string(), + position: z.string(), + }), + }), + }), + prompt: "Generate an example person for testing.", +}); +``` + +## More Examples + +You can see `generateObject` and `streamObject` in action using various frameworks in the following examples: + +### `generateObject` + + + +### `streamObject` + + diff --git a/create-agentic-app/template/docs/technical/betterauth/polar.md b/create-agentic-app/template/docs/technical/betterauth/polar.md new file mode 100644 index 0000000..3066ff6 --- /dev/null +++ b/create-agentic-app/template/docs/technical/betterauth/polar.md @@ -0,0 +1,476 @@ +# plugins: Polar + +URL: /docs/plugins/polar +Source: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/plugins/polar.mdx + +Better Auth Plugin for Payment and Checkouts using Polar + +--- + +title: Polar +description: Better Auth Plugin for Payment and Checkouts using Polar + +--- + +[Polar](https://polar.sh) is a developer first payment infrastructure. Out of the box it provides a lot of developer first integrations for payments, checkouts and more. This plugin helps you integrate Polar with Better Auth to make your auth + payments flow seamless. + + + This plugin is maintained by Polar team. For bugs, issues or feature requests, + please visit the [Polar GitHub + repo](https://github.com/polarsource/polar-adapters). + + +## Features + +- Checkout Integration +- Customer Portal +- Automatic Customer creation on signup +- Event Ingestion & Customer Meters for flexible Usage Based Billing +- Handle Polar Webhooks securely with signature verification +- Reference System to associate purchases with organizations + +## Installation + +```bash +pnpm add better-auth @polar-sh/better-auth @polar-sh/sdk +``` + +## Preparation + +Go to your Polar Organization Settings, and create an Organization Access Token. Add it to your environment. + +```bash +# .env +POLAR_ACCESS_TOKEN=... +``` + +### Configuring BetterAuth Server + +The Polar plugin comes with a handful additional plugins which adds functionality to your stack. + +- Checkout - Enables a seamless checkout integration +- Portal - Makes it possible for your customers to manage their orders, subscriptions & granted benefits +- Usage - Simple extension for listing customer meters & ingesting events for Usage Based Billing +- Webhooks - Listen for relevant Polar webhooks + +```typescript +import { betterAuth } from "better-auth"; +import { polar, checkout, portal, usage, webhooks } from "@polar-sh/better-auth"; +import { Polar } from "@polar-sh/sdk"; + +const polarClient = new Polar({ + accessToken: process.env.POLAR_ACCESS_TOKEN, + // Use 'sandbox' if you're using the Polar Sandbox environment + // Remember that access tokens, products, etc. are completely separated between environments. + // Access tokens obtained in Production are for instance not usable in the Sandbox environment. + server: 'sandbox' +}); + +const auth = betterAuth({ + // ... Better Auth config + plugins: [ + polar({ + client: polarClient, + createCustomerOnSignUp: true, + use: [ + checkout({ + products: [ + { + productId: "123-456-789", // ID of Product from Polar Dashboard + slug: "pro" // Custom slug for easy reference in Checkout URL, e.g. /checkout/pro + } + ], + successUrl: "/success?checkout_id={CHECKOUT_ID}", + authenticatedUsersOnly: true + }), + portal(), + usage(), + webhooks({ + secret: process.env.POLAR_WEBHOOK_SECRET, + onCustomerStateChanged: (payload) => // Triggered when anything regarding a customer changes + onOrderPaid: (payload) => // Triggered when an order was paid (purchase, subscription renewal, etc.) + ... // Over 25 granular webhook handlers + onPayload: (payload) => // Catch-all for all events + }) + ], + }) + ] +}); +``` + +### Configuring BetterAuth Client + +You will be using the BetterAuth Client to interact with the Polar functionalities. + +```typescript +import { createAuthClient } from "better-auth/react"; +import { polarClient } from "@polar-sh/better-auth"; + +// This is all that is needed +// All Polar plugins, etc. should be attached to the server-side BetterAuth config +export const authClient = createAuthClient({ + plugins: [polarClient()], +}); +``` + +## Configuration Options + +```typescript +import { betterAuth } from "better-auth"; +import { + polar, + checkout, + portal, + usage, + webhooks, +} from "@polar-sh/better-auth"; +import { Polar } from "@polar-sh/sdk"; + +const polarClient = new Polar({ + accessToken: process.env.POLAR_ACCESS_TOKEN, + // Use 'sandbox' if you're using the Polar Sandbox environment + // Remember that access tokens, products, etc. are completely separated between environments. + // Access tokens obtained in Production are for instance not usable in the Sandbox environment. + server: "sandbox", +}); + +const auth = betterAuth({ + // ... Better Auth config + plugins: [ + polar({ + client: polarClient, + createCustomerOnSignUp: true, + getCustomerCreateParams: ({ user }, request) => ({ + metadata: { + myCustomProperty: 123, + }, + }), + use: [ + // This is where you add Polar plugins + ], + }), + ], +}); +``` + +### Required Options + +- `client`: Polar SDK client instance + +### Optional Options + +- `createCustomerOnSignUp`: Automatically create a Polar customer when a user signs up +- `getCustomerCreateParams`: Custom function to provide additional customer creation metadata + +### Customers + +When `createCustomerOnSignUp` is enabled, a new Polar Customer is automatically created when a new User is added in the Better-Auth Database. + +All new customers are created with an associated `externalId`, which is the ID of your User in the Database. This allows us to skip any Polar to User mapping in your Database. + +## Checkout Plugin + +To support checkouts in your app, simply pass the Checkout plugin to the use-property. + +```typescript +import { polar, checkout } from "@polar-sh/better-auth"; + +const auth = betterAuth({ + // ... Better Auth config + plugins: [ + polar({ + ... + use: [ + checkout({ + // Optional field - will make it possible to pass a slug to checkout instead of Product ID + products: [ { productId: "123-456-789", slug: "pro" } ], + // Relative URL to return to when checkout is successfully completed + successUrl: "/success?checkout_id={CHECKOUT_ID}", + // Whether you want to allow unauthenticated checkout sessions or not + authenticatedUsersOnly: true + }) + ], + }) + ] +}); +``` + +When checkouts are enabled, you're able to initialize Checkout Sessions using the checkout-method on the BetterAuth Client. This will redirect the user to the Product Checkout. + +```typescript +await authClient.checkout({ + // Any Polar Product ID can be passed here + products: ["e651f46d-ac20-4f26-b769-ad088b123df2"], + // Or, if you setup "products" in the Checkout Config, you can pass the slug + slug: "pro", +}); +``` + +Checkouts will automatically carry the authenticated User as the customer to the checkout. Email-address will be "locked-in". + +If `authenticatedUsersOnly` is `false` - then it will be possible to trigger checkout sessions without any associated customer. + +### Organization Support + +This plugin supports the Organization plugin. If you pass the organization ID to the Checkout referenceId, you will be able to keep track of purchases made from organization members. + +```typescript +const organizationId = (await authClient.organization.list())?.data?.[0]?.id, + +await authClient.checkout({ + // Any Polar Product ID can be passed here + products: ["e651f46d-ac20-4f26-b769-ad088b123df2"], + // Or, if you setup "products" in the Checkout Config, you can pass the slug + slug: 'pro', + // Reference ID will be saved as `referenceId` in the metadata of the checkout, order & subscription object + referenceId: organizationId +}); +``` + +## Portal Plugin + +A plugin which enables customer management of their purchases, orders and subscriptions. + +```typescript +import { polar, checkout, portal } from "@polar-sh/better-auth"; + +const auth = betterAuth({ + // ... Better Auth config + plugins: [ + polar({ + ... + use: [ + checkout(...), + portal() + ], + }) + ] +}); +``` + +The portal-plugin gives the BetterAuth Client a set of customer management methods, scoped under `authClient.customer`. + +### Customer Portal Management + +The following method will redirect the user to the Polar Customer Portal, where they can see orders, purchases, subscriptions, benefits, etc. + +```typescript +await authClient.customer.portal(); +``` + +### Customer State + +The portal plugin also adds a convenient state-method for retrieving the general Customer State. + +```typescript +const { data: customerState } = await authClient.customer.state(); +``` + +The customer state object contains: + +- All the data about the customer. +- The list of their active subscriptions + - Note: This does not include subscriptions done by a parent organization. See the subscription list-method below for more information. +- The list of their granted benefits. +- The list of their active meters, with their current balance. + +Thus, with that single object, you have all the required information to check if you should provision access to your service or not. + +[You can learn more about the Polar Customer State in the Polar Docs](https://docs.polar.sh/integrate/customer-state). + +### Benefits, Orders & Subscriptions + +The portal plugin adds 3 convenient methods for listing benefits, orders & subscriptions relevant to the authenticated user/customer. + +[All of these methods use the Polar CustomerPortal APIs](https://docs.polar.sh/api-reference/customer-portal) + +#### Benefits + +This method only lists granted benefits for the authenticated user/customer. + +```typescript +const { data: benefits } = await authClient.customer.benefits.list({ + query: { + page: 1, + limit: 10, + }, +}); +``` + +#### Orders + +This method lists orders like purchases and subscription renewals for the authenticated user/customer. + +```typescript +const { data: orders } = await authClient.customer.orders.list({ + query: { + page: 1, + limit: 10, + productBillingType: "one_time", // or 'recurring' + }, +}); +``` + +#### Subscriptions + +This method lists the subscriptions associated with authenticated user/customer. + +```typescript +const { data: subscriptions } = await authClient.customer.subscriptions.list({ + query: { + page: 1, + limit: 10, + active: true, + }, +}); +``` + +**Important** - Organization Support + +This will **not** return subscriptions made by a parent organization to the authenticated user. + +However, you can pass a `referenceId` to this method. This will return all subscriptions associated with that referenceId instead of subscriptions associated with the user. + +So in order to figure out if a user should have access, pass the user's organization ID to see if there is an active subscription for that organization. + +```typescript +const organizationId = (await authClient.organization.list())?.data?.[0]?.id, + +const { data: subscriptions } = await authClient.customer.orders.list({ + query: { + page: 1, + limit: 10, + active: true, + referenceId: organizationId + }, +}); + +const userShouldHaveAccess = subscriptions.some( + sub => // Your logic to check subscription product or whatever. +) +``` + +## Usage Plugin + +A simple plugin for Usage Based Billing. + +```typescript +import { polar, checkout, portal, usage } from "@polar-sh/better-auth"; + +const auth = betterAuth({ + // ... Better Auth config + plugins: [ + polar({ + ... + use: [ + checkout(...), + portal(), + usage() + ], + }) + ] +}); +``` + +### Event Ingestion + +Polar's Usage Based Billing builds entirely on event ingestion. Ingest events from your application, create Meters to represent that usage, and add metered prices to Products to charge for it. + +[Learn more about Usage Based Billing in the Polar Docs.](https://docs.polar.sh/features/usage-based-billing/introduction) + +```typescript +const { data: ingested } = await authClient.usage.ingest({ + event: "file-uploads", + metadata: { + uploadedFiles: 12, + }, +}); +``` + +The authenticated user is automatically associated with the ingested event. + +### Customer Meters + +A simple method for listing the authenticated user's Usage Meters, or as we call them, Customer Meters. + +Customer Meter's contains all information about their consumption on your defined meters. + +- Customer Information +- Meter Information +- Customer Meter Information + - Consumed Units + - Credited Units + - Balance + +```typescript +const { data: customerMeters } = await authClient.usage.meters.list({ + query: { + page: 1, + limit: 10, + }, +}); +``` + +## Webhooks Plugin + +The Webhooks plugin can be used to capture incoming events from your Polar organization. + +```typescript +import { polar, webhooks } from "@polar-sh/better-auth"; + +const auth = betterAuth({ + // ... Better Auth config + plugins: [ + polar({ + ... + use: [ + webhooks({ + secret: process.env.POLAR_WEBHOOK_SECRET, + onCustomerStateChanged: (payload) => // Triggered when anything regarding a customer changes + onOrderPaid: (payload) => // Triggered when an order was paid (purchase, subscription renewal, etc.) + ... // Over 25 granular webhook handlers + onPayload: (payload) => // Catch-all for all events + }) + ], + }) + ] +}); +``` + +Configure a Webhook endpoint in your Polar Organization Settings page. Webhook endpoint is configured at /polar/webhooks. + +Add the secret to your environment. + +```bash +# .env +POLAR_WEBHOOK_SECRET=... +``` + +The plugin supports handlers for all Polar webhook events: + +- `onPayload` - Catch-all handler for any incoming Webhook event +- `onCheckoutCreated` - Triggered when a checkout is created +- `onCheckoutUpdated` - Triggered when a checkout is updated +- `onOrderCreated` - Triggered when an order is created +- `onOrderPaid` - Triggered when an order is paid +- `onOrderRefunded` - Triggered when an order is refunded +- `onRefundCreated` - Triggered when a refund is created +- `onRefundUpdated` - Triggered when a refund is updated +- `onSubscriptionCreated` - Triggered when a subscription is created +- `onSubscriptionUpdated` - Triggered when a subscription is updated +- `onSubscriptionActive` - Triggered when a subscription becomes active +- `onSubscriptionCanceled` - Triggered when a subscription is canceled +- `onSubscriptionRevoked` - Triggered when a subscription is revoked +- `onSubscriptionUncanceled` - Triggered when a subscription cancellation is reversed +- `onProductCreated` - Triggered when a product is created +- `onProductUpdated` - Triggered when a product is updated +- `onOrganizationUpdated` - Triggered when an organization is updated +- `onBenefitCreated` - Triggered when a benefit is created +- `onBenefitUpdated` - Triggered when a benefit is updated +- `onBenefitGrantCreated` - Triggered when a benefit grant is created +- `onBenefitGrantUpdated` - Triggered when a benefit grant is updated +- `onBenefitGrantRevoked` - Triggered when a benefit grant is revoked +- `onCustomerCreated` - Triggered when a customer is created +- `onCustomerUpdated` - Triggered when a customer is updated +- `onCustomerDeleted` - Triggered when a customer is deleted +- `onCustomerStateChanged` - Triggered when a customer is created diff --git a/create-agentic-app/template/docs/technical/react-markdown.md b/create-agentic-app/template/docs/technical/react-markdown.md new file mode 100644 index 0000000..d4f5406 --- /dev/null +++ b/create-agentic-app/template/docs/technical/react-markdown.md @@ -0,0 +1,123 @@ +# react-markdown + +React component to render markdown. + +## Contents + +- [Install](#install) +- [Use](#use) +- [API](#api) +- [Examples](#examples) +- [Plugins](#plugins) + +## What is this? + +This package is a React component that can be given a string of markdown that it'll safely render to React elements. You can pass plugins to change how markdown is transformed and pass components that will be used instead of normal HTML elements. + +## Install + +```sh +npm install react-markdown +``` + +## Use + +Basic usage: + +```js +import Markdown from "react-markdown"; + +const markdown = "# Hi, *Pluto*!"; + +{markdown} +``` + +With plugins: + +```js +import Markdown from "react-markdown"; +import remarkGfm from "remark-gfm"; + +const markdown = `Just a link: www.nasa.gov.`; + +{markdown} +``` + +## API + +Key props: + +- `children` ā€” markdown string to render +- `remarkPlugins` ā€” array of remark plugins +- `rehypePlugins` ā€” array of rehype plugins +- `components` ā€” object mapping HTML tags to React components +- `allowedElements` ā€” array of allowed HTML tags +- `disallowedElements` ā€” array of disallowed HTML tags + +## Examples + +### Using GitHub Flavored Markdown + +```js +import Markdown from "react-markdown"; +import remarkGfm from "remark-gfm"; + +const markdown = ` +* [x] todo +* [ ] done + +| Column 1 | Column 2 | +|----------|----------| +| Cell 1 | Cell 2 | +`; + +{markdown} +``` + +### Custom Components (Syntax Highlighting) + +```js +import Markdown from "react-markdown"; +import { Prism as SyntaxHighlighter } from "react-syntax-highlighter"; +import { dark } from "react-syntax-highlighter/dist/esm/styles/prism"; + +const markdown = ` +\`\`\`js +console.log('Hello, world!'); +\`\`\` +`; + + + ) : ( + + {children} + + ); + }, + }} +> + {markdown} + +``` + +## Plugins + +Common plugins: + +- `remark-gfm` ā€” GitHub Flavored Markdown (tables, task lists, strikethrough) +- `remark-math` ā€” Math notation support +- `rehype-katex` ā€” Render math with KaTeX +- `rehype-highlight` ā€” Syntax highlighting +- `rehype-raw` ā€” Allow raw HTML (use carefully for security) diff --git a/create-agentic-app/template/drizzle.config.ts b/create-agentic-app/template/drizzle.config.ts new file mode 100644 index 0000000..490ea9e --- /dev/null +++ b/create-agentic-app/template/drizzle.config.ts @@ -0,0 +1,10 @@ +import type { Config } from "drizzle-kit"; + +export default { + dialect: "postgresql", + schema: "./src/lib/schema.ts", + out: "./drizzle", + dbCredentials: { + url: process.env.POSTGRES_URL!, + }, +} satisfies Config; diff --git a/create-agentic-app/template/env.example b/create-agentic-app/template/env.example new file mode 100644 index 0000000..c71be99 --- /dev/null +++ b/create-agentic-app/template/env.example @@ -0,0 +1,29 @@ +# Database +POSTGRES_URL=postgresql://dev_user:dev_password@localhost:5432/postgres_dev + +# Authentication - Better Auth +# Generate key using https://www.better-auth.com/docs/installation +BETTER_AUTH_SECRET=qtD4Ssa0t5jY7ewALgai97sKhAtn7Ysc + +# Google OAuth (Get from Google Cloud Console) +# Redirect URI: http://localhost:3000/api/auth/callback/google +GOOGLE_CLIENT_ID= +GOOGLE_CLIENT_SECRET= + +# AI Integration (Optional - for chat functionality) +OPENAI_API_KEY= +OPENAI_MODEL="gpt-5-mini" + +# Optional - for vector search only +OPENAI_EMBEDDING_MODEL="text-embedding-3-large" + +# App URL (for production deployments) +NEXT_PUBLIC_APP_URL="http://localhost:3000" + +# File storage (optional - if app required file uploads) +BLOB_READ_WRITE_TOKEN= + +# Polar payment processing +# Get these from: https://sandbox.polar.sh/dashboard (sandbox) or https://polar.sh/dashboard (production) +POLAR_WEBHOOK_SECRET=polar_ +POLAR_ACCESS_TOKEN=polar_ \ No newline at end of file diff --git a/create-agentic-app/template/eslint.config.mjs b/create-agentic-app/template/eslint.config.mjs new file mode 100644 index 0000000..c85fb67 --- /dev/null +++ b/create-agentic-app/template/eslint.config.mjs @@ -0,0 +1,16 @@ +import { dirname } from "path"; +import { fileURLToPath } from "url"; +import { FlatCompat } from "@eslint/eslintrc"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const compat = new FlatCompat({ + baseDirectory: __dirname, +}); + +const eslintConfig = [ + ...compat.extends("next/core-web-vitals", "next/typescript"), +]; + +export default eslintConfig; diff --git a/create-agentic-app/template/next.config.ts b/create-agentic-app/template/next.config.ts new file mode 100644 index 0000000..e9ffa30 --- /dev/null +++ b/create-agentic-app/template/next.config.ts @@ -0,0 +1,7 @@ +import type { NextConfig } from "next"; + +const nextConfig: NextConfig = { + /* config options here */ +}; + +export default nextConfig; diff --git a/create-agentic-app/template/package.json b/create-agentic-app/template/package.json new file mode 100644 index 0000000..68b96d9 --- /dev/null +++ b/create-agentic-app/template/package.json @@ -0,0 +1,56 @@ +{ + "name": "agentic-coding-starter-kit", + "version": "0.1.0", + "private": true, + "scripts": { + "dev": "next dev --turbopack", + "build": "pnpm run db:migrate && next build", + "start": "next start", + "lint": "next lint", + "typecheck": "tsc --noEmit", + "db:generate": "drizzle-kit generate", + "db:migrate": "drizzle-kit migrate", + "db:push": "drizzle-kit push", + "db:studio": "drizzle-kit studio", + "db:dev": "drizzle-kit push", + "db:reset": "drizzle-kit drop && drizzle-kit push" + }, + "dependencies": { + "@ai-sdk/openai": "^2.0.53", + "@ai-sdk/react": "^2.0.78", + "@radix-ui/react-avatar": "^1.1.10", + "@radix-ui/react-dialog": "^1.1.15", + "@radix-ui/react-dropdown-menu": "^2.1.16", + "@radix-ui/react-slot": "^1.2.3", + "ai": "^5.0.78", + "better-auth": "^1.3.29", + "class-variance-authority": "^0.7.1", + "clsx": "^2.1.1", + "drizzle-orm": "^0.44.7", + "lucide-react": "^0.539.0", + "next": "15.4.6", + "next-themes": "^0.4.6", + "pg": "^8.16.3", + "postgres": "^3.4.7", + "react": "19.1.0", + "react-dom": "19.1.0", + "react-markdown": "^10.1.0", + "tailwind-merge": "^3.3.1", + "zod": "^4.1.12" + }, + "devDependencies": { + "@eslint/eslintrc": "^3.3.1", + "@tailwindcss/postcss": "^4.1.16", + "@types/node": "^20.19.23", + "@types/pg": "^8.15.5", + "@types/react": "^19.2.2", + "@types/react-dom": "^19.2.2", + "drizzle-kit": "^0.31.5", + "eslint": "^9.38.0", + "eslint-config-next": "15.4.6", + "shadcn": "^3.5.0", + "tailwindcss": "^4.1.16", + "tw-animate-css": "^1.4.0", + "typescript": "^5.9.3" + } +} diff --git a/create-agentic-app/template/postcss.config.mjs b/create-agentic-app/template/postcss.config.mjs new file mode 100644 index 0000000..c7bcb4b --- /dev/null +++ b/create-agentic-app/template/postcss.config.mjs @@ -0,0 +1,5 @@ +const config = { + plugins: ["@tailwindcss/postcss"], +}; + +export default config; diff --git a/create-agentic-app/template/public/file.svg b/create-agentic-app/template/public/file.svg new file mode 100644 index 0000000..004145c --- /dev/null +++ b/create-agentic-app/template/public/file.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/create-agentic-app/template/public/globe.svg b/create-agentic-app/template/public/globe.svg new file mode 100644 index 0000000..567f17b --- /dev/null +++ b/create-agentic-app/template/public/globe.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/create-agentic-app/template/public/next.svg b/create-agentic-app/template/public/next.svg new file mode 100644 index 0000000..5174b28 --- /dev/null +++ b/create-agentic-app/template/public/next.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/create-agentic-app/template/public/vercel.svg b/create-agentic-app/template/public/vercel.svg new file mode 100644 index 0000000..7705396 --- /dev/null +++ b/create-agentic-app/template/public/vercel.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/create-agentic-app/template/public/window.svg b/create-agentic-app/template/public/window.svg new file mode 100644 index 0000000..b2b2a44 --- /dev/null +++ b/create-agentic-app/template/public/window.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/create-agentic-app/template/src/app/api/chat/route.ts b/create-agentic-app/template/src/app/api/chat/route.ts new file mode 100644 index 0000000..68ee73f --- /dev/null +++ b/create-agentic-app/template/src/app/api/chat/route.ts @@ -0,0 +1,15 @@ +import { openai } from "@ai-sdk/openai"; +import { streamText, UIMessage, convertToModelMessages } from "ai"; + +export async function POST(req: Request) { + const { messages }: { messages: UIMessage[] } = await req.json(); + + const result = streamText({ + model: openai(process.env.OPENAI_MODEL || "gpt-5-mini"), + messages: convertToModelMessages(messages), + }); + + return ( + result as unknown as { toUIMessageStreamResponse: () => Response } + ).toUIMessageStreamResponse(); +} diff --git a/create-agentic-app/template/src/app/api/diagnostics/route.ts b/create-agentic-app/template/src/app/api/diagnostics/route.ts new file mode 100644 index 0000000..eb3b579 --- /dev/null +++ b/create-agentic-app/template/src/app/api/diagnostics/route.ts @@ -0,0 +1,126 @@ +import { NextResponse } from "next/server"; + +type StatusLevel = "ok" | "warn" | "error"; + +interface DiagnosticsResponse { + timestamp: string; + env: { + POSTGRES_URL: boolean; + BETTER_AUTH_SECRET: boolean; + GOOGLE_CLIENT_ID: boolean; + GOOGLE_CLIENT_SECRET: boolean; + OPENAI_API_KEY: boolean; + NEXT_PUBLIC_APP_URL: boolean; + }; + database: { + connected: boolean; + schemaApplied: boolean; + error?: string; + }; + auth: { + configured: boolean; + routeResponding: boolean | null; + }; + ai: { + configured: boolean; + }; + overallStatus: StatusLevel; +} + +export async function GET(req: Request) { + const env = { + POSTGRES_URL: Boolean(process.env.POSTGRES_URL), + BETTER_AUTH_SECRET: Boolean(process.env.BETTER_AUTH_SECRET), + GOOGLE_CLIENT_ID: Boolean(process.env.GOOGLE_CLIENT_ID), + GOOGLE_CLIENT_SECRET: Boolean(process.env.GOOGLE_CLIENT_SECRET), + OPENAI_API_KEY: Boolean(process.env.OPENAI_API_KEY), + NEXT_PUBLIC_APP_URL: Boolean(process.env.NEXT_PUBLIC_APP_URL), + } as const; + + // Database checks + let dbConnected = false; + let schemaApplied = false; + let dbError: string | undefined; + if (env.POSTGRES_URL) { + try { + const [{ db }, { sql }, schema] = await Promise.all([ + import("@/lib/db"), + import("drizzle-orm"), + import("@/lib/schema"), + ]); + // Ping DB + await db.execute(sql`select 1`); + dbConnected = true; + try { + // Touch a known table to verify migrations + await db.select().from(schema.user).limit(1); + schemaApplied = true; + } catch { + schemaApplied = false; + } + } catch (err) { + dbConnected = false; + dbError = err instanceof Error ? err.message : "Unknown database error"; + } + } else { + dbConnected = false; + schemaApplied = false; + dbError = "POSTGRES_URL is not set"; + } + + // Auth route check: we consider the route responding if it returns any HTTP response + // for /api/auth/session (status codes in the 2xx-4xx range are acceptable for readiness) + const origin = (() => { + try { + return new URL(req.url).origin; + } catch { + return process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000"; + } + })(); + + let authRouteResponding: boolean | null = null; + try { + const res = await fetch(`${origin}/api/auth/session`, { + method: "GET", + headers: { Accept: "application/json" }, + cache: "no-store", + }); + authRouteResponding = res.status >= 200 && res.status < 500; + } catch { + authRouteResponding = false; + } + + const authConfigured = + env.BETTER_AUTH_SECRET && env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET; + const aiConfigured = env.OPENAI_API_KEY; // We avoid live-calling the AI provider here + + const overallStatus: StatusLevel = (() => { + if (!env.POSTGRES_URL || !dbConnected || !schemaApplied) return "error"; + if (!authConfigured) return "error"; + // AI is optional; warn if not configured + if (!aiConfigured) return "warn"; + return "ok"; + })(); + + const body: DiagnosticsResponse = { + timestamp: new Date().toISOString(), + env, + database: { + connected: dbConnected, + schemaApplied, + error: dbError, + }, + auth: { + configured: authConfigured, + routeResponding: authRouteResponding, + }, + ai: { + configured: aiConfigured, + }, + overallStatus, + }; + + return NextResponse.json(body, { + status: 200, + }); +} diff --git a/create-agentic-app/template/src/app/chat/page.tsx b/create-agentic-app/template/src/app/chat/page.tsx new file mode 100644 index 0000000..c77825e --- /dev/null +++ b/create-agentic-app/template/src/app/chat/page.tsx @@ -0,0 +1,207 @@ +"use client"; + +import { useChat } from "@ai-sdk/react"; +import { Button } from "@/components/ui/button"; +import { UserProfile } from "@/components/auth/user-profile"; +import { useSession } from "@/lib/auth-client"; +import { useState, type ReactNode } from "react"; +import ReactMarkdown from "react-markdown"; +import type { Components } from "react-markdown"; + +const H1: React.FC> = (props) => ( +

+); +const H2: React.FC> = (props) => ( +

+); +const H3: React.FC> = (props) => ( +

+); +const Paragraph: React.FC> = ( + props +) =>

; +const UL: React.FC> = (props) => ( +