zaid.marzguioui/myeasycms-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Next.js Supabase V3 (#463)

Browse Source 
Version 3 of the kit:
- Radix UI replaced with Base UI (using the Shadcn UI patterns)
- next-intl replaces react-i18next
- enhanceAction deprecated; usage moved to next-safe-action
- main layout now wrapped with [locale] path segment
- Teams only mode
- Layout updates
- Zod v4
- Next.js 16.2
- Typescript 6
- All other dependencies updated
- Removed deprecated Edge CSRF
- Dynamic Github Action runner
This commit is contained in:
Giancarlo Buomprisco
2026-03-24 13:40:38 +08:00
committed by GitHub
parent 4912e402a3
commit 7ebff31475
840 changed files with 71395 additions and 20095 deletions
Download Patch File Download Diff File Expand all files Collapse all files

439
docs/installation/ai-agents.mdoc Normal file
View File

@@ -0,0 +1,439 @@
---
status: "published"
title: "AI Agentic Development | Next.js Supabase Turbo"
label: "AI Agentic Development"
order: 11
description: "Configure Claude Code, Cursor, Windsurf, and other AI coding assistants to work effectively with the Next.js Supabase Turbo SaaS Starter Kit."
---
AI Agentic Development uses AI coding assistants like Claude Code or Cursor to write code within your project. MakerKit ships with instruction files (`AGENTS.md`, `CLAUDE.md`) that teach these AI agents your codebase patterns, available skills, and project conventions so they generate code matching your architecture.
The kit includes pre-configured agent rules for Claude Code, Cursor, Windsurf, Codex, and Gemini. In our extensive testing with state-of-the-art agents like Claude Code, we found that modern tools already crawl existing patterns and learn from your codebase. With a polished codebase like MakerKit, agents have the context they need to produce good code without exhaustive API documentation.
{% sequence title="AI Agent Setup" description="Get AI agents working with your MakerKit codebase." %}
[Understand the Agent Files](#agent-configuration-files)
[Configure Your Editor](#editor-configuration)
[Add the MCP Server](#mcp-server-optional)
[Customize Rules for Your App](#customizing-rules)
{% /sequence %}
## Agent Configuration Files
MakerKit uses a hierarchical system of instruction files. Global rules live at the project root, and package-specific rules live in subdirectories.
### File Locations
| File | Purpose | Used By |
|------|---------|---------|
| `AGENTS.md` | Primary agent instructions | Cursor, Windsurf |
| `CLAUDE.md` | Claude-specific instructions | Claude Code |
| `.gemini/GEMINI.md` | Gemini instructions | Gemini |
### Hierarchical Structure
AI agents read instructions from multiple files based on context. When you work in `apps/web`, the agent reads:
1. Root `AGENTS.md` (global patterns, commands, tech stack)
2. `apps/web/AGENTS.md` (route organization, component patterns)
3. `apps/web/supabase/AGENTS.md` (database migrations, RLS policies)
This hierarchy means agents get more specific instructions as they work deeper in the codebase.
```
AGENTS.md # Global: tech stack, commands, patterns
├── apps/web/AGENTS.md # App: routes, components, config files
│ ├── apps/web/supabase/AGENTS.md # Database: schemas, migrations, RLS
│ └── apps/web/app/admin/AGENTS.md # Admin: super admin features
├── packages/ui/AGENTS.md # UI: components, design system
├── packages/supabase/AGENTS.md # Supabase: clients, auth, types
├── packages/features/AGENTS.md # Features: feature packages
└── packages/next/AGENTS.md # Next.js: actions, routes, utilities
```
### What Agents Learn
The root `AGENTS.md` teaches agents:
- **Tech stack**: Next.js 16, React 19, Supabase, Tailwind CSS 4, Turborepo
- **Multi-tenant architecture**: Personal accounts vs team accounts, account_id foreign keys
- **Essential commands**: `pnpm dev`, `pnpm typecheck`, `pnpm supabase:web:reset`
- **Key patterns**: Server Actions with `authActionClient`, Route Handlers with `enhanceRouteHandler`
- **Authorization**: RLS enforces access control, admin client bypasses RLS
Package-specific files add context for that area:
```markdown
# packages/supabase/AGENTS.md
## Client Usage
### Server Components (Preferred)
import { getSupabaseServerClient } from '@kit/supabase/server-client';
const client = getSupabaseServerClient();
// RLS automatically enforced
### Admin Client (Use Sparingly)
import { getSupabaseServerAdminClient } from '@kit/supabase/server-admin-client';
// CRITICAL: Bypasses RLS - validate manually!
```
## Editor Configuration
### Claude Code
Claude Code reads `CLAUDE.md` files automatically. The root file references `@AGENTS.md` to include those instructions.
No configuration needed. Start Claude Code in your project directory:
```bash
claude
```
Claude Code discovers and reads the instruction files on startup.
### Cursor
Cursor reads `AGENTS.md` files automatically when you open a project. The agent instructions appear in context when you use Cursor's AI features.
For the best experience:
1. Open the project root in Cursor (not a subdirectory)
2. The agent rules load automatically
3. Use Cmd+K or the chat panel to interact with the agent
### Windsurf
Windsurf uses the same `AGENTS.md` files as Cursor. Open your project and the rules apply automatically.
### Codex
Codex reads `AGENTS.md` files. Open the project root and the agent instructions apply to generated code.
### Gemini
Gemini reads from `.gemini/GEMINI.md`. This file points to the `AGENTS.md` files:
```markdown
# .gemini/GEMINI.md
- Check for the presence of AGENTS.md files in the project workspace
- There may be additional AGENTS.md in sub-folders with additional specific instructions
```
## MCP Server (Optional)
The Makerkit MCP Server gives AI agents additional tools for working with the codebase. See the [MCP Server documentation](./mcp) for setup instructions.
MCP tools help agents:
- Understand the project structure
- Navigate between related files
- Apply MakerKit-specific patterns
## Customizing Rules
The default rules cover MakerKit patterns. Add your own rules for application-specific logic.
### Adding Business Logic Rules
Create or edit `AGENTS.md` files to include your domain knowledge:
```markdown
# apps/web/AGENTS.md (add to existing file)
## Business Logic
### Subscription Tiers
- Free: 1 team member, 3 projects
- Pro: 10 team members, unlimited projects
- Enterprise: Unlimited everything, SSO
### Project Limits
Check limits before creating projects:
- Use `checkProjectLimit(accountId)` from `~/lib/server/projects`
- Returns { allowed: boolean, current: number, limit: number }
### Naming Conventions
- Projects use kebab-case slugs: "my-project-name"
- Team accounts use slugs, not IDs, in URLs
```
### What Makes Effective Agent Rules
In our testing, we noticed that adding detailed API instructions to agent rules has diminishing returns. Modern agents like Claude Code crawl your existing code, learn the patterns, and apply them. What actually moves the needle:
1. **Must-do rules**: Things the agent should always do
2. **Must-not-do rules**: Things the agent should never do
3. **Router instructions**: Where to find things the agent needs
```markdown
# apps/web/AGENTS.md (add to existing file)
## MUST DO
- Always use `authActionClient` for Server Actions
- Always enable RLS on new tables
- Always run `pnpm typecheck` after changes
- Always use the `Trans` component for user-facing text
## MUST NOT DO
- Never use the admin client without manual auth validation
- Never commit .env files or secrets
- Never use `any` type in TypeScript
- Never skip RLS policies on tables with user data
## Where to Find Things
- Auth patterns: `packages/supabase/src/clients/`
- UI components: `packages/ui/src/`
- Billing logic: `packages/billing/`
- Database schemas: `apps/web/supabase/schemas/`
```
This approach works better than documenting every API because agents learn APIs from code, but they need explicit guidance on project-specific constraints and conventions.
### Adding Feature Flags
Document which features are gated so agents know what's available:
```markdown
## Feature Flags
Check `config/feature-flags.config.ts` for current flags:
- `enableTeamAccounts`: Team workspaces enabled
- `enableTeamCreation`: Users can create new teams
- `enableTeamAccountBilling`: Team billing enabled
- `enablePersonalAccountBilling`: Personal account billing enabled
- `enableNotifications`: In-app notifications enabled
Import the config directly:
import featureFlags from '~/config/feature-flags.config';
if (featureFlags.enableTeamCreation) { /* ... */ }
```
## Claude Code Directory Structure
Claude Code uses a `.claude/` directory for additional configuration:
```
.claude/
├── agents/ # Custom agent definitions
│ └── code-quality-reviewer.md
├── commands/ # Slash commands
│ └── feature-builder.md
├── evals/ # Evaluation scripts
├── skills/ # Reusable skills
│ ├── playwright-e2e/
│ ├── postgres-expert/
│ ├── react-form-builder/
│ └── server-action-builder/
└── settings.local.json # Local permissions (git-ignored)
```
## Built-in Skills
The kit includes skills for Claude Code that provide specialized guidance for common tasks.
{% callout title="Skills may require explicit invocation" %}
Claude can automatically invoke skills based on the context of the conversation. However, you can also explicitly invoke skills by typing the skill name at the start of your message when you need specialized guidance, such as '/postgres-supabase-expert' "review the database schema for the projects feature".
{% /callout %}
| Skill | Command | Purpose |
|-------|---------|---------|
| Postgres & Supabase Expert | `/postgres-supabase-expert` | Database schemas, RLS policies, migrations, PgTAP tests |
| Server Action Builder | `/server-action-builder` | Server Actions with validation and error handling |
| React Form Builder | `/react-form-builder` | Forms with Zod validation and Shadcn UI |
| Playwright E2E | `/playwright-e2e` | End-to-end test patterns |
### Using Skills
Invoke a skill by typing its command at the start of your message:
```
/postgres-supabase-expert Create a projects table with RLS policies for team access
```
```
/server-action-builder Create an action to update user settings
```
### Feature Builder Command
The `/feature-builder` command orchestrates multiple skills for end-to-end feature implementation:
```
/feature-builder Add a projects feature with CRUD operations
```
This command guides you through:
1. Database schema with `/postgres-supabase-expert`
2. Server Actions with `/server-action-builder`
3. Forms with `/react-form-builder`
## Adding External Skills
The [Agent Skills](https://github.com/vercel-labs/agent-skills) project provides additional skills you can install:
```bash
npx add-skill vercel-labs/agent-skills
```
Available skills:
- **[react-best-practices](https://vercel.com/blog/introducing-react-best-practices)**: Performance optimization guidelines from Vercel Engineering (40+ rules across 8 categories)
- **web-design-guidelines**: UI audit with accessibility checks (100+ rules covering accessibility, performance, UX)
- **vercel-deploy-claimable**: Deploy directly from conversations with live preview URLs
## Verification Workflow
Agents are instructed to run verification after making changes:
```bash
pnpm typecheck # Must pass
pnpm lint:fix # Auto-fix issues
pnpm format:fix # Format code
```
If an agent skips verification, remind it:
```
Run typecheck and lint:fix to verify the changes
```
## Common Patterns Agents Know
### Server Actions
Agents use `authActionClient` for Server Actions:
```typescript
'use server';
import { authActionClient } from '@kit/next/safe-action';
import * as z from 'zod';
const schema = z.object({
name: z.string().min(1),
});
export const createProjectAction = authActionClient
.inputSchema(schema)
.action(async ({ parsedInput: data, ctx: { user } }) => {
// Implementation
});
```
### Route Handlers
Agents use `enhanceRouteHandler` for API routes:
```typescript
import { enhanceRouteHandler } from '@kit/next/routes';
export const POST = enhanceRouteHandler(
async ({ body, user }) => {
// Implementation
return NextResponse.json({ success: true });
},
{ schema: requestSchema }
);
```
### Database Queries
Agents prefer Server Components with the standard client:
```typescript
import { getSupabaseServerClient } from '@kit/supabase/server-client';
async function ProjectList() {
const client = getSupabaseServerClient();
const { data } = await client.from('projects').select('*');
// RLS enforced automatically
}
```
## Best Practices for Using AI Agents
After extensive use of AI agents with MakerKit, we've identified what works:
### Keep AGENTS.md Files Focused
Long instruction files cause context drift where agents forget earlier rules. Keep each file under 500 lines. Split by concern rather than cramming everything into the root file.
### Use Rules as a Router
Rather than documenting every API, tell agents where to find things:
```markdown
## Where to Look
- Need a UI component? Check `packages/ui/src/` first
- Building a form? See `packages/ui/src/shadcn/form.tsx` for patterns
- Adding a Server Action? Reference `apps/web/app/home/_lib/server/`
```
Agents are excellent at reading code once they know where to look.
### Explicit Constraints Beat Implicit Conventions
"Always use `authActionClient`" works better than "We prefer using authActionClient for most cases." Agents follow explicit rules; they guess at preferences.
### Let Agents Learn from Your Codebase
With a consistent codebase like MakerKit, agents pick up patterns automatically. You don't need to document that Server Components fetch data or that forms use Zod. Focus your rules on project-specific decisions and gotchas.
## Troubleshooting
### Agent Ignores Rules
1. Verify files exist at the expected locations
2. Check file names match exactly (case-sensitive)
3. Restart your editor to reload configuration
### Agent Generates Wrong Patterns
Add explicit examples to your `AGENTS.md`:
```markdown
## Patterns
### CORRECT - Use authActionClient
export const action = authActionClient.inputSchema(schema).action(async ({ parsedInput: data, ctx: { user } }) => {});
### INCORRECT - Raw Server Action
export async function action(data: FormData) {} // Missing validation
```
### Agent Misunderstands Structure
Add a quick reference section:
```markdown
## Quick Reference
- App routes: `apps/web/app/`
- Shared components: `packages/ui/src/`
- Database schemas: `apps/web/supabase/schemas/`
- Feature packages: `packages/features/*/`
```
## Next Steps
- Configure the [MCP Server](./mcp) for enhanced agent capabilities
- Add [LLM rules](./llms) for additional context from documentation
- Review [conventions](./conventions) to understand the patterns agents follow
{% faq
title="Frequently Asked Questions"
items=[
{"question": "Which AI coding tool works best with MakerKit?", "answer": "Claude Code and Cursor have the deepest integration through AGENTS.md and CLAUDE.md files. Both support the hierarchical instruction system and built-in skills. Choose based on your preferred workflow."},
{"question": "Do I need the MCP Server?", "answer": "No, but it helps. The MCP Server gives agents additional tools for understanding the codebase. Agents work without it, but may need more guidance for complex tasks."},
{"question": "How do I update agent rules when I change my app?", "answer": "Edit the relevant AGENTS.md file. Changes apply immediately to new agent sessions. Document your domain logic, API patterns, and feature flags so agents generate code that fits your application."},
{"question": "Can I use multiple AI tools on the same project?", "answer": "Yes. The instruction files work across tools. AGENTS.md covers Cursor, Windsurf, and Codex. CLAUDE.md adds Claude-specific context. You can switch between tools without reconfiguring."},
{"question": "Why does the agent generate code that doesn't match my patterns?", "answer": "Add explicit examples to your AGENTS.md showing correct and incorrect patterns. Agents learn from examples better than abstract rules. Include the specific imports, function signatures, and patterns you want."},
{"question": "How do skills work with AI agents?", "answer": "Skills are specialized instruction sets you invoke explicitly with /skill-name syntax in Claude Code. For example, /postgres-supabase-expert provides database guidance, /server-action-builder helps with Server Actions."}
]
/%}

217
docs/installation/clone-repository.mdoc Normal file
View File

@@ -0,0 +1,217 @@
---
status: "published"
title: "Clone the Next.js Supabase SaaS Kit Repository"
label: "Clone the Repository"
order: 4
description: "Set up your development environment and clone the Next.js Supabase SaaS Kit Turbo repository."
---
{% sequence title="Setup Steps" description="Get your development environment ready and clone the repository." %}
[Install prerequisites](#prerequisites)
[Clone the repository](#cloning-the-repository)
[Install dependencies](#install-dependencies)
[Configure Git remotes](#configure-git-remotes)
{% /sequence %}
## Prerequisites
Before cloning, install these tools:
| Tool | Required Version | Installation |
|------|-----------------|--------------|
| Node.js | **20.10.0+** | [nodejs.org](https://nodejs.org) or use nvm |
| pnpm | **10.19.0+** | `npm i -g pnpm` |
| Docker | Latest | [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
| Git | Latest | [git-scm.com](https://git-scm.com) |
{% alert type="error" title="Node.js Version" %}
The kit requires Node.js 20.10.0 or later. Earlier versions will fail during installation due to engine requirements in package.json.
{% /alert %}
### Verify Your Setup
```bash
node -v # Should output v20.10.0 or higher
pnpm -v # Should output 10.19.0 or higher
docker -v # Should output Docker version
```
### Why Docker?
Supabase runs locally using Docker containers. You don't need to understand Docker internals; just have it running when you start the development server.
**macOS alternatives**: [OrbStack](https://orbstack.dev/) is faster than Docker Desktop and works as a drop-in replacement.
## Cloning the Repository
### Using SSH (recommended)
```bash
git clone git@github.com:makerkit/next-supabase-saas-kit-turbo my-saas
cd my-saas
```
### Using HTTPS
```bash
git clone https://github.com/makerkit/next-supabase-saas-kit-turbo my-saas
cd my-saas
```
If you haven't configured SSH keys, see [GitHub's SSH setup guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
### Windows Users
Place the repository near your drive root (e.g., `C:\projects\my-saas`) to avoid path length issues with Node.js modules.
**Avoid**: OneDrive folders, deeply nested paths, or paths with spaces.
## Install Dependencies
```bash
pnpm i
```
This installs all workspace dependencies across the monorepo. The first install takes a few minutes.
### Warnings in the terminal
You may see the following warnings in the terminal:
```
WARN  Failed to create bin at /vercel/path0/node_modules/.pnpm/node_modules/.bin/supabase. ENOENT: no such file or directory
```
This is just a warning [caused by PNPM and Supabase](https://github.com/supabase/cli/issues/3489) and can be safely ignored.
Another warning you may see is:
```
Ignored build scripts: core-js-pure, sharp, unrs-resolver.
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.
```
This is by design! We don't want to run scripts from dependencies that are not needed for the project to run properly. This is a security precaution.
## Configure Git Remotes
### Automatic Setup (recommended)
Run the setup generator to configure remotes and create your own repository:
```bash
pnpm turbo gen setup
```
This interactive script:
1. Removes the original `origin` remote
2. Adds `upstream` pointing to the MakerKit repository
3. Prompts you to create and connect your own repository
### Manual Setup
If the automatic setup fails or you prefer manual control:
**1. Remove the original origin:**
```bash
git remote rm origin
```
**2. Add upstream for updates:**
```bash
git remote add upstream git@github.com:makerkit/next-supabase-saas-kit-turbo
```
**3. Create your repository on GitHub, then add it as origin:**
```bash
git remote add origin git@github.com:your-username/your-repo.git
git push -u origin main
```
**4. Verify remotes:**
```bash
git remote -v
# origin git@github.com:your-username/your-repo.git (fetch)
# origin git@github.com:your-username/your-repo.git (push)
# upstream git@github.com:makerkit/next-supabase-saas-kit-turbo (fetch)
# upstream git@github.com:makerkit/next-supabase-saas-kit-turbo (push)
```
## Pulling Updates
To get the latest changes from MakerKit:
```bash
git pull upstream main
```
Run this regularly to stay current with bug fixes and new features.
### Automate Post-Merge Dependency Install
Create a Git hook to automatically run `pnpm i` after pulling:
```bash
cat > .git/hooks/post-merge << 'EOF'
#!/bin/bash
pnpm i
EOF
chmod +x .git/hooks/post-merge
```
This prevents the common issue of missing dependencies after pulling updates.
## Common Pitfalls
Avoid these issues that trip up most users:
1. **Wrong Node.js version**: The kit requires Node.js 20.10.0+. Using Node 18 or earlier causes silent failures and missing features.
2. **Docker not running**: Supabase commands hang indefinitely if Docker isn't started. Always open Docker Desktop before running `supabase:web:start`.
3. **Windows long paths**: Node.js modules create deeply nested folders. Place your project near the drive root (e.g., `C:\projects\my-saas`).
4. **OneDrive sync conflicts**: OneDrive can corrupt `node_modules`. Keep your project outside OneDrive-synced folders.
5. **Forgetting to set upstream**: Without the `upstream` remote, you can't pull MakerKit updates. Run `git remote -v` to verify both `origin` and `upstream` exist.
6. **Skipping `pnpm i` after updates**: Pulling changes often adds new dependencies. Always run `pnpm i` after `git pull upstream main`.
## Troubleshooting
### "Permission denied" when cloning
Your SSH key isn't configured. Either:
- Set up SSH keys following [GitHub's guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
- Use HTTPS instead: `git clone https://github.com/makerkit/next-supabase-saas-kit-turbo`
### "Engine requirements not met"
Your Node.js version is too old. Install Node.js 20.10.0+ using nvm:
```bash
nvm install 20
nvm use 20
```
### Git username mismatch
If you encounter permission issues, verify your Git username matches your GitHub account:
```bash
git config user.username
```
Set it if needed:
```bash
git config --global user.username "your-github-username"
```
## Next Steps
With the repository cloned, proceed to [running the project](/docs/next-supabase-turbo/installation/running-project) to start development.

82
docs/installation/code-health.mdoc Normal file
View File

@@ -0,0 +1,82 @@
---
status: "published"
label: "Code Health and Testing"
title: "Code Health and Testing in Next.js Supabase"
order: 10
description: "Learn how to set up Github Actions, pre-commit hooks, and more in Makerkit to ensure code health and quality."
---
Makerkit provides a set of tools to ensure code health and quality in your project. This includes setting up Github Actions, pre-commit hooks, and more.
## Github Actions
By default, Makerkit sets up Github Actions to run tests on every push to the repository. You can find the Github Actions configuration in the `.github/workflows` directory.
The workflow has two jobs:
1. `typescript` - runs the Typescript compiler to check for type errors.
2. `test` - runs the Playwright tests in the `tests` directory.
### Enable E2E Tests
Since it needs some setup - these are not enabled by default. To enable E2E tests, you need to set the following environment variables in the Github Actions workflow:
```bash
ENABLE_E2E_JOB=true
```
### Configuring the E2E environment for Github Actions
To set up Github Actions for your project, please add the following secrets to your repository Github Actions settings:
1. `SUPABASE_SERVICE_ROLE_KEY` - the service role key for Supabase.
2. `SUPABASE_DB_WEBHOOK_SECRET` - the webhook secret for Supabase.
3. `STRIPE_SECRET_KEY` - the secret key for Stripe.
4. `STRIPE_WEBHOOK_SECRET` - the webhook secret for Stripe.
These are the same as the ones you have running the project locally. Don't use real secrets here - use the development app secrets that you use locally. **This is a testing environment**, and you don't want to expose your production secrets.
Additionally, please set the following environment variables in the Github Actions workflow:
1. `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - this is the publishable key for Stripe.
2. `SUPABASE_DB_WEBHOOK_SECRET`: Use the value `WEBHOOKSECRET` for the webhook secret. Again, this is a testing environment, so we add testing values.
### Enable Stripe Tests
Since it needs some setup - these are not enabled by default. To enable Stripe tests, you need to set the following environment variables in the Github Actions workflow:
```bash
ENABLE_BILLING_TESTS=true
```
Of course - make sure you have the Stripe secrets set up in the Github Actions secrets.
## Pre-Commit Hook
It's recommended to set up a pre-commit hook to ensure that your code is linted correctly and passes the typechecker before committing.
### Setting up the Pre-Commit Hook
To do so, create a `pre-commit` file in the `./.git/hooks` directory with the following content:
```bash
#!/bin/sh
pnpm run typecheck
pnpm run lint
```
Turborepo will execute the commands for all the affected packages - while skipping the ones that are not affected.
### Make the Pre-Commit Hook Executable
Now, make the file executable:
```bash
chmod +x ./.git/hooks/pre-commit
```
To test the pre-commit hook, try to commit a file with linting errors or type errors. The commit should fail, and you should see the error messages in the console.
### What about the e2e tests?
You could also add tests - but it'll slow down your commits. It's better to run tests in Github Actions.

177
docs/installation/common-commands.mdoc Normal file
View File

@@ -0,0 +1,177 @@
---
status: "published"
title: 'Essential Commands for the Next.js Supabase SaaS Kit'
label: 'Common Commands'
order: 6
description: 'Quick reference for development, database, testing, and code quality commands in the Next.js Supabase SaaS Kit.'
---
A quick reference for the commands you'll use daily. All commands run from the project root.
## Daily Development
| Command | What It Does |
|---------|-------------|
| `pnpm dev` | Start Next.js dev server + dev tools |
| `pnpm run supabase:web:start` | Start local Supabase |
| `pnpm run supabase:web:stop` | Stop local Supabase |
| `pnpm run stripe:listen` | Forward Stripe webhooks locally |
## Database Operations
### Starting and Stopping
```bash
# Start Supabase (requires Docker running)
pnpm run supabase:web:start
# Stop Supabase
pnpm run supabase:web:stop
```
### Migrations
```bash
# Reset database (re-run all migrations + seed)
pnpm run supabase:web:reset
# Generate types after schema changes
pnpm run supabase:web:typegen
# Run database tests
pnpm run supabase:web:test
```
### Creating New Migrations
After modifying tables in Supabase Studio, create a migration:
```bash
# See what changed
pnpm --filter web supabase db diff
# Create a named migration file
pnpm --filter web supabase db diff -f add-projects-table
```
This creates a new file in `apps/web/supabase/migrations/`.
### Running Supabase CLI Commands
The Supabase CLI is scoped to `apps/web`. To run any Supabase command:
```bash
pnpm --filter web supabase <command>
```
Examples:
```bash
# Link to remote project
pnpm --filter web supabase link --project-ref your-project-ref
# Push migrations to production
pnpm --filter web supabase db push
# Pull remote schema
pnpm --filter web supabase db pull
```
## Code Quality
Run these before committing:
```bash
# Type checking
pnpm typecheck
# Lint and auto-fix
pnpm lint:fix
# Format code
pnpm format:fix
```
Or run all three:
```bash
pnpm typecheck && pnpm lint:fix && pnpm format:fix
```
## Testing
```bash
# Run all tests
pnpm test
# Run E2E tests (requires app running)
pnpm --filter e2e test
```
## Environment Variables
```bash
# Generate environment variables from template
pnpm turbo gen env
# Validate environment variables
pnpm turbo gen validate-env
```
## Cleaning Up
When dependencies get out of sync or caches cause issues:
```bash
# Clean all workspaces
pnpm run clean:workspaces
# Clean root
pnpm run clean
# Reinstall everything
pnpm i
```
## Package Management
```bash
# Install dependencies
pnpm i
# Update all dependencies
pnpm update -r
# Check for version mismatches
pnpm syncpack:list
# Fix version mismatches
pnpm syncpack:fix
```
## Building for Production
```bash
# Build all packages and apps
pnpm build
# Analyze bundle size
pnpm --filter web analyze
```
## Quick Reference Card
```bash
# Start everything
pnpm run supabase:web:start && pnpm dev
# Database workflow
pnpm run supabase:web:reset # Reset to clean state
pnpm run supabase:web:typegen # Update TypeScript types
# Before committing
pnpm typecheck && pnpm lint:fix && pnpm format:fix
# When things break
pnpm run clean:workspaces && pnpm run clean && pnpm i
```

47
docs/installation/conventions.mdoc Normal file
View File

@@ -0,0 +1,47 @@
---
status: "published"
description: "Makerkit uses conventions to ensure consistency and readability in the codebase."
title: "Conventions in the Next.js Supabase Turbo Starter Kit"
label: "Conventions"
order: 3
---
Below are some of the conventions used in the Next.js Supabase Turbo Starter Kit.
**You're not required to follow these conventions**: they're simply a standard set of practices used in the core kit. If you like them - I encourage you to keep these during your usage of the kit - so to have consistent code style that you and your teammates understand.
### Turborepo Packages
In this project, we use Turborepo packages to define reusable code that can be shared across multiple applications.
- **Apps** are used to define the main application, including routing, layout, and global styles.
- Apps pass down configuration to the packages, and the packages provide the corresponding logic and components.
### Creating Packages
**Should you create a package for your app code?**
- **Recommendation:** Do not create a package for your app code unless you plan to reuse it across multiple applications or are experienced in writing library code.
- If your application is not intended for reuse, keep all code in the app folder. This approach saves time and reduces complexity, both of which are beneficial for fast shipping.
- **Experienced developers:** If you have the experience, feel free to create packages as needed.
### Imports and Paths
When importing modules from packages or apps, use the following conventions:
- **From a package:** Use `@kit/package-name` (e.g., `@kit/ui`, `@kit/shared`, etc.).
- **From an app:** Use `~/` (e.g., `~/lib/components`, `~/config`, etc.).
### Non-Route Folders
Non-route folders within the `app` directory are prefixed with an underscore (e.g., `_components`, `_lib`, etc.).
- This prefix indicates that these folders are not routes but are used for shared components, utilities, etc.
### Server Code
Files located in `server` folders are intended for server-side code only. They should not be used in client-side code.
- This convention helps clarify where the code is meant to run, which is particularly important in Next.js where the distinction can be blurry.
- For example, server-related code for a part of the app can be found in the `_lib/server` folder.
- Include the `server-only` package at the top of the file to ensure it is not accidentally imported in client-side code.

77
docs/installation/faq.mdoc Normal file
View File

@@ -0,0 +1,77 @@
---
status: "published"
title: "FAQ - Questions about the Next.js SaaS Boilerplate"
label: "FAQ"
order: 13
description: "Frequently asked questions about the Next.js SaaS Boilerplate."
---
The below is a technical FAQ about this kit. For general questions about Makerkit, please see the [Makerkit FAQ](/faq).
## Technical FAQ
### Do I need to know Supabase to use the Next.js SaaS Boilerplate?
Yes, you should have a basic understanding of Supabase to use the Next.js SaaS Boilerplate. You'll need to know how to:
- Create a Supabase project
- Set up the database
- Understand PostgreSQL
- Use the Supabase client in your Next.js app
While you can use the kit to learn, it does not teach you how to use Supabase. For that, please refer to the [Supabase documentation](https://supabase.com/docs).
### Do I need to know Next.js to use the Next.js SaaS Boilerplate?
Yes, you should have a basic understanding of Next.js to use the Next.js SaaS Boilerplate.
### I don't know Supabase! Should I buy the Next.js SaaS Boilerplate?
You should be prepared for a learning curve or consider learning Supabase first. The Next.js SaaS Boilerplate is built on top of Supabase, so knowing how to use Supabase is essential.
### I don't know Turborepo! Should I buy the Next.js SaaS Boilerplate?
Yes, you can still use the Next.js SaaS Boilerplate without prior knowledge of Turborepo. Turborepo is used to manage the monorepo structure of the boilerplate. Your main focus will be on building your SaaS product within the `apps/web` directory, not on the tools used to build the boilerplate. Even without experience using Turborepo, you won't need to interact with it directly unless you plan to customize the core code in the `packages` directory.
### Will you add more packages in the future?
Very likely! This kit is designed to be modular, allowing for new features and packages to be added without interfering with your existing code. There are many ideas for new packages and features that may be added in the future.
### Can I use this kit for a non-SaaS project?
This kit is primarily intended for SaaS projects. If you're building a non-SaaS project, the Next.js SaaS Boilerplate might be overkill. You can still use it, but you might need to remove some features specific to SaaS projects.
### Can I use personal accounts only?
Yes, you can set a feature flag to disable team accounts and use personal accounts only.
### Can I use the React package X with this kit?
Yes, you can use any React package with this kit. The kit is a simple Next.js application, so you are generally only constrained by the underlying technologies (Next.js, Stripe, Supabase, etc.) and not by the kit itself. Since you own and can edit all the code, you can adapt the kit to your needs. However, if there are limitations with the underlying technology, you might need to work around them.
### Does Makerkit set up the production instance for me?
No, Makerkit does not set up the production instance for you. This includes setting up Supabase, Stripe, and any other services you need. Makerkit does not have access to your Stripe or Supabase accounts, so setup on your end is required. Makerkit provides the codebase and documentation to help you set up your SaaS project.
### How do I get support if I encounter issues?
For support, you can:
1. Visit our Discord
2. Contact us via support email
### Are there any example projects or demos?
Yes - you get access to the OpenAI demo.
### How do I deploy my application?
Please check the [production checklist](../going-to-production/checklist) for more information.
### How do I contribute to the Next.js SaaS Boilerplate?
We welcome contributions! Please ping me if you'd like to contribute (licensees only).
### How do I update my project when a new version of the boilerplate is released?
Please [read the documentation for updating your Makerkit project](updating-codebase).

282
docs/installation/functional-walkthrough.mdoc Normal file
View File

@@ -0,0 +1,282 @@
---
status: "published"
title: 'Functional Walkthrough - Next.js Supabase Turbo Starter Kit'
label: 'Walkthrough'
order: 8
description: 'A functional walkthrough of the Next.js Supabase Turbo Starter Kit. Understand the features and how to use the kit.'
---
This is a functional walkthrough of the Next.js Supabase Turbo Starter Kit. In this guide, you'll learn about the functional aspects of the kit.
## Overview of the Next.js Supabase Turbo Starter Kit
We can break down the Next.js Supabase Turbo Starter Kit into the following functional sections:
1. **Marketing / External Section** - the public-facing part of the application. This also includes the blog and documentation.
2. **Authentication** - the authentication system of the application.
3. **Personal Account Features** - the features available to personal accounts.
4. **Team Account Features** - the features available to team accounts.
5. **Invitations** - the invitation system of the application.
6. **Super Admin** - the super admin features of the application.
## Marketing / External Section
The marketing section is the public-facing part of the application. It is where users can learn about the product, the pricing and the legal information.
### Home Page
The home page is the landing page of the application. It showcases the features of the product and encourages users to sign up.
{% img src="/assets/images/docs/walkthrough/home-page.webp" width="3420" height="2142" /%}
### Pricing
The pricing page is where users can learn about the different pricing plans of the product.
{% img src="/assets/images/docs/walkthrough/pricing.webp" width="3420" height="2142" /%}
This section is also added to the home page.
### FAQ
The FAQ page is where users can find answers to common questions about the product.
{% img src="/assets/images/docs/walkthrough/faq.webp" width="3420" height="2142" /%}
### Contact
The contact page is where users can get in touch with the company. It includes a contact form that allows users to send messages to the company directly.
{% img src="/assets/images/docs/walkthrough/contact.webp" width="3420" height="2142" /%}
### Content Pages
Content pages can be displayed using the CMS that you have setup. By default, the kit implements a Blog and a Documentation systems using either Keystatic or Wordpress. You can choose which one you prefer.
#### Blog
The blog is where the company can publish articles about the product, the industry, and other topics.
Below is the page where all the latest blog posts are listed:
{% img src="/assets/images/docs/walkthrough/blog.webp" width="3420" height="2142" /%}
And here is an example of a blog post:
{% img src="/assets/images/docs/walkthrough/blog-post.webp" width="3420" height="2142" /%}
#### Documentation
The documentation is where users can learn how to use the product. It includes guides, tutorials, and reference material.
{% img src="/assets/images/docs/walkthrough/walkthrough-documentation.webp" width="3420" height="2142" /%}
### Legal Pages
The legal pages are, of course, empty and need to be filled in with the appropriate legal information.
Don't use ChatGPT to fill them up. It's a bad idea.
## Authentication
The authentication system is where users can sign up, sign in, reset their password. It also includes multi-factor authentication.
### Sign Up
The sign-up page is where users can create an account. They need to provide their email address and password.
{% img src="/assets/images/docs/walkthrough/sign-up.webp" width="3420" height="2142" /%}
Once successful, users are asked to confirm their email address. This is enabled by default - and due to security reasons, it's not possible to disable it.
{% img src="/assets/images/docs/walkthrough/sign-up-success.webp" width="3420" height="2142" /%}
### Sign In
The sign-in page is where users can log in to their account. They need to provide their email address and password.
{% img src="/assets/images/docs/walkthrough/sign-in.webp" width="3420" height="2142" /%}
### Password Reset
The password reset page is where users can reset their password. They need to provide their email address.
{% img src="/assets/images/docs/walkthrough/password-reset.webp" width="3420" height="2142" /%}
### Multi-Factor Authentication
Multi-Factor Authentication (MFA) is an additional layer of security that requires users to provide two or more verification factors to sign in to their account.
First, users need to enable MFA and add a factor:
{% img src="/assets/images/docs/walkthrough/setup-mfa.webp" width="3420" height="2142" /%}
Then, after signing in, users need to provide the verification code:
{% img src="/assets/images/docs/walkthrough/verify-mfa.webp" width="3420" height="2142" /%}
## Internal / Behind authentication pages
After signing in - users are redirected to the internal pages of the application. These pages are only accessible to authenticated users.
The internal part of the application is divided into two workspaces:
1. The user workspace
2. The team workspace (optional)
This is how this works:
1. **Personal Account** - all users have a personal account. This is where they can: manage their settings, choose a team account - and **optionally** subscribe to a plan, or access the features you provide.
2. **Team Account (optional)** - users can create a team account - and invite other users to join. The team account has its own workspace - where users can manage the team settings, members, and billing.
Generally speaking, **it's up to you** to decide what features are available to personal accounts and team accounts. You can choose to disable billing for personal accounts - and only enable it for team accounts - or vice versa.
One simple rule of a thumb is that personal accounts are for individuals - and team accounts are for organizations. Personal accounts cannot be disabled, as that would disallow users from accessing the application should they not be part of a team - which doesn't make sense.
## Personal Account Features
The personal account workspace is where users can access the features available to their personal account.
This is the home page after logging in - and it's the user workspace:
1. Home Page - empty by default (but you can optionally provide the list of teams the user is part of)
2. Account Settings
3. Billing (if enabled)
### Home Page of the user workspace
By default - the user home is an empty page - as it's likely you will want to place some content that is unique to your SaaS.
However, we provide a component that allows you to lists the team an account is part of: this is useful for B2B SaaS rather than B2C.
The internal pages have two layouts:
1. A sidebar layout (default)
2. A top navigation layout
You can choose any of the two - and also choose either one for the user layout or the account layout.
Below is the user home page with the sidebar layout:
{% img src="/assets/images/docs/walkthrough/user-home-sidebar.webp" width="3420" height="2142" /%}
And below is the user home page with the top navigation layout:
{% img src="/assets/images/docs/walkthrough/user-home-header.webp" width="3420" height="2142" /%}
You can choose the one that fits your needs.
### Account Settings of the user workspace
From the navigation - users can access their account settings. Here they can update their profile information, change their password, language, multi-factor authentication, and more.
We've used light mode so far - how about dark mode? Let's switch to dark mode:
{% img src="/assets/images/docs/walkthrough/user-account-settings.webp" width="3420" height="2142" /%}
### Billing of the user workspace
Users can check out and subscribe to a plan - or visit the billing portal - from the billing page.
**This is only visible if billing is enabled**: you can choose to disable billing for a personal account - and only enable it for team accounts - or vice versa.
{% img src="/assets/images/docs/walkthrough/user-billing.webp" width="3420" height="2142" /%}
Once choosing a plan - we load the embedded checkout form from Stripe (or Lemon Squeezy).
After subscribing, the billing page will show the subscription details.
{% img src="/assets/images/docs/walkthrough/user-billing-plan.webp" width="3420" height="2142" /%}
## Team Account Features
From the profile dropdown, users can choose:
1. Switch to a team account
2. Create a team account
{% img src="/assets/images/docs/walkthrough/user-profile-dropdown.webp" width="876" height="796" /%}
In a team account workspace - users can access the following features:
1. A team account home page: by default - we display a mock dashboard, just as an example.
2. Account settings: users can update the team account settings.
3. Members: users can view the members of the team account.
4. Billing: users can view the billing of the team account.
### Home Page of the team workspace
By default - the team home is a mock dashboard - just as an example. You can replace this with your own dashboard - or any other content.
{% img src="/assets/images/docs/walkthrough/team-account-dashboard.webp" width="3420" height="2142" /%}
### Account Settings of the team workspace
From the navigation - users can access the team account settings. Here they can update the team account information, or delete the team account (if owner), or leave the team account (if member).
{% img src="/assets/images/docs/walkthrough/team-account-settings.webp" width="3420" height="2142" /%}
### Members page of the team workspace
From the navigation - users can access the members of the team account.
Here they can:
1. view the members
2. invite new members
3. remove or update an existing member
4. transfer ownership to another member
5. remove or update an invitation
{% img src="/assets/images/docs/walkthrough/team-account-members.webp" width="3420" height="2142" /%}
### Billing of the team workspace
If enabled - users can view the billing of the team account - and subscribe to a plan or visit the billing portal.
{% img src="/assets/images/docs/walkthrough/team-account-billing.webp" width="3420" height="2142" /%}
## Joining a team account
When a user is invited to join a team account - they receive an email with an invitation link. After signing up or signing in - they are redirected to the join page.
{% img src="/assets/images/docs/walkthrough/sign-up-invite.webp" width="3420" height="2142" /%}
### Join Page
The join page is where users can join a team account.
{% img src="/assets/images/docs/walkthrough/join-team.webp" width="3420" height="2142" /%}
## Super Admin
The super admin is the administrator of the SaaS. They have access to a special set of features that allow them to manage the accounts of the SaaS.
### Home Page of the super admin
The home page is a small overview of the SaaS.
You can easily customize this page to show the most important metrics of your SaaS.
{% img src="/assets/images/docs/walkthrough/super-admin-dashboard.jpg" width="3420" height="2142" /%}
### Listing the accounts of the SaaS
The super admin can view all the accounts of the SaaS. They can filter the accounts by personal accounts, team accounts, or all accounts.
{% img src="/assets/images/docs/walkthrough/super-admin-accounts.webp" width="3420" height="2142" /%}
### Viewing the account details
The super admin can view the details of an account. They can see the account information, the members of the account, and the billing information.
Additionally, they can perform the following actions:
1. Ban the account (or unban)
2. Delete the account
{% img src="/assets/images/docs/walkthrough/super-admin-account.webp" width="3420" height="2142" /%}
## Conclusion
This concludes the functional walkthrough of the Next.js Supabase Turbo Starter Kit. You should now have a good understanding of the features of the kit and how to use it. If you have any questions, feel free to reach out to us. We're here to help!

109
docs/installation/introduction.mdoc Normal file
View File

@@ -0,0 +1,109 @@
---
status: "published"
title: 'Introduction to the Next.js Supabase SaaS Starter Kit'
label: 'Introduction'
order: 1
description: 'A production-ready Next.js 16 and Supabase SaaS starter kit with authentication, billing, teams, and admin dashboard built on React 19 and Tailwind CSS 4.'
---
The Next.js Supabase SaaS Kit is a production-ready starter for building multi-tenant SaaS applications. It ships with authentication, team management, subscription billing, and an admin dashboard out of the box.
Built on **Next.js 16**, **React 19**, **Supabase**, and **Tailwind CSS 4**, this Turborepo monorepo gives you a solid foundation to launch faster without sacrificing code quality or flexibility.
## What You Get
### Authentication and Security
- Email/password and OAuth sign-in (Google, GitHub, etc.)
- Magic link authentication
- Multi-factor authentication (TOTP)
- Password reset and email verification
- Session management with Supabase Auth
### Multi-Tenant Account System
- **Personal accounts**: Every user has a personal workspace
- **Team accounts**: Create organizations with multiple members
- **Role-based access**: Owner, Admin, Member roles with customizable permissions
- **Invitations**: Invite users via email with role assignment
- **RLS enforcement**: Row Level Security policies protect data at the database level
### Subscription Billing
- **Stripe** and **Lemon Squeezy** integrations
- Subscription models: flat-rate, tiered, per-seat pricing
- Customer portal for self-service management
- Webhook handling for subscription lifecycle events
- Support for both personal and team billing
### Admin Dashboard
- User management (view, impersonate, ban)
- Subscription overview and management
- Analytics and metrics dashboard
- Super admin role with MFA requirement
### Developer Experience
- **Turborepo monorepo** with shared packages
- **TypeScript** throughout with strict mode
- **Shadcn UI** components (Base UI-based)
- **React Query** for client-side data fetching
- **Zod** for runtime validation
- **next-intl** for i18n with locale-prefixed URL routing
- **Keystatic** or **WordPress** CMS integration
- **Sentry** and **Baselime** monitoring support
- Pre-configured **LLM rules** for Cursor, Claude Code, and Windsurf
## Monorepo Architecture
The kit separates concerns into reusable packages:
```
apps/
web/ # Main Next.js application
e2e/ # Playwright end-to-end tests
packages/
features/ # Feature modules (auth, accounts, admin, etc.)
ui/ # Shared UI components (@kit/ui)
supabase/ # Supabase client and types (@kit/supabase)
billing/ # Billing logic and gateway (@kit/billing)
mailers/ # Email providers (@kit/mailers)
i18n/ # Internationalization (@kit/i18n)
monitoring/ # Error tracking (@kit/monitoring)
analytics/ # User analytics (@kit/analytics)
```
This structure lets you modify features without touching core packages, and makes it straightforward to add new applications that share the same backend logic.
## Prerequisites
Before diving in, you should be comfortable with:
- **Next.js App Router**: Server Components, Server Actions, route handlers
- **Supabase**: PostgreSQL, Row Level Security, Auth
- **React**: Hooks, TypeScript, component patterns
The kit builds on these technologies rather than teaching them. If you're new to Supabase or the App Router, spend time with their official docs first.
## Documentation Scope
This documentation covers kit-specific configuration, patterns, and customization. For underlying technology details:
- [Next.js Documentation](https://nextjs.org/docs)
- [Supabase Documentation](https://supabase.com/docs)
- [Stripe Documentation](https://stripe.com/docs)
- [Turborepo Documentation](https://turbo.build/repo/docs)
## Upgrading from v2
{% callout title="Differences with v2" %}
In v3, the kit migrated from Radix to Base UI primitives, from `i18next` to `next-intl`, and from `enhanceAction` to `next-safe-action`. See [Upgrading from v2 to v3](/docs/next-supabase-turbo/installation/v3-migration) for the full migration guide.
{% /callout %}
## Next Steps
1. [Check the technical details](/docs/next-supabase-turbo/installation/technical-details) to understand the full stack
2. [Clone the repository](/docs/next-supabase-turbo/installation/clone-repository) and set up your environment
3. [Run the project locally](/docs/next-supabase-turbo/installation/running-project) to explore the features

98
docs/installation/mcp.mdoc Normal file
View File

@@ -0,0 +1,98 @@
---
status: "published"
title: "MCP Server for Next.js Supabase"
label: "MCP Server"
order: 12
description: "Configure MCP for Next.js Supabase for best AI assistance using AI Agents"
---
The Makerkit MCP Server provides tools to AI Agents for working with the codebase.
## Build MCP Server
Run the command:
```bash
pnpm --filter "@kit/mcp-server" build
```
The command will build the MCP Server at `packages/mcp-server/build/index.js`.
## Adding MCP Servers to AI Coding tools
In general, tools should automatically detect the MCP Server and use it as we ship the configuration in the `.mcp.json` file. However, you can add it manually to your AI coding tool by following the steps below.
Before getting started, retrieve the absolute path to the `index.js` file created above. You can normally do this in your IDE by right-clicking the `index.js` file and selecting `Copy Path`.
I will reference this as `<full-path>` in the steps below: please replace it with the full path to your `index.js`.
### Claude Code
Claude will automatically detect the MCP Server and use it as we ship the configuration in the `.mcp.json` file.
### Codex
Open the Codex TOML config and add the following:
```toml
[mcp_servers.makerkit]
command = "node"
args = ["<path-to-mcp-server>"]
```
Please change the `<path-to-mcp-server>` to the actual path of the MCP Server.
### Cursor
Open the `mcp.json` config in Cursor and add the following config:
```json
{
"mcpServers": {
"makerkit": {
"command": "node",
"args": ["<path-to-mcp-server>"]
}
}
}
```
Please change the `<path-to-mcp-server>` to the actual path of the MCP Server.
### Other Agents
Please refer to the documentation for other AI Agents. The format is normally similar with minimal differences.
## CLI MCP Server
The CLI MCP Server is a separate MCP server that ships with the MakerKit CLI. It lets your AI assistant create projects, install plugins, pull upstream updates, and resolve merge conflicts.
To add it, drop this into your editor's MCP config:
Using npx:
```json
{
"mcpServers": {
"makerkit-cli": {
"command": "npx",
"args": ["--yes", "--quiet", "@makerkit/cli@latest", "makerkit-cli-mcp"]
}
}
}
```
Using pnpm:
```json
{
"mcpServers": {
"makerkit-cli": {
"command": "pnpm",
"args": ["--silent", "dlx", "@makerkit/cli@latest", "makerkit-cli-mcp"]
}
}
}
```
The `--quiet` flag (npx) and `--silent` flag (pnpm) prevent package manager output from interfering with the MCP JSON-RPC stream.

55
docs/installation/migration-from-makerkit-v1.mdoc Normal file
View File

@@ -0,0 +1,55 @@
---
status: "published"
title: "Migrating from Makerkit v1 to Next.js Supabase"
label: "Migrating from v1"
order: 9
description: "Guidelines for migrating from Makerkit v1 to Next.js SaaS Boilerplate."
---
🚀 Welcome to your journey from Makerkit v1 to the Next.js SaaS Boilerplate!
This guide is designed to help you understand the changes between the two versions and navigate your project migration to the new v2. Whether you're a seasoned developer or just starting out, we've got you covered!
Here's a roadmap of the steps you'll take:
1. **Bootstrap a new project**: Kickstart a new project using the Next.js SaaS Boilerplate 🎉
2. **Update Schema**: Tweak the Postgres schema foreign key references, and integrate your existing tables 🧩
3. **Move files from older app**: Transport your files to the new app structure 📦
4. **Update imports to existing files**: Refresh imports to align with the new file structure 🔄
5. **Update configuration**: Modify the configuration files to match the new schemas ⚙️
## 1. Bootstrap a new project
The Next.js SaaS Boilerplate is a fresh take on Makerkit v1. You'll need to create a new project using this innovative boilerplate. Follow the [installation guide](clone-repository) to get your new project up and running in no time!
## 2. Update Schema
The schema in the Next.js SaaS Boilerplate has evolved significantly from Makerkit v1. You'll need to update your Postgres schema to match the new one.
Previously, you'd have a foreign key set to the organization ID:
```sql
organization_id bigint not null references organizations(id) on delete cascade,
```
Now, you'll have a foreign key set to the account ID as a UUID:
```sql
account_id uuid not null references public.accounts(id) on delete cascade,
```
In v2, an account can be both a user or an organization. So, instead of referencing the organization ID as in v1, you'll now reference the account ID.
## 3. Move files from older app
You have the flexibility to add these files to either the "user scope" (`/home`) or the "account scope" (`/home/[account]`). Note that in v3, all routes live under the `[locale]` segment (e.g., `app/[locale]/home/[account]/`). Choose the one that best suits your project needs.
## 4. Update imports to existing files
You'll need to update the imports to your existing files to match the new file structure. This applies to all the components and utilities that you imported from Makerkit. For instance, a button previously imported from `~/core/ui/Button`, will now be imported from `@kit/ui/button`.
## 5. Update configuration
Lastly, you'll need to update the configuration files to match the new schemas. The configuration is now split across various files at `apps/web/config`. Pay special attention to the billing schema, which is now more versatile (and a bit more complex).
Ready to get started? Let's dive in! 🏊‍♀️

184
docs/installation/navigating-codebase.mdoc Normal file
View File

@@ -0,0 +1,184 @@
---
status: "published"
title: "Navigating the Next.js Supabase SaaS Kit Codebase"
label: "Navigating the Codebase"
order: 7
description: "Understand the Turborepo monorepo structure, key directories, and where to add your custom code."
---
The kit uses Turborepo to organize code into reusable packages. Understanding this structure helps you know where to find things and where to add your own code.
## Top-Level Structure
```
├── apps/
│ ├── web/ # Main Next.js application
│ ├── dev-tool/ # Development debugging tool
│ └── e2e/ # Playwright end-to-end tests
├── packages/
│ ├── features/ # Feature modules (auth, accounts, admin)
│ ├── ui/ # Shared UI components
│ ├── supabase/ # Database client and types
│ ├── billing/ # Payment integrations
│ ├── mailers/ # Email providers
│ └── ... # Other shared packages
└── turbo.json # Turborepo configuration
```
## Where You'll Work Most
**90% of your work** happens in `apps/web/`. The packages provide infrastructure; you build your product in the app.
### apps/web/ Directory
```
apps/web/
├── app/ # Next.js App Router (routes)
├── components/ # App-specific components
├── config/ # Application configuration
├── lib/ # App-specific utilities
├── content/ # CMS content (Keystatic)
├── styles/ # Global CSS
└── supabase/ # Migrations and database tests
```
| Directory | What Goes Here |
|-----------|---------------|
| `app/` | All routes and pages |
| `components/` | Components specific to this app |
| `config/` | App settings, feature flags, navigation |
| `lib/` | Utilities that don't belong in packages |
| `supabase/` | Database migrations and seed data |
## App Router Structure
The `app/` directory follows Next.js App Router conventions:
```
app/
├── [locale]/ # i18n locale segment (wraps all routes)
│ ├── (marketing)/ # Public pages (landing, pricing, blog)
│ ├── auth/ # Authentication pages
│ ├── home/ # Authenticated dashboard
│ │ ├── (user)/ # Personal account routes
│ │ └── [account]/ # Team account routes (dynamic)
│ ├── admin/ # Super admin dashboard
│ ├── join/ # Team invitation acceptance
│ ├── update-password/ # Password reset completion
│ └── identities/ # OAuth identity linking
├── api/ # API route handlers (outside [locale])
└── layout.tsx # Minimal root layout
```
### Route Groups Explained
**`(marketing)`** - Pathless group for public pages. URLs don't include "marketing":
- `app/[locale]/(marketing)/page.tsx` → `/`
- `app/[locale]/(marketing)/pricing/page.tsx` → `/pricing`
**`home/(user)`** - Personal account dashboard. Pathless group under /home:
- `app/[locale]/home/(user)/page.tsx` → `/home`
- `app/[locale]/home/(user)/settings/page.tsx` → `/home/settings`
**`home/[account]`** - Team account dashboard. Dynamic segment for team slug:
- `app/[locale]/home/[account]/page.tsx` → `/home/acme-corp`
- `app/[locale]/home/[account]/settings/page.tsx` → `/home/acme-corp/settings`
The `[locale]` segment is optional for the default language (en). Non-default locales use a prefix (e.g., `/es/pricing`).
## Packages Overview
Packages provide reusable functionality. Import from them; don't modify unless necessary.
### Feature Packages (`packages/features/`)
| Package | Import | Contains |
|---------|--------|----------|
| `@kit/auth` | `@kit/auth/*` | Sign in/up forms, auth hooks |
| `@kit/accounts` | `@kit/accounts/*` | Personal account components |
| `@kit/team-accounts` | `@kit/team-accounts/*` | Team management, invitations |
| `@kit/admin` | `@kit/admin/*` | Super admin dashboard |
| `@kit/notifications` | `@kit/notifications/*` | In-app notifications |
### Infrastructure Packages
| Package | Import | Contains |
|---------|--------|----------|
| `@kit/ui` | `@kit/ui/*` | Shadcn components, design system |
| `@kit/supabase` | `@kit/supabase/*` | Database clients, types |
| `@kit/next` | `@kit/next/*` | Server actions, route helpers |
| `@kit/billing` | `@kit/billing/*` | Subscription logic |
| `@kit/mailers` | `@kit/mailers/*` | Email sending |
## Adding Your Own Code
### New Pages
Add routes in `apps/web/app/[locale]/`:
```
# Public page
apps/web/app/[locale]/(marketing)/features/page.tsx → /features
# Authenticated page (personal)
apps/web/app/[locale]/home/(user)/dashboard/page.tsx → /home/dashboard
# Authenticated page (team)
apps/web/app/[locale]/home/[account]/projects/page.tsx → /home/[slug]/projects
```
### New Components
Add to `apps/web/components/` for app-specific components:
```
apps/web/components/
├── dashboard/
│ ├── stats-card.tsx
│ └── activity-feed.tsx
└── projects/
├── project-list.tsx
└── project-form.tsx
```
### New Database Tables
1. Create migration in `apps/web/supabase/migrations/`
2. Run `pnpm run supabase:web:reset` to apply
3. Run `pnpm run supabase:web:typegen` to update types
### New API Routes
Add to `apps/web/app/api/`:
```typescript
// apps/web/app/api/projects/route.ts
import { enhanceRouteHandler } from '@kit/next/routes';
export const GET = enhanceRouteHandler(async ({ user }) => {
// Your logic here
});
```
## Configuration Files
Located in `apps/web/config/`:
| File | Purpose | When to Edit |
|------|---------|--------------|
| `app.config.ts` | App name, URLs | During initial setup |
| `auth.config.ts` | Auth providers | Adding OAuth providers |
| `billing.config.ts` | Plans, prices | Setting up billing |
| `feature-flags.config.ts` | Feature toggles | Enabling/disabling features |
| `paths.config.ts` | Route constants | Adding new routes |
| `*-navigation.config.tsx` | Sidebar menus | Customizing navigation |
## Next Steps
- [Review common commands](/docs/next-supabase-turbo/installation/common-commands) for daily development
- [Configure the app](/docs/next-supabase-turbo/configuration/application-configuration) for your product
- [Add marketing pages](/docs/next-supabase-turbo/development/marketing-pages) to start building

165
docs/installation/running-project.mdoc Normal file
View File

@@ -0,0 +1,165 @@
---
status: "published"
title: "Running the Next.js Supabase SaaS Kit Locally"
label: "Running the Project"
order: 5
description: "Start the local development environment with Supabase, Next.js, and optional Stripe webhook forwarding."
---
Running the project requires starting three services: Supabase (database), Next.js (web app), and optionally Stripe (billing webhooks).
{% sequence title="Startup Order" description="Start services in this order for a working development environment." %}
[Start Docker](#1-start-docker)
[Start Supabase](#2-start-supabase)
[Start Next.js](#3-start-nextjs)
[Start Stripe (optional)](#4-start-stripe-optional)
{% /sequence %}
## 1. Start Docker
Supabase runs in Docker containers. Open Docker Desktop (or OrbStack on macOS) before proceeding.
{% alert type="warning" title="Docker Required" %}
Supabase cannot start without Docker running. If you see "Cannot connect to Docker daemon", open your Docker application first.
{% /alert %}
## 2. Start Supabase
```bash
pnpm run supabase:web:start
```
This starts:
- PostgreSQL database on port 54322
- Supabase Studio (database UI) at [http://localhost:54323](http://localhost:54323)
- Mailpit (email testing) at [http://localhost:54324](http://localhost:54324)
- Auth, Storage, and other Supabase services
First startup downloads Docker images and runs migrations. This can take a few minutes.
**Bookmark these URLs:**
- [localhost:54323](http://localhost:54323) - Supabase Studio (view your database)
- [localhost:54324](http://localhost:54324) - Mailpit (check auth emails)
### If Supabase Fails to Start
Common fixes:
1. **Docker resources**: Increase Docker memory to 4GB+ in Docker Desktop settings
2. **Port conflicts**: Stop other services using ports 54321-54324
3. **Clean restart**: `pnpm run supabase:web:stop` then try again
## 3. Start Next.js
```bash
pnpm dev
```
This starts:
- Web application at [http://localhost:3000](http://localhost:3000)
- Dev Tools at [http://localhost:3010](http://localhost:3010)
The dev tools provide debugging utilities for environment variables, feature flags, and authentication state.
### Test Credentials
The database is seeded with test users:
**Regular User:**
```
Email: test@makerkit.dev
Password: testingpassword
```
**Super Admin (requires MFA):**
```
Email: super-admin@makerkit.dev
Password: testingpassword
```
### Super Admin MFA Setup
Super admin login requires a TOTP code. Use any authenticator app with this secret:
```
NHOHJVGPO3R3LKVPRMNIYLCDMBHUM2SE
```
Or use [totp.danhersam.com](https://totp.danhersam.com/) with this secret to generate codes.
### If Login Fails
Reset the database to restore seeded users:
```bash
pnpm run supabase:web:reset
```
This re-runs migrations and seeds fresh test data.
## 4. Start Stripe (Optional)
For testing subscription billing, forward Stripe webhooks to your local server:
```bash
pnpm run stripe:listen
```
This requires:
1. [Stripe CLI](https://stripe.com/docs/stripe-cli) installed
2. Stripe account authenticated (`stripe login`)
The command outputs a webhook signing secret. Add it to your `.env.local`:
```bash
STRIPE_WEBHOOK_SECRET=whsec_xxxxx
```
## Local Development URLs
| Service | URL | Purpose |
|---------|-----|---------|
| Web App | [localhost:3000](http://localhost:3000) | Main application |
| Dev Tools | [localhost:3010](http://localhost:3010) | Debugging utilities |
| Supabase Studio | [localhost:54323](http://localhost:54323) | Database management |
| Mailpit | [localhost:54324](http://localhost:54324) | Email testing |
## Stopping Services
Stop Supabase:
```bash
pnpm run supabase:web:stop
```
Stop Next.js: Press `Ctrl+C` in the terminal.
## Common Issues
### "Module not found: Can't resolve 'react-dom/client'"
Windows path length issue. Move your project closer to the drive root (e.g., `C:\projects\my-saas`).
See [troubleshooting module not found](../troubleshooting/troubleshooting-module-not-found) for details.
### Database connection errors
Supabase isn't running. Start it with `pnpm run supabase:web:start`.
### Seeded users not working
Database may have stale data. Reset with `pnpm run supabase:web:reset`.
### Emails not arriving
Check Mailpit at [localhost:54324](http://localhost:54324). All local emails go there, not to real email addresses.
## Next Steps
- [Navigate the codebase](/docs/next-supabase-turbo/installation/navigating-codebase) to understand the project structure
- [Configure the application](/docs/next-supabase-turbo/configuration/application-configuration) to customize for your product
- Review the [production checklist](/docs/next-supabase-turbo/going-to-production/checklist) before deploying

167
docs/installation/technical-details.mdoc Normal file
View File

@@ -0,0 +1,167 @@
---
status: "published"
title: "Technical Details of the Next.js Supabase SaaS Starter Kit"
label: "Technical Details"
order: 2
description: "Tech stack overview: Next.js 16, React 19, Supabase, Tailwind CSS 4, Turborepo monorepo with TypeScript, Shadcn UI, and Zod."
---
The kit is built as a [Turborepo](https://turbo.build) monorepo using these core technologies:
| Technology | Version | Purpose |
|------------|---------|---------|
| Next.js | 16 | App Router with Turbopack |
| React | 19 | UI framework |
| Supabase | Latest | Database, Auth, Storage |
| Tailwind CSS | 4 | Styling |
| TypeScript | 5.9+ | Type safety |
| pnpm | 10.19+ | Package manager |
| Node.js | 20.10+ | Runtime (required) |
### Key Libraries
- **Shadcn UI** (Base UI-based) for accessible UI components
- **React Query** (@tanstack/react-query) for client-side data fetching
- **next-intl** for internationalization with locale-prefixed URL routing
- **next-safe-action** for type-safe server actions
- **Zod** for schema validation
- **Lucide** for icons
- **react.email** for email templates
- **Nodemailer** or **Resend** for sending emails
The kit deploys to Vercel, Cloudflare, or any Node.js hosting. Edge runtime support enables deployment to Cloudflare Workers.
## Monorepo Structure
### Core Packages
| Package | Import | Purpose |
|---------|--------|---------|
| `@kit/ui` | `@kit/ui/*` | Shadcn UI components and custom components |
| `@kit/supabase` | `@kit/supabase/*` | Supabase clients, types, and queries |
| `@kit/next` | `@kit/next/*` | Server Actions, route handlers, middleware utilities |
| `@kit/shared` | `@kit/shared/*` | Shared utilities and helpers |
| `@kit/i18n` | `@kit/i18n/*` | Internationalization utilities |
### Feature Packages
Located in `packages/features/`:
| Package | Purpose |
|---------|---------|
| `@kit/auth` | Authentication flows (Supabase Auth) |
| `@kit/accounts` | Personal account management |
| `@kit/team-accounts` | Team/organization management |
| `@kit/admin` | Super admin dashboard |
| `@kit/notifications` | In-app notifications |
### Billing Packages
Located in `packages/billing/`:
| Package | Purpose |
|---------|---------|
| `@kit/billing` | Core billing logic and types |
| `@kit/billing-gateway` | Payment provider abstraction |
| `@kit/stripe` | Stripe integration |
| `@kit/lemon-squeezy` | Lemon Squeezy integration |
### Infrastructure Packages
| Package | Purpose |
|---------|---------|
| `@kit/mailers` | Email provider abstraction (Resend, Nodemailer, SendGrid) |
| `@kit/email-templates` | React Email templates |
| `@kit/monitoring` | Error tracking (Sentry, Baselime) |
| `@kit/analytics` | User behavior tracking |
| `@kit/database-webhooks` | Database trigger handlers |
| `@kit/cms` | Content management abstraction |
| `@kit/keystatic` | Keystatic CMS integration |
| `@kit/wordpress` | WordPress headless CMS integration |
| `@kit/policies` | Authorization policy helpers |
| `@kit/otp` | One-time password utilities |
## Application Configuration
Configuration files live in `apps/web/config/`:
| File | Purpose |
|------|---------|
| `app.config.ts` | App name, description, URLs |
| `auth.config.ts` | Auth providers, redirect paths |
| `billing.config.ts` | Billing provider, plans |
| `feature-flags.config.ts` | Feature toggles |
| `paths.config.ts` | Route definitions |
| `personal-account-navigation.config.tsx` | Personal dashboard sidebar |
| `team-account-navigation.config.tsx` | Team dashboard sidebar |
## Key Patterns
### Server Actions
Use `authActionClient` from `@kit/next/safe-action` for type-safe, validated server actions:
```typescript
import { authActionClient, publicActionClient } from '@kit/next/safe-action';
import * as z from 'zod';
const schema = z.object({ name: z.string().min(1) });
// Authenticated action
export const updateName = authActionClient
.inputSchema(schema)
.action(async ({ parsedInput: data, ctx: { user } }) => {
// data is validated, user is authenticated
});
// Public action (no auth required)
export const submitContact = publicActionClient
.inputSchema(schema)
.action(async ({ parsedInput: data }) => {
// data is validated, no user required
});
```
Use `authActionClient` for authenticated actions and `publicActionClient` for public actions like contact forms.
### Route Handlers
Use `enhanceRouteHandler` from `@kit/next/routes` for API routes:
```typescript
import { enhanceRouteHandler } from '@kit/next/routes';
export const POST = enhanceRouteHandler(async ({ body, user }) => {
// body is parsed, user is available
return NextResponse.json({ success: true });
}, { schema: yourSchema });
```
### Supabase Clients
```typescript
// Server Components and Server Actions
import { getSupabaseServerClient } from '@kit/supabase/server-client';
// Admin operations (bypasses RLS)
import { getSupabaseServerAdminClient } from '@kit/supabase/server-admin-client';
```
## Deployment Targets
The kit supports multiple deployment targets:
- **Vercel**: Zero-config deployment with environment variables
- **Cloudflare Pages/Workers**: Edge runtime support
- **Docker**: Self-hosted deployments
- **Any Node.js host**: Standard Next.js deployment
For production deployment, see the [going to production checklist](/docs/next-supabase-turbo/going-to-production/checklist).
## Upgrading from v2
{% callout title="Differences with v2" %}
In v2, the kit used Radix UI primitives, `enhanceAction` for server actions, `i18next` for translations, and `import { z } from 'zod'`. In v3, it uses Base UI primitives, `authActionClient`/`publicActionClient` from `next-safe-action`, `next-intl` for i18n, and `import * as z from 'zod'`.
For the full migration guide, see [Upgrading from v2 to v3](/docs/next-supabase-turbo/installation/v3-migration).
{% /callout %}

240
docs/installation/update-tailwindcss-v4.mdoc Normal file
View File

@@ -0,0 +1,240 @@
---
status: "published"
title: "Guidelines for updating Makerkit to Tailwind CSS v4"
label: "Updating to Tailwind CSS v4"
order: 9
description: "A guide to updating Makerkit to Tailwind CSS v4. All you need to know to migrate your codebase to the latest Tailwind CSS version."
---
Makerkit was originally built with Tailwind CSS v3, and has since been updated to Tailwind CSS v4. This guide will walk you through the changes and migration steps required to update your codebase to the latest version should you choose to update manually.
If you don't want to update manually, please pull the latest changes from Makerkit. You can use the below as a reference for the changes you need to make for the code you've written so far.
## Major Changes Overview
1. **Tailwind CSS Version Update**: Upgraded from v3.4.17 to v4.0.0
2. **CSS Architecture**: Moved to a component-based CSS architecture with separate stylesheets
3. **File Structure**: Reorganized CSS files into modular components
4. **Styling Changes**: Updated various UI components with new styling patterns
## File Structure Changes
The CSS structure has been reorganized into multiple files:
```txt {% title="apps/web/styles/*.css" %}
styles/
├── globals.css
├── theme.css
├── theme.utilities.css
├── shadcn-ui.css
├── markdoc.css
└── makerkit.css
```
1. `globals.css`: Global styles for the entire application
2. `theme.css`: Theme variables and colors
3. `theme.utilities.css`: Utility classes for the theme
4. `shadcn-ui.css`: ShadcN UI specific styles
5. `markdoc.css`: Markdown/documentation styles
6. `makerkit.css`: Makerkit specific components
### Retaining your existing styles
If you wish to keep your existing theme colors, please update the `shadcn-ui.css` file and keep the same variables for the theme.
**Note:** You have to use the `hsl` function to update the theme colors.
```css {% title="apps/web/styles/shadcn-ui.css" %}
@layer base {
:root {
--background: hsl(0 0% 100%);
--foreground: hsl(224 71.4% 4.1%);
--card: hsl(0 0% 100%);
--card-foreground: hsl(224 71.4% 4.1%);
--popover: hsl(0 0% 100%);
--popover-foreground: hsl(224 71.4% 4.1%);
--primary: hsl(220.9 39.3% 11%);
--primary-foreground: hsl(210 20% 98%);
--secondary: hsl(220 14.3% 95.9%);
--secondary-foreground: hsl(220.9 39.3% 11%);
--muted: hsl(220 14.3% 95.9%);
--muted-foreground: hsl(220 8.9% 46.1%);
--accent: hsl(220 14.3% 95.9%);
--accent-foreground: hsl(220.9 39.3% 11%);
--destructive: hsl(0 84.2% 60.2%);
--destructive-foreground: hsl(210 20% 98%);
--border: hsl(214.3 31.8% 94.4%);
--input: hsl(214.3 31.8% 91.4%);
--ring: hsl(224 71.4% 4.1%);
--radius: 0.5rem;
--chart-1: hsl(12 76% 61%);
--chart-2: hsl(173 58% 39%);
--chart-3: hsl(197 37% 24%);
--chart-4: hsl(43 74% 66%);
--chart-5: hsl(27 87% 67%);
--sidebar-background: hsl(0 0% 98%);
--sidebar-foreground: hsl(240 5.3% 26.1%);
--sidebar-primary: hsl(240 5.9% 10%);
--sidebar-primary-foreground: hsl(0 0% 98%);
--sidebar-accent: hsl(240 4.8% 95.9%);
--sidebar-accent-foreground: hsl(240 5.9% 10%);
--sidebar-border: hsl(220 13% 91%);
--sidebar-ring: hsl(217.2 91.2% 59.8%);
}
.dark {
--background: hsl(224 71.4% 4.1%);
--foreground: hsl(210 20% 98%);
--card: hsl(224 71.4% 4.1%);
--card-foreground: hsl(210 20% 98%);
--popover: hsl(224 71.4% 4.1%);
--popover-foreground: hsl(210 20% 98%);
--primary: hsl(210 20% 98%);
--primary-foreground: hsl(220.9 39.3% 11%);
--secondary: hsl(215 27.9% 13%);
--secondary-foreground: hsl(210 20% 98%);
--muted: hsl(215 27.9% 13%);
--muted-foreground: hsl(217.9 10.6% 64.9%);
--accent: hsl(215 27.9% 13%);
--accent-foreground: hsl(210 20% 98%);
--destructive: hsl(0 62.8% 30.6%);
--destructive-foreground: hsl(210 20% 98%);
--border: hsl(215 27.9% 13%);
--input: hsl(215 27.9% 13%);
--ring: hsl(216 12.2% 83.9%);
--chart-1: hsl(220 70% 50%);
--chart-2: hsl(160 60% 45%);
--chart-3: hsl(30 80% 55%);
--chart-4: hsl(280 65% 60%);
--chart-5: hsl(340 75% 55%);
--sidebar-background: hsl(224 71.4% 4.1%);
--sidebar-foreground: hsl(240 4.8% 95.9%);
--sidebar-primary: hsl(224.3 76.3% 48%);
--sidebar-primary-foreground: hsl(0 0% 100%);
--sidebar-accent: hsl(215 27.9% 13%);
--sidebar-accent-foreground: hsl(240 4.8% 95.9%);
--sidebar-border: hsl(240 3.7% 15.9%);
--sidebar-ring: hsl(217.2 91.2% 59.8%);
}
}
```
## Breaking Changes
### 1. Class Name Updates
- Replace `space-x-` and `space-y-` with `gap-x-` and `gap-y-`
- Update shadow utilities:
- `shadow` → `shadow-xs`
- `shadow-sm` → `shadow-xs`
- `shadow-lg` → `shadow-xl`
**Note:** The spacing has changed from v3 using dynamic spacing, so you may need to update your custom spacing values.
### 2. Border Radius Changes
- Update rounded utilities:
- `rounded-sm` → `rounded-xs`
- Keep other rounded values the same
### 3. Color System Changes
- The theme has been updated with a better looking color system, especially on dark mode
### 4. Layout Updates
- Flex gap spacing:
- Replace `space-x-` with `gap-x-`
- Replace `space-y-` with `gap-y-`
### 5. Container Changes
```css
/* Old */
.container {
@apply max-sm:px-4;
}
/* New */
@utility container {
margin-inline: auto;
@apply xl:max-w-[80rem] px-8;
}
```
#### **Outline Utilities**
```css
/* Old */
focus:outline-none
/* New */
focus:outline-hidden
```
#### **Shadow Utilities**
```css
/* Old */
shadow-sm
/* New */
shadow-xs
```
## Migration Steps
#### **Update Dependencies**
```json
{
"dependencies": {
"tailwindcss": "4.0.0",
"@tailwindcss/postcss": "^4.0.0"
}
}
```
The `tailwindcss-animate` dependency is now part of `apps/web/package.json` and should be removed from `package.json` in the Tailwind CSS v4 upgrade.
#### **Update PostCSS Config**
```js
module.exports = {
plugins: {
'@tailwindcss/postcss': {},
},
};
```
#### **CSS Files**
- Move existing global styles to appropriate new CSS files
- Update import statements to include new CSS files
- Remove old tailwind.config.ts and replace with new CSS structure
#### **Component Updates**
- Review all components using spacing utilities
- Update shadow utilities
- Review and update color usage
- Update flex and grid gap utilities
## Testing Checklist
- [ ] Verify all components render correctly
- [ ] Check responsive layouts
- [ ] Test dark mode functionality
- [ ] Verify shadow and elevation styles
- [ ] Test container layouts
- [ ] Verify color system implementation
- [ ] Check form component styling
- [ ] Test navigation components
- [ ] Verify modal and overlay styling
- [ ] Check typography scaling
## Additional Resources
- [Tailwind CSS v4 Documentation](https://tailwindcss.com/)

128
docs/installation/updating-codebase.mdoc Normal file
View File

@@ -0,0 +1,128 @@
---
status: "published"
title: "Updating your Next.js Supabase Turbo Starter Kit"
label: "Updating the Codebase"
order: 6
description: "Learn how to update your Next.js Supabase Turbo Starter Kit to the latest version."
---
This guide will walk you through the process of updating your codebase by pulling the latest changes from the GitHub repository and merging them into your project. This ensures you're always equipped with the latest features and bug fixes.
If you've been following along with our previous guides, you should already have a Git repository set up for your project, with an `upstream` remote pointing to the original repository.
Updating your project involves fetching the latest changes from the `upstream` remote and merging them into your project. Let's dive into the steps!
{% sequence title="Steps to update your codebase" description="Learn how to update your Next.js Supabase Turbo Starter Kit to the latest version." %}
[Stashing your changes (if any)](#0.-stashing-your-changes-(if-any))
[Refresh the `upstream` remote](#1.-refresh-the-remote)
[Resolve any conflicts](#2.-resolve-any-conflicts)
[Run a health check on your project](#run-a-health-check-on-your-project-after-resolving-conflicts)
[Merge the changes](#3.-merge-the-changes)
{% /sequence %}
## 0. Stashing your changes (if any)
If you have uncommited changes, before updating your project, it's a good idea to stash your changes to avoid any conflicts during the update process. You can stash your changes by running:
```bash
git stash
```
This will save your changes temporarily, allowing you to update your project without any conflicts. Once you've updated your project, you can apply your changes back by running:
```bash
git stash pop
```
If you don't have any changes to stash, you can skip this step and proceed with the update process. 🛅
Alternatively, you can commit your changes.
## 1. Refresh the `upstream` remote
Create a new branch for your updates from the `main` branch:
```bash
git checkout -b update-codebase-<date>
```
In this way, you can keep track of your updates and visualize the changes in the branch before merging them into your main branch.
Now, fetch the latest changes from the `upstream` remote. You can do this by running the following command:
```bash
git pull upstream main
```
When prompted the first time, please opt for **merging instead of rebasing**.
Now, run `pnpm i` to update the dependencies:
```bash
pnpm i
```
## 2. Resolve any conflicts
Encountered conflicts during the merge? No worries! You'll need to resolve them manually. Git will highlight the files with conflicts, and you can edit them to resolve the issues.
### 2.1 Conflicts in the lock file "pnpm-lock.yaml"
If you find conflicts in the `pnpm-lock.yaml` file, accept either of the two changes (avoid manual edits), then run:
```bash
pnpm i
```
Your lock file will now reflect both your changes and the updates from the `upstream` repository. 🎉
### 2.2 Conflicts in the DB types "database.types.ts"
Your types might differ from those in the `upstream` repository, so you'll need to rebuild them and accept the latest state of the DB.
To do this, first you want to reset the DB to apply the latest changes from the `upstream` repository:
```bash
pnpm run supabase:web:reset
```
Next, regenerate the types with the following command:
```bash
pnpm run supabase:web:typegen
```
Your types will now reflect the changes from both the `upstream` repository and your project. 🚀
### Run a health check on your project after resolving conflicts
After resolving the conflicts, it's time to test your project to ensure everything is working as expected. Run your project locally and navigate through the various features to verify that everything is functioning correctly.
You can run the following commands for a quick health check:
```bash
pnpm run typecheck
```
And lint your code with:
```bash
pnpm run lint
```
## 3. Merge the changes
If everything looks good, commit the changes and push them to your remote repository:
```bash
git commit -m "COMMIT_MESSAGE"
git push origin update-codebase-<date>
```
Once the changes are pushed, you can create a pull request to merge the changes into the `main` branch, assuming all is working fine.
Your project is now up to date with the latest changes from the `upstream` repository. 🎉

1326
docs/installation/v3-migration.mdoc Normal file
View File

File diff suppressed because it is too large Load Diff