docs

Documentation Index

Welcome to the Flywheel Next.js + Supabase Starter documentation! This guide will help you understand and use all features of this template.

📚 Documentation Structure

Getting Started

Perfect for newcomers and those setting up the project for the first time.

→ Getting Started Guide

• Prerequisites and requirements
• Installation steps
• Environment configuration
• First run and verification
• Troubleshooting common issues

Architecture

Understand the project structure and design patterns.

→ Architecture Guide

• Project structure explained
• Layer architecture
• Design patterns used
• Data flow
• Component organization
• Performance optimizations

Supabase Integration

Learn how to work with Supabase database and authentication.

→ Supabase Guide

• Client architecture (browser, server, anonymous)
• RPC Pattern - Recommended approach
• Creating PostgreSQL functions
• Real-time subscriptions
• Storage utilities
• Authentication patterns
• Best practices

Custom Hooks

Master the custom React hooks provided in the starter.

→ Hooks Documentation

• useAuth - Authentication state
• useTheme - Dark/light mode
• useIsMobile - Responsive design
• Creating your own hooks
• Hook patterns and best practices

UI Components

Explore ShadCN UI components and how to use them.

→ UI Components Guide

• What is ShadCN UI?
• Installed components
• Adding new components
• Component examples
• Customization guide
• Theming

Git Workflow

Learn the professional Git workflow with automated validation.

→ Git Workflow Guide

• Conventional Commits - Commit message format
• Husky - Git hooks setup
• Commitlint - Commit validation
• Release-it - Automated releases
• Creating releases
• CHANGELOG generation
• Complete workflow examples

🎯 Quick Navigation by Task

I want to...

Get Started

• Set up the project: Getting Started → Installation
• Configure Supabase: Getting Started → Set Up Supabase
• Run the dev server: Getting Started → Run Development Server

Work with Database

• Create database functions: Supabase → Database Functions
• Call RPC functions: Supabase → RPC Pattern
• Real-time updates: Supabase → Real-time Subscriptions
• Upload files: Supabase → Storage

Build UI

• Add new components: UI Components → Adding New Components
• Customize theme: UI Components → Customization
• Component examples: UI Components → Component Examples

Manage State

• Use authentication: Hooks → useAuth
• Theme switching: Hooks → useTheme
• Mobile detection: Hooks → useIsMobile
• Create custom hook: Hooks → Creating Custom Hooks

Git and Releases

• Commit changes: Git Workflow → Conventional Commits
• Create a release: Git Workflow → Release-it
• Setup git hooks: Git Workflow → Husky

📖 Reading Order

For Beginners

1. Getting Started - Set up your development environment
2. Architecture - Understand the project structure
3. UI Components - Learn to build interfaces
4. Hooks - Manage state and logic
5. Supabase - Work with database
6. Git Workflow - Professional development workflow

For Experienced Developers

1. Architecture - Review design patterns
2. Supabase - RPC pattern and best practices
3. Git Workflow - Commit conventions and releases
4. Getting Started - Quick setup reference

🔍 Find by Technology

Next.js

• Architecture → App Router
• Architecture → Server Components
• Architecture → Performance

React

• Hooks → Custom Hooks
• Architecture → Component Patterns
• UI Components → Examples

TypeScript

• Architecture → Type Safety
• Supabase → TypeScript Types
• Hooks → Typing Hooks

Supabase

• Supabase → Complete Guide
• Supabase → RPC Pattern
• Supabase → Real-time

Tailwind CSS

• UI Components → ShadCN UI
• UI Components → Customization
• Hooks → useIsMobile

Git

• Git Workflow → Complete Guide
• Git Workflow → Conventional Commits
• Git Workflow → Releases

💡 Common Tasks

Authentication Tasks

// Check if user is logged in
import { useAuth } from '@/hooks/use-auth';
const { user } = useAuth();

// Get user in server component
import { createClient } from '@/lib/supabase/core/server';
const supabase = await createClient();
const {
  data: { user },
} = await supabase.auth.getUser();

Learn more: Hooks → useAuth | Supabase → Authentication

Database Queries

// RECOMMENDED: Call PostgreSQL functions via RPC
const { data } = await supabase.rpc('get_user_notes', {
  p_user_id: userId,
});

// Avoid: Direct queries (less secure, harder to maintain)
// const { data } = await supabase.from('notes').select('*')

Why RPC? Better security, performance, and maintainability.
Learn more: Supabase → RPC Pattern

UI Components

# Add a new component
npx shadcn@latest add card

Learn more: UI Components → Adding Components

Git Commits

# Proper commit format
git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"
git commit -m "docs: update documentation"

Learn more: Git Workflow → Conventional Commits

🆘 Getting Help

Documentation Not Clear?

1. Check the Troubleshooting section
2. Search for your issue in the documentation
3. Check the Additional Resources section

Still Need Help?

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Discord Community: Chat with other developers

📚 Additional Resources

Official Documentation

• Next.js Documentation
• Supabase Documentation
• ShadCN UI
• Tailwind CSS
• TypeScript

Tutorials and Guides

• Next.js App Router Tutorial
• Supabase Quickstart
• React Hooks Guide
• Conventional Commits

Community

• Next.js Discord
• Supabase Discord
• Radix UI Community

🚀 Ready to Start?

Begin with the Getting Started Guide and follow the setup instructions!

---

Need to contribute? Check our Contributing Guide

Found an issue? Report it on GitHub

Have a question? Start a discussion