Makerkit Next.js SaaS Starter Kit (Lite)

The @kit/ui package manages all UI components and styles for the application. It is organized into two distinct categories:

1. Shadcn UI: Standard components that follow the shadcn/ui pattern, allowing for high customizability and consistency across the app.
2. Makerkit-specific: Specialized components designed specifically for the MakerKit ecosystem and SaaS workflows.

The project uses a Turborepo monorepo architecture:

• apps/web/: The main Next.js application.
  • app/(marketing)/: Public marketing pages.
  • app/auth/: Authentication pages (logic resides in @kit/auth).
  • app/home/: Protected/Gated application pages.
  • supabase/: Database schema, migrations, and seed data.
  • config/: Application configuration.
• packages/ui/: Shared UI components (Shadcn UI + TailwindCSS v4).
• packages/features/: Core business logic packages (e.g., auth in packages/features/auth).

To add new Shadcn UI components to your project, follow the official MakerKit documentation guide. This ensures components are correctly integrated into the existing @kit/ui structure and styling system.

https://makerkit.dev/docs/next-supabase-turbo/components/shadcn

Use the following commands to control the local Supabase instance:

• Stop Supabase: pnpm run supabase:web:stop
• Reset Supabase: pnpm run supabase:web:reset (This applies migrations and resets the database using seed data).

For advanced CLI operations, use the --filter web flag to target the web application package.

pnpm run supabase:web:start
pnpm run supabase:web:stop
pnpm run supabase:web:reset

Supabase Setup

1. Create a new project in the Supabase dashboard.
2. Push your local migrations to the remote project:

   pnpm --filter web supabase db push

3. Set the Supabase Callback URL: In your Supabase project settings, set the Auth callback URL to <your-app-url>/auth/callback.

Hosting

• Vercel/Other Providers: Standard Next.js deployment.
• Cloudflare: To deploy to Cloudflare, you must set the runtime to edge in apps/web/app/layout.tsx and enable Node.js compatibility in the Cloudflare dashboard:

  export const runtime = 'edge';

The project uses Turborepo to cache results for these commands. You can run them frequently without performance impact:

• Format code: pnpm run format:fix
• Lint code: pnpm run lint
• Validate TypeScript: pnpm run typecheck

Before using Supabase utilities within your application, you must ensure that the @kit/supabase package is installed as a dependency. This package manages the Supabase client and provides various utilities for interacting with your Supabase backend.

{
    "name": "my-app",
    "dependencies": {
        "@kit/supabase": "*"
    }
}

The database schema and migrations are located in apps/web/supabase. Use these commands to manage changes:

• Create a new migration:

  pnpm --filter web supabase migration new --name <migration-name>

  This creates a file in apps/web/supabase/migrations.
• Apply migrations locally: Run pnpm run supabase:web:reset to apply migrations and reset with seed data.
• Link to a remote Supabase project:

  pnpm --filter web supabase db link

• Push migrations to remote Supabase:

  pnpm --filter web supabase db push

Follow these steps to set up the development environment locally:

1. Clone the repository:

   git clone https://github.com/makerkit/next-supabase-saas-kit-lite.git

2. Install dependencies using pnpm:

   pnpm install

3. Start Supabase (requires Docker to be running):

   pnpm run supabase:web:start

   The Supabase Dashboard is typically available at http://localhost:54323.
4. Start the Next.js application:

   pnpm run dev

   The app will be available at http://localhost:3000.

The event system is built on a base set of application events. To add your own custom events, you must extend the ConsumerProvidedEventTypes type. The system uses TypeScript generics to ensure that when you emit or listen to an event, the payload is correctly typed based on your extensions.

Base events included in BaseAppEventTypes:

• user.signedIn: { userId: string }
• user.signedUp: { method: 'magiclink' | 'password' }
• user.updated: EmptyPayload
• checkout.started: { planId: string; account?: string }

// 1. Define your custom events
export type ConsumerProvidedEventTypes = {
  'my.custom.event': { foo: string };
};

// The rest of the system will now automatically include 'my.custom.event'
// with the correct payload type.

Navigation items can be restricted to specific contexts using the context property. This allows you to show or hide routes based on whether the user is in a personal, organizational, or global view.

Available RouteContext values:

• 'personal': For routes specific to an individual user.
• 'organization': For routes specific to an organization/team.
• 'all': The default context, making the route available in all views.

// Example of a route restricted to organization context
const orgRoute = {
  label: 'Team Settings',
  path: '/org/settings',
  context: 'organization' as const,
};