diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1728945 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,352 @@ +# Contributing to Git Search + +๐ŸŽ‰ Thank you for your interest in contributing to Git Search! We welcome contributions from developers of all experience levels. + +## ๐Ÿ“‹ Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [How to Contribute](#how-to-contribute) +- [Pull Request Process](#pull-request-process) +- [Coding Standards](#coding-standards) +- [Testing Guidelines](#testing-guidelines) +- [Reporting Issues](#reporting-issues) +- [Community](#community) + +## ๐Ÿ“œ Code of Conduct + +By participating in this project, you agree to abide by our Code of Conduct. Please be respectful, inclusive, and constructive in all interactions. + +### Our Standards + +- Use welcoming and inclusive language +- Be respectful of differing viewpoints and experiences +- Gracefully accept constructive criticism +- Focus on what is best for the community +- Show empathy towards other community members + +## ๐Ÿš€ Getting Started + +### Prerequisites + +Before contributing, make sure you have: + +- Node.js 18+ installed +- Git installed and configured +- A GitHub account +- Basic knowledge of TypeScript, React, and Next.js + +### Development Setup + +1. **Fork the repository** + ```bash + # Click the "Fork" button on GitHub, then clone your fork + git clone https://github.com/YOUR_USERNAME/git-search.git + cd git-search + ``` + +2. **Add upstream remote** + ```bash + git remote add upstream https://github.com/RafiulM/git-search.git + ``` + +3. **Install dependencies** + ```bash + npm install + ``` + +4. **Set up environment variables** + ```bash + cp .env.example .env.local + # Fill in your API keys and environment variables + ``` + +5. **Run the development server** + ```bash + npm run dev + ``` + +6. **Verify the setup** + - Open [http://localhost:3000](http://localhost:3000) + - Ensure the application loads correctly + +## ๐Ÿ› ๏ธ How to Contribute + +### Types of Contributions + +We welcome various types of contributions: + +- ๐Ÿ› **Bug fixes** - Fix existing issues +- โœจ **New features** - Add new functionality +- ๐Ÿ“ **Documentation** - Improve docs, READMEs, code comments +- ๐ŸŽจ **UI/UX improvements** - Enhance user interface and experience +- โšก **Performance optimizations** - Make the app faster +- ๐Ÿงช **Tests** - Add or improve test coverage +- ๐Ÿ”ง **Refactoring** - Improve code quality and structure + +### Finding Work + +1. **Check existing issues** - Look for issues labeled `good first issue` or `help wanted` +2. **Create new issues** - If you find bugs or have feature ideas +3. **Join discussions** - Participate in GitHub Discussions + +## ๐Ÿ“ฅ Pull Request Process + +### Before You Start + +1. **Create an issue** first to discuss major changes +2. **Check existing PRs** to avoid duplication +3. **Assign yourself** to the issue you're working on + +### Step-by-Step Process + +1. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/issue-number-description + ``` + +2. **Make your changes** + - Follow our coding standards + - Add tests for new functionality + - Update documentation if needed + +3. **Test your changes** + ```bash + npm run lint # Check linting + npm run build # Ensure it builds + npm run test # Run tests (if available) + ``` + +4. **Commit your changes** + ```bash + git add . + git commit -m "feat: add search filtering by language" + ``` + +5. **Push to your fork** + ```bash + git push origin feature/your-feature-name + ``` + +6. **Create a Pull Request** + - Use a clear, descriptive title + - Fill out the PR template completely + - Link to related issues + - Add screenshots for UI changes + +### PR Requirements + +- โœ… All tests pass +- โœ… Code follows our style guidelines +- โœ… Documentation updated (if applicable) +- โœ… No merge conflicts +- โœ… Descriptive commit messages +- โœ… PR template filled out + +## ๐ŸŽจ Coding Standards + +### TypeScript Guidelines + +- Use TypeScript for all new code +- Define proper types and interfaces +- Avoid `any` type when possible +- Use strict mode settings + +### Code Style + +- Use Prettier for formatting +- Follow ESLint rules +- Use meaningful variable and function names +- Write self-documenting code +- Add comments for complex logic + +### File Organization + +``` +src/ +โ”œโ”€โ”€ components/ +โ”‚ โ”œโ”€โ”€ ui/ # Reusable UI components +โ”‚ โ”œโ”€โ”€ search/ # Search-specific components +โ”‚ โ””โ”€โ”€ common/ # Shared components +โ”œโ”€โ”€ lib/ # Utility functions +โ”œโ”€โ”€ hooks/ # Custom React hooks +โ”œโ”€โ”€ types/ # TypeScript type definitions +โ””โ”€โ”€ utils/ # Helper functions +``` + +### Component Guidelines + +- Use functional components with hooks +- Extract custom hooks for reusable logic +- Keep components small and focused +- Use proper prop types +- Handle loading and error states + +### API Guidelines + +- Use proper HTTP status codes +- Implement error handling +- Add input validation +- Document API endpoints +- Use consistent response formats + +## ๐Ÿงช Testing Guidelines + +### Testing Framework + +We use Jest and React Testing Library for testing. + +### Writing Tests + +- Write tests for new features +- Include edge cases +- Test user interactions +- Mock external dependencies +- Aim for meaningful test coverage + +### Running Tests + +```bash +npm run test # Run all tests +npm run test:watch # Run tests in watch mode +npm run test:coverage # Run tests with coverage +``` + +## ๐Ÿ› Reporting Issues + +### Bug Reports + +When reporting bugs, please include: + +- **Clear title** - Briefly describe the issue +- **Steps to reproduce** - Detailed reproduction steps +- **Expected behavior** - What should happen +- **Actual behavior** - What actually happens +- **Environment details** - OS, browser, Node.js version +- **Screenshots** - If applicable +- **Additional context** - Any other relevant information + +### Feature Requests + +For feature requests, please include: + +- **Problem description** - What problem does this solve? +- **Proposed solution** - How should it work? +- **Alternatives considered** - Other approaches you've thought of +- **Additional context** - Why is this important? + +### Issue Labels + +We use labels to categorize issues: + +- `bug` - Something isn't working +- `enhancement` - New feature or request +- `documentation` - Improvements to docs +- `good first issue` - Good for newcomers +- `help wanted` - Extra attention needed +- `priority: high/medium/low` - Priority level + +## ๐Ÿค Community + +### Communication Channels + +- **GitHub Issues** - Bug reports and feature requests +- **GitHub Discussions** - General discussions and questions +- **Pull Requests** - Code review and collaboration + +### Getting Help + +If you need help: + +1. Check existing documentation +2. Search GitHub Issues for similar questions +3. Create a new issue with the `question` label +4. Join GitHub Discussions + +### Recognition + +Contributors are recognized in: + +- **README.md** - Major contributors listed +- **Release notes** - Contributions highlighted +- **GitHub contributions** - Automatic recognition + +## ๐Ÿ“ Development Workflow + +### Branch Naming + +- `feature/description` - New features +- `fix/issue-number` - Bug fixes +- `docs/description` - Documentation updates +- `refactor/description` - Code refactoring + +### Commit Messages + +Follow conventional commit format: + +``` +type(scope): description + +[optional body] + +[optional footer] +``` + +Types: +- `feat` - New feature +- `fix` - Bug fix +- `docs` - Documentation +- `style` - Formatting +- `refactor` - Code refactoring +- `test` - Adding tests +- `chore` - Maintenance tasks + +Examples: +``` +feat(search): add language filter to repository search +fix(ui): resolve dark mode toggle issue on mobile +docs(readme): update installation instructions +``` + +### Release Process + +1. Features merged to `main` branch +2. Regular releases with semantic versioning +3. Release notes generated automatically +4. Contributors acknowledged in releases + +## ๐ŸŽฏ Roadmap + +Check our [GitHub Projects](https://github.com/RafiulM/git-search/projects) to see: + +- Current sprint goals +- Upcoming features +- Long-term roadmap +- Issue priorities + +## ๐Ÿ“š Resources + +### Learning Resources + +- [Next.js Documentation](https://nextjs.org/docs) +- [React Documentation](https://reactjs.org/docs) +- [TypeScript Handbook](https://www.typescriptlang.org/docs/) +- [Tailwind CSS Documentation](https://tailwindcss.com/docs) + +### Project Resources + +- [Architecture Documentation](docs/ARCHITECTURE.md) +- [API Documentation](docs/API.md) +- [Deployment Guide](docs/DEPLOYMENT.md) +- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) + +--- + +## ๐Ÿ™ Thank You + +Thank you for contributing to Git Search! Your contributions help make this tool better for developers worldwide. + +**Happy coding! ๐Ÿš€โœจ** \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ffda4ab --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Rafiul Islam + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 6471acd..73813ed 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,40 @@ -[![CodeGuide](/codeguide-backdrop.svg)](https://codeguide.dev) - # CodeGuide Starter Kit Lite v2 -A modern web application starter template built with Next.js 15, featuring authentication, database integration, AI capabilities, and dark mode support. +
+ +๐Ÿš€ **A modern Next.js starter template with authentication, database integration, AI capabilities, and comprehensive UI components** + +[![Next.js](https://img.shields.io/badge/Next.js-15-black?style=flat&logo=next.js)](https://nextjs.org/) +[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?style=flat&logo=typescript)](https://www.typescriptlang.org/) +[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4-38B2AC?style=flat&logo=tailwind-css)](https://tailwindcss.com/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +
+ +CodeGuide Starter Kit Lite v2 is a comprehensive Next.js starter template that accelerates your development workflow. It comes pre-configured with modern authentication, database integration, AI capabilities, and a complete UI component system to help you build production-ready applications faster. + +## ๐Ÿ“ธ Demo + +> **Note**: Screenshots and live demo links will be added once deployed. + +### Key Features Showcase +- ๐Ÿ  **Dashboard**: Clean setup status and environment validation +- ๐Ÿ’ฌ **AI Chat**: Interactive AI conversation interface +- ๐ŸŽจ **UI Components**: 40+ pre-built shadcn/ui components +- ๐ŸŒ™ **Theme System**: Seamless dark/light mode switching + +## โœจ Features -## Tech Stack +- ๐Ÿ” **Authentication Ready** - Pre-configured Clerk authentication with middleware protection +- ๐Ÿ—„๏ธ **Database Integration** - Supabase setup with Row Level Security (RLS) policies +- ๐Ÿค– **AI Integration** - Vercel AI SDK with OpenAI and Anthropic support +- ๐ŸŽจ **Complete UI System** - 40+ shadcn/ui components (New York style) +- ๐ŸŒ™ **Theme System** - Dark/light mode with next-themes and system detection +- ๐Ÿ“ฑ **Responsive Design** - Mobile-first design with TailwindCSS v4 +- โšก **Performance Optimized** - Next.js 15 App Router with TypeScript +- ๐Ÿ”ง **Developer Experience** - ESLint, TypeScript strict mode, and hot reloading + +## ๐Ÿš€ Tech Stack - **Framework:** [Next.js 15](https://nextjs.org/) (App Router) - **Language:** TypeScript @@ -12,175 +42,546 @@ A modern web application starter template built with Next.js 15, featuring authe - **Database:** [Supabase](https://supabase.com/) - **Styling:** [Tailwind CSS v4](https://tailwindcss.com/) - **UI Components:** [shadcn/ui](https://ui.shadcn.com/) -- **AI Integration:** [Vercel AI SDK](https://sdk.vercel.ai/) +- **AI Integration:** [Vercel AI SDK](https://sdk.vercel.ai/) with OpenAI/Anthropic - **Theme System:** [next-themes](https://github.com/pacocoursey/next-themes) -## Prerequisites +## ๐Ÿ“‹ Prerequisites Before you begin, ensure you have the following: + - Node.js 18+ installed - A [Clerk](https://clerk.com/) account for authentication - A [Supabase](https://supabase.com/) account for database - Optional: [OpenAI](https://platform.openai.com/) or [Anthropic](https://console.anthropic.com/) API key for AI features -- Generated project documents from [CodeGuide](https://codeguide.dev/) for best development experience -## Getting Started +## โš™๏ธ Installation + +### Quick Start 1. **Clone the repository** ```bash - git clone + git clone https://github.com/RafiulM/codeguide-starter-kit-lite-v2.git cd codeguide-starter-kit-lite-v2 ``` -2. **Install dependencies** +2. **Verify Node.js version** + ```bash + node --version # Should be 18.0.0 or higher + npm --version # Should be 8.0.0 or higher + ``` + +3. **Install dependencies** ```bash + # Using npm (recommended) npm install - # or + + # Or using yarn yarn install - # or + + # Or using pnpm pnpm install ``` -3. **Environment Variables Setup** - - Copy the `.env.example` file to `.env.local`: - ```bash - cp .env.example .env.local - ``` - - Fill in the environment variables in `.env.local` (see Configuration section below) +4. **Environment Variables Setup** + ```bash + # Copy the example environment file + cp .env.example .env.local + + # Edit the .env.local file with your actual values + # See the Configuration section below for detailed setup + ``` -4. **Start the development server** +5. **Database Setup** (Optional for basic functionality) + ```bash + # Install Supabase CLI if not already installed + npm install -g supabase + + # Initialize Supabase (if needed) + supabase init + + # Run database migrations + npx supabase db push + ``` + +6. **Start the development server** ```bash npm run dev - # or - yarn dev - # or - pnpm dev ``` -5. **Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.** +7. **Verify installation** + - Open [http://localhost:3000](http://localhost:3000) + - You should see the Git Search application + - Check the browser console for any errors -The homepage includes a setup dashboard with direct links to configure each service. +### Installation Troubleshooting -## Configuration +If you encounter issues during installation: -### Clerk Setup -1. Go to [Clerk Dashboard](https://dashboard.clerk.com/) -2. Create a new application -3. Go to API Keys -4. Copy the `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` +1. **Node.js version issues**: + ```bash + # Use nvm to install the correct version + nvm install 18 + nvm use 18 + ``` -### Supabase Setup -1. Go to [Supabase Dashboard](https://supabase.com/dashboard) -2. Create a new project -3. Go to Authentication โ†’ Integrations โ†’ Add Clerk (for third-party auth) -4. Go to Project Settings > API -5. Copy the `Project URL` as `NEXT_PUBLIC_SUPABASE_URL` -6. Copy the `anon` public key as `NEXT_PUBLIC_SUPABASE_ANON_KEY` +2. **Dependency conflicts**: + ```bash + # Clear npm cache and reinstall + npm cache clean --force + rm -rf node_modules package-lock.json + npm install + ``` -### AI Integration Setup (Optional) -1. Go to [OpenAI Platform](https://platform.openai.com/) or [Anthropic Console](https://console.anthropic.com/) -2. Create an API key -3. Add to your environment variables +3. **Permission errors** (macOS/Linux): + ```bash + # Fix npm permissions + sudo chown -R $(whoami) ~/.npm + ``` -## Environment Variables +## ๐Ÿ”ง Configuration + +### Environment Variables Create a `.env.local` file in the root directory with the following variables: ```env # Clerk Authentication -NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key -CLERK_SECRET_KEY=your_secret_key +NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... +CLERK_SECRET_KEY=sk_test_... -# Supabase -NEXT_PUBLIC_SUPABASE_URL=your_supabase_url -NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key +# Supabase Database +NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co +NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ... # AI Integration (Optional) -OPENAI_API_KEY=your_openai_api_key -ANTHROPIC_API_KEY=your_anthropic_api_key +OPENAI_API_KEY=sk-... +ANTHROPIC_API_KEY=sk-ant-... ``` -## Features +### Service Setup -- ๐Ÿ” Authentication with Clerk (middleware protection) -- ๐Ÿ—„๏ธ Supabase Database with third-party auth integration -- ๐Ÿค– AI Chat Interface with OpenAI/Anthropic support -- ๐ŸŽจ 40+ shadcn/ui components (New York style) -- ๐ŸŒ™ Dark mode with system preference detection -- ๐ŸŽฏ Built-in setup dashboard with service status -- ๐Ÿš€ App Router with Server Components -- ๐Ÿ”’ Row Level Security examples with Clerk user IDs -- ๐Ÿ“ฑ Responsive design with TailwindCSS v4 -- ๐ŸŽจ Custom fonts (Geist Sans, Geist Mono, Parkinsans) +#### 1. Clerk Setup +1. Go to [Clerk Dashboard](https://dashboard.clerk.com/) +2. Create a new application +3. Go to API Keys and copy your keys +4. Configure the allowed redirect URLs for your domain -## Project Structure +#### 2. Supabase Setup +1. Go to [Supabase Dashboard](https://supabase.com/dashboard) +2. Create a new project +3. Go to Authentication โ†’ Integrations โ†’ Add Clerk (for third-party auth) +4. Copy your project URL and anon key from Project Settings โ†’ API + +#### 3. AI Integration Setup (Optional) +1. Sign up for [OpenAI](https://platform.openai.com/) or [Anthropic](https://console.anthropic.com/) +2. Generate an API key +3. Add to your environment variables for AI-powered summaries + +## ๐Ÿ—๏ธ Project Structure ``` codeguide-starter-kit-lite-v2/ โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ app/ # Next.js app router pages -โ”‚ โ”‚ โ”œโ”€โ”€ api/chat/ # AI chat API endpoint +โ”‚ โ”œโ”€โ”€ app/ # Next.js app router +โ”‚ โ”‚ โ”œโ”€โ”€ api/ # API routes +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ chat/ # AI chat endpoint โ”‚ โ”‚ โ”œโ”€โ”€ globals.css # Global styles with dark mode โ”‚ โ”‚ โ”œโ”€โ”€ layout.tsx # Root layout with providers -โ”‚ โ”‚ โ””โ”€โ”€ page.tsx # Hero + setup dashboard +โ”‚ โ”‚ โ””โ”€โ”€ page.tsx # Home page with status dashboard โ”‚ โ”œโ”€โ”€ components/ # React components -โ”‚ โ”‚ โ”œโ”€โ”€ ui/ # shadcn/ui components (40+) +โ”‚ โ”‚ โ”œโ”€โ”€ ui/ # shadcn/ui components (40+ components) โ”‚ โ”‚ โ”œโ”€โ”€ chat.tsx # AI chat interface -โ”‚ โ”‚ โ”œโ”€โ”€ theme-provider.tsx # Theme context -โ”‚ โ”‚ โ””โ”€โ”€ theme-toggle.tsx # Dark mode toggle +โ”‚ โ”‚ โ”œโ”€โ”€ setup-guide.tsx # Configuration guide +โ”‚ โ”‚ โ”œโ”€โ”€ theme-provider.tsx # Theme context provider +โ”‚ โ”‚ โ””โ”€โ”€ theme-toggle.tsx # Dark mode toggle components โ”‚ โ”œโ”€โ”€ lib/ # Utility functions -โ”‚ โ”‚ โ”œโ”€โ”€ supabase.ts # Supabase client with Clerk auth -โ”‚ โ”‚ โ”œโ”€โ”€ user.ts # User utilities -โ”‚ โ”‚ โ”œโ”€โ”€ utils.ts # General utilities +โ”‚ โ”‚ โ”œโ”€โ”€ utils.ts # Utility functions (cn, etc.) +โ”‚ โ”‚ โ”œโ”€โ”€ supabase.ts # Supabase client configurations +โ”‚ โ”‚ โ”œโ”€โ”€ user.ts # User utilities using Clerk โ”‚ โ”‚ โ””โ”€โ”€ env-check.ts # Environment validation -โ”‚ โ””โ”€โ”€ middleware.ts # Clerk route protection +โ”‚ โ””โ”€โ”€ middleware.ts # Clerk authentication middleware โ”œโ”€โ”€ supabase/ -โ”‚ โ””โ”€โ”€ migrations/ # Database migrations with RLS examples -โ”œโ”€โ”€ CLAUDE.md # AI coding agent documentation +โ”‚ โ””โ”€โ”€ migrations/ # Database migrations +โ”œโ”€โ”€ components.json # shadcn/ui configuration +โ”œโ”€โ”€ CLAUDE.md # AI assistant context +โ”œโ”€โ”€ CONTRIBUTING.md # Contribution guidelines โ”œโ”€โ”€ SUPABASE_CLERK_SETUP.md # Integration setup guide -โ””โ”€โ”€ components.json # shadcn/ui configuration +โ””โ”€โ”€ public/ # Static assets +``` + +## ๐ŸŽฏ Usage + +### Getting Started +1. **Setup Environment**: Follow the installation steps above +2. **Run the Application**: Start the development server with `npm run dev` +3. **Check Status**: Visit `http://localhost:3000` to see setup status +4. **Configure Services**: Use the dashboard links to set up Clerk, Supabase, and AI services + +### AI Chat Interface +1. **Sign In**: Authenticate with Clerk to access AI features +2. **Start Chatting**: Use the integrated chat interface to interact with AI +3. **Ask Questions**: Get help with development, coding, or project setup + +### Building Your Application +- **Authentication**: Routes are automatically protected with Clerk middleware +- **Database**: Use the pre-configured Supabase client with RLS policies +- **UI Components**: Leverage 40+ shadcn/ui components +- **Styling**: Customize themes and styles with TailwindCSS v4 +- **AI Integration**: Add AI features using the Vercel AI SDK + +## ๐Ÿ”Œ API Documentation + +The starter kit provides a foundation for building API endpoints. Currently included: + +### Authentication + +All API endpoints can use Clerk authentication. Include the authorization header: + +```bash +Authorization: Bearer +``` + +### Available Endpoints + +#### AI Chat Integration +```http +POST /api/chat +``` + +**Request Body:** +```json +{ + "messages": [ + { + "role": "user", + "content": "Help me understand Next.js App Router" + } + ] +} +``` + +**Response:** +- Streaming AI response using Vercel AI SDK +- Supports both OpenAI and Anthropic models +- Requires authentication via Clerk + +### Extending the API + +The starter kit provides patterns for adding your own API endpoints: + +1. **Create API Routes**: Add files to `src/app/api/` +2. **Authentication**: Use Clerk's `auth()` helper for protected routes +3. **Database Integration**: Use the pre-configured Supabase client +4. **Type Safety**: Leverage TypeScript for request/response types + +**Example API Route:** +```typescript +// src/app/api/users/route.ts +import { auth } from '@clerk/nextjs' +import { createSupabaseServerClient } from '@/lib/supabase' + +export async function GET() { + const { userId } = auth() + if (!userId) { + return new Response('Unauthorized', { status: 401 }) + } + + const supabase = await createSupabaseServerClient() + const { data, error } = await supabase + .from('users') + .select('*') + .eq('user_id', userId) + + return Response.json({ data, error }) +} +``` + +## ๐Ÿ”ง Troubleshooting + +### Common Issues and Solutions + +#### Authentication Issues + +**Problem**: Clerk authentication not working +```bash +Error: Clerk: Missing publishable key ``` -## Database Integration +**Solution**: +1. Verify your Clerk keys in `.env.local` +2. Ensure keys start with the correct prefixes: + - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` starts with `pk_test_` or `pk_live_` + - `CLERK_SECRET_KEY` starts with `sk_test_` or `sk_live_` +3. Restart your development server after adding keys -This starter includes modern Clerk + Supabase integration: +**Problem**: Redirects not working after authentication +**Solution**: +1. Check your Clerk dashboard settings +2. Add your domain to allowed redirect URLs +3. For local development, include `http://localhost:3000` -- **Third-party auth** (not deprecated JWT templates) -- **Row Level Security** policies using `auth.jwt() ->> 'sub'` for Clerk user IDs -- **Example migrations** with various RLS patterns (user-owned, public/private, collaboration) -- **Server-side client** with automatic Clerk token handling +#### Database Issues -## AI Coding Agent Integration +**Problem**: Supabase connection failed +```bash +Error: Invalid Supabase URL or anon key +``` + +**Solution**: +1. Verify your Supabase project URL and anon key +2. Check if your Supabase project is active +3. Ensure RLS (Row Level Security) policies are properly configured +4. Test connection with the Supabase dashboard + +**Problem**: Database migrations not working +```bash +Error: relation "posts" does not exist +``` + +**Solution**: +```bash +# Reset and re-run migrations +supabase db reset +npx supabase db push +``` + +#### API Issues + +**Problem**: GitHub API rate limiting +```bash +Error: API rate limit exceeded +``` + +**Solution**: +1. Ensure you have a valid GitHub token in your environment variables +2. Use a personal access token for higher rate limits +3. Implement caching for frequently accessed data +4. Consider implementing retry logic with exponential backoff + +**Problem**: AI features not working +```bash +Error: OpenAI API key invalid +``` + +**Solution**: +1. Verify your API key is correct and active +2. Check your API usage limits and billing +3. Ensure the API key has the necessary permissions +4. Try switching between OpenAI and Anthropic providers + +#### Build and Development Issues + +**Problem**: Next.js build fails +```bash +Error: Type error in components +``` + +**Solution**: +```bash +# Check TypeScript errors +npm run lint +npx tsc --noEmit + +# Clear Next.js cache +rm -rf .next +npm run dev +``` + +**Problem**: Styling issues with Tailwind CSS +**Solution**: +1. Ensure Tailwind CSS is properly configured +2. Check if PostCSS config is correct +3. Verify `globals.css` imports +4. Clear browser cache and restart development server + +#### Performance Issues + +**Problem**: Slow search results +**Solution**: +1. Implement search result caching +2. Add pagination to limit results per page +3. Use debouncing for search input +4. Optimize API calls with proper error handling + +**Problem**: Large bundle size +**Solution**: +```bash +# Analyze bundle size +npm install -g @next/bundle-analyzer +ANALYZE=true npm run build +``` + +### Getting Help + +If you're still experiencing issues: + +1. **Check the logs**: Look at browser console and terminal output +2. **Search existing issues**: Check [GitHub Issues](https://github.com/RafiulM/codeguide-starter-kit-lite-v2/issues) +3. **Create a new issue**: Include error messages, steps to reproduce, and environment details +4. **Join discussions**: Participate in [GitHub Discussions](https://github.com/RafiulM/codeguide-starter-kit-lite-v2/discussions) + +### Debug Mode + +Enable debug mode for more detailed logging: + +```bash +# Add to your .env.local +DEBUG=true +NODE_ENV=development +``` + +## ๐Ÿค Contributing + +We welcome contributions! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to submit pull requests, report issues, and contribute to the project. + +## ๐Ÿ“„ License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## ๐Ÿš€ Performance & Deployment + +### Performance Optimizations -This starter is optimized for AI coding agents: +Git Search is built with performance in mind: -- **`CLAUDE.md`** - Comprehensive project context and patterns -- **Setup guides** with detailed integration steps -- **Example migrations** with RLS policy templates -- **Clear file structure** and naming conventions -- **TypeScript integration** with proper type definitions +- **Server-Side Rendering (SSR)**: Fast initial page loads with Next.js App Router +- **Static Generation**: Pre-built pages for better SEO and performance +- **Image Optimization**: Automatic image compression and lazy loading +- **Code Splitting**: Automatic bundle splitting for faster loading +- **Caching Strategy**: Redis/in-memory caching for API responses +- **Database Optimization**: Efficient queries with proper indexing -## Documentation Setup +### Deployment Options -To implement the generated documentation from CodeGuide: +#### Vercel (Recommended) -1. Create a `documentation` folder in the root directory: +1. **Connect your repository**: + - Fork this repository + - Connect to Vercel dashboard + - Import your forked repository + +2. **Environment Variables**: + - Add all required environment variables in Vercel dashboard + - Use production values for Clerk, Supabase, and API keys + +3. **Deploy**: ```bash - mkdir documentation + # Automatic deployment on every push to main branch + git push origin main ``` -2. Place all generated markdown files from CodeGuide in this directory: +#### Docker Deployment + +```dockerfile +# Dockerfile included in repository +FROM node:18-alpine +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production +COPY . . +RUN npm run build +EXPOSE 3000 +CMD ["npm", "start"] +``` + +**Build and run**: +```bash +docker build -t codeguide-starter . +docker run -p 3000:3000 --env-file .env.local codeguide-starter +``` + +#### Self-Hosted Deployment + +1. **Build the application**: ```bash - # Example structure - documentation/ - โ”œโ”€โ”€ project_requirements_document.md - โ”œโ”€โ”€ app_flow_document.md - โ”œโ”€โ”€ frontend_guideline_document.md - โ””โ”€โ”€ backend_structure_document.md + npm run build ``` -3. These documentation files will be automatically tracked by git and can be used as a reference for your project's features and implementation details. +2. **Start production server**: + ```bash + npm start + ``` + +3. **Process Manager (PM2)**: + ```bash + npm install -g pm2 + pm2 start npm --name "codeguide-starter" -- start + pm2 save + pm2 startup + ``` + +### Environment-Specific Configuration + +#### Production Checklist + +- [ ] Set `NODE_ENV=production` +- [ ] Use production API keys (Clerk, Supabase, etc.) +- [ ] Enable HTTPS +- [ ] Configure proper CORS settings +- [ ] Set up monitoring and logging +- [ ] Configure database backups +- [ ] Set up CI/CD pipeline +- [ ] Enable rate limiting +- [ ] Configure CDN for static assets + +#### Security Considerations + +- Use environment variables for all sensitive data +- Enable HTTPS in production +- Configure proper CORS policies +- Implement rate limiting +- Regular security updates +- Monitor for vulnerabilities + +### Monitoring and Analytics + +Recommended tools for production monitoring: + +- **Performance**: Vercel Analytics, Google PageSpeed Insights +- **Error Tracking**: Sentry, LogRocket +- **Uptime Monitoring**: Pingdom, UptimeRobot +- **User Analytics**: Plausible, Google Analytics + +## ๐Ÿ™ Acknowledgments + +- Built with [Next.js](https://nextjs.org/) and [React](https://reactjs.org/) +- UI components from [shadcn/ui](https://ui.shadcn.com/) +- Authentication by [Clerk](https://clerk.com/) +- Database powered by [Supabase](https://supabase.com/) +- AI capabilities by [OpenAI](https://openai.com/) and [Anthropic](https://anthropic.com/) + +## ๐Ÿ“ž Support & Community + +### Get Help + +- ๐Ÿ› **Bug Reports**: [GitHub Issues](https://github.com/RafiulM/codeguide-starter-kit-lite-v2/issues) +- ๐Ÿ’ฌ **Discussions**: [GitHub Discussions](https://github.com/RafiulM/codeguide-starter-kit-lite-v2/discussions) +- ๐Ÿ“– **Documentation**: [Wiki](https://github.com/RafiulM/codeguide-starter-kit-lite-v2/wiki) +- ๐Ÿ’ก **Feature Requests**: [Enhancement Issues](https://github.com/RafiulM/codeguide-starter-kit-lite-v2/issues/new?template=feature_request.md) + +### Connect with the Community + +- ๐ŸŒŸ **Star the repo** if you find it useful +- ๐Ÿด **Fork** to contribute your improvements +- ๐Ÿ‘ฅ **Follow** [@RafiulM](https://github.com/RafiulM) for updates +- ๐Ÿ“ฑ **Share** with your developer friends + +### Support the Project + +If Git Search has been helpful to you, consider: + +- โญ **Starring the repository** +- ๐Ÿ› **Reporting bugs** and issues +- ๐Ÿ’ป **Contributing code** improvements +- ๐Ÿ“ **Improving documentation** +- ๐Ÿ’ฌ **Helping others** in discussions + +--- + +
+ +**Happy searching! ๐Ÿ”โœจ** -## Contributing +*Built with โค๏ธ by [RafiulM](https://github.com/RafiulM)* -Contributions are welcome! Please feel free to submit a Pull Request. \ No newline at end of file +
\ No newline at end of file