saas-builder

SaaS Builder

Purpose

Verify the local baseline, then adapt the boilerplate's marketing, routes, schema, auth, i18n, UI, and tests for the user's SaaS MVP.

Mandatory Baseline Gate

Run these commands before planning, editing, or implementing product-specific work:

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

Users usually run npx skills add ixartz/saas-boilerplate from a parent/root directory; it creates .agents/ there and clones the boilerplate into <target-directory>. Since the app is one level below the agent's initial cwd, cd <target-directory> before reading app files or running project commands, and confirm package.json, src/, and skills/ exist.

Then verify the baseline:

npm run build-local
npm run test

Setup and verification commands are hard gates. Do not continue to mapping or implementation work until the baseline is fixed.

Working Rules

• Use the verified clone as the source of truth. Inspect current files before making claims or edits.
• Keep changes minimal. Do not reformat unrelated files.
• Do not change these: src/components/DemoBadge.tsx, its DemoBadge usage in src/app/[locale]/layout.tsx, or src/app/[locale]/(auth)/dashboard/page.tsx.
• Use marketing routes only for promotional content.
• Treat landing and marketing page adaptation as part of every SaaS implementation unless the user explicitly scopes it out.
• Build product workflows as dedicated authenticated dashboard feature pages, not in the dashboard index: use src/app/[locale]/(auth)/dashboard/<feature>/page.tsx for CRUD, data entry, tools, and customer-specific views.
• Split complex product workflows across several authenticated pages when needed. Do not force every part of a workflow into a single page; a feature can use separate pages for list, create, edit, detail, settings, or related subflows.

Project Conventions

• Keep the existing stack and patterns unless the user explicitly asks to replace them: Next.js App Router, TypeScript, React, Tailwind CSS, Shadcn/Radix UI, Clerk, Drizzle ORM, T3 Env, next-intl, LogTape, Vitest, Storybook, and Playwright.
• Add environment variables through src/libs/Env.ts; avoid direct process.env except in bootstrapping or instrumentation.
• Put user-visible copy in every supported locale file.
• Prefer existing Clerk account and organization features before custom auth flows.
• Follow nearby style and import conventions.
• Run npm run db:generate whenever src/models/Schema.ts changes.
• Persist product data in the database, not in local state or memory. Use Drizzle ORM for all database access.
• Make new components visually polished and consistent with the current UI: reuse existing Shadcn/Radix primitives, Tailwind tokens, spacing, typography, states, and responsive patterns before introducing new visual treatments.
• Use shadcn/ui theme tokens for UI colors; change colors only in src/styles/global.css, not locally in components.
• React Compiler is enabled, so don't add useMemo or useCallback.