ixartz SaaS Boilerplate

SaaS Boilerplate is a production-ready, open-source Next.js template designed to accelerate the development of SaaS applications. It features a modular UI built with Tailwind CSS and Shadcn UI, and uses TypeScript for type safety.

Key features include:

• Authentication: Handled by Clerk.
• Multi-Tenancy: Support for Teams, Roles, and Permissions.
• Database: Managed via Drizzle ORM (supports PostgreSQL, SQLite, and MySQL).
• Internationalization: Built-in i18n support.
• Testing: Unit and integration testing with Vitest; E2E testing with Playwright.
• Quality & DevOps: ESLint, Prettier, GitHub Actions for CI/CD, and Sentry for error reporting.

To start a new project using this boilerplate, clone the repository, install dependencies, and run the development server. The npm run dev command starts Next.js, a local PostgreSQL-compatible PGlite database, and Sentry Spotlight simultaneously.

Requirements:

• Node.js 24+
• npm

git clone --depth=1 https://github.com/ixartz/SaaS-Boilerplate.git my-project-name
cd my-project-name
npm install
npm run dev

To prepare for production, ensure DATABASE_URL and CLERK_SECRET_KEY are defined in your environment. Build and test the production bundle locally using:

npm run build
npm run start

When building new product workflows, do not add them to the dashboard index. Instead, create dedicated authenticated feature pages using the following route pattern:

src/app/[locale]/(auth)/dashboard/<feature>/page.tsx

For complex workflows, split the logic across multiple pages (e.g., separate pages for list, create, edit, detail, or settings) rather than forcing everything into a single page.

To use the Edge runtime in an App Router layout, add export const runtime = 'edge'; to your src/app/layouts.tsx.

Warning: Database migrations are not compatible with Edge. You must:

1. Disable automatic migration in src/libs/DB.ts.
2. Run migrations manually using npm run db:migrate whenever the schema changes.

The project includes several testing suites:

• Unit Tests: Uses Vitest. Run with npm run test.
• E2E/Integration Tests: Uses Playwright. Run with npm run test:e2e. (Note: run npx playwright install first if in a new environment).

Define your database structure in ./src/models/Schema.ts using Drizzle ORM. After updating the schema, you must generate a migration file using the following command:

npm run db:generate

Localization is handled via next-intl and Crowdin. To automate translations via GitHub Actions:

1. Create a project on Crowdin and obtain the Project ID.
2. Create a Personal Access Token in Crowdin (Account Settings > API).
3. Define CROWDIN_PROJECT_ID and CROWDIN_PERSONAL_TOKEN as environment variables in your GitHub Actions.

Localization files will synchronize with Crowdin on every push to the main branch.

The boilerplate uses Clerk for authentication. To configure it:

1. Create a Clerk account and a new application.
2. Add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY to your .env.local file.
3. In the Clerk Dashboard, navigate to Organization management > Settings > Enable organization to enable multi-tenancy support.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_pub_key
CLERK_SECRET_KEY=your_clerk_secret_key

Before implementing product-specific features, you must clone the repository, install dependencies, and verify the baseline works. This ensures you are building on a stable foundation.

1. Clone and install:

git clone https://github.com/ixartz/SaaS-Boilerplate.git <target-directory>
cd <target-directory>
npm install

2. Verify the baseline:

npm run build-local
npm run test

If these commands fail, do not proceed to implementation. Fix the errors until the baseline is verified.

Follow these conventions when extending the project's configuration and data layer:

• Environment Variables: Add new variables through src/libs/Env.ts. Avoid using process.env directly in your code.
• Database Schema: Modify src/models/Schema.ts to update the database structure. Whenever you change the schema, you must run the following command to regenerate the Drizzle client:

  npm run db:generate

• Data Persistence: Always use Drizzle ORM for database access. Do not persist product data in local state or memory.