Skip to content

docs: clean README + repo link, add MIT LICENSE #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
f-amine merged 1 commit into from
Jun 18, 2026
Merged

docs: clean README + repo link, add MIT LICENSE #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 f-amine

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
218 changes: 102 additions & 116 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,186 +1,172 @@
<div align="center">

<img src="apps/marketing/public/hero.png" alt="vibestack" width="100%" />

# vibestack

**The SaaS starter where Claude writes the rest.**
### The SaaS starter where Claude writes the rest.

An opinionated, AI-first SaaS starter — full stack pre-wired, every infra decision pre-made, every Claude Code skill you need vendored in the repo. You bring the business logic. Claude does the plumbing.
An opinionated, AI-first SaaS starter. Full stack pre-wired, every infra decision pre-made, every Claude Code skill vendored in the repo. You bring the business logic; Claude does the plumbing.

Works for two crowds:
[![Repo](https://img.shields.io/badge/GitHub-f--amine%2Fvibe--stack-181717?logo=github)](https://github.com/f-amine/vibe-stack)
[![Stars](https://img.shields.io/github/stars/f-amine/vibe-stack?color=e8c06a)](https://github.com/f-amine/vibe-stack/stargazers)
[![CI](https://github.com/f-amine/vibe-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/f-amine/vibe-stack/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-e8c06a.svg)](LICENSE)

- **Devs** — clone, `pnpm dev`, ship.
- **Vibe-coders** — open Claude Code, run `/setup`, describe your idea, let the workflow drive.
[**Repository**](https://github.com/f-amine/vibe-stack) · [Quickstart](#quickstart) · [Workflow](#the-vibestack-workflow) · [Deploy](#deploying-with-dokploy)

Same repo. Same skills. Same outcome.
</div>

---

## What's in the box

- Next.js 16 + React 19 + App Router (web, marketing, admin)
- Better Auth (email/pw, magic-link, Google, passkeys, 2FA, orgs, admin role, rate-limit)
- Postgres + Drizzle, tRPC v11 + Tanstack Query, Zod v4 validation
- Tailwind v4 + shadcn + dark mode
- Polar.sh billing wired end-to-end (sandbox + prod)
- Resend + React Email, Cloudflare R2 storage + nightly `pg_dump` → R2
- PostHog + GA4 analytics, Sentry errors, next-intl (EN + FR)
- Dokploy + docker-compose deploy, GitHub Actions CI
- Biome v2, Vitest + Playwright + a11y suite
```bash
npx create-vibestack my-saas
```

Full ADR set under `docs/adr/`. Decisions you don't have to re-make.
One command, both crowds:

## What's NOT in the box
- **Devs** — clone, `pnpm dev`, ship.
- **Vibe-coders** — open Claude Code, run `/setup`, describe your idea, let the workflow drive.

- App-level AI features. The stack is "AI-native dev" — not "AI SaaS template". Add `ai` SDK or whatever model wrapper you want when you build your features.
- A name. `npx create-vibestack` asks for one — or run `pnpm rename` after cloning.
- A wall of required API keys. **Zero-key boot**: the app runs with just a database and an auth secret. Every third-party integration (email, billing, storage, OAuth, analytics, errors) is optional and degrades gracefully until you add its key.
Same repo. Same skills. Same outcome.

## The vibestack workflow
## What's in the box

Open Claude Code in this repo. Skills come vendored — no install step:
- **Next.js 16** + React 19 + App Router — three apps: web, marketing, admin
- **Better Auth** — email/password, magic-link, Google, passkeys, 2FA, orgs, admin role, rate-limit
- **Postgres + Drizzle**, tRPC v11 + TanStack Query, Zod v4
- **Tailwind v4** + shadcn + dark mode
- **Polar.sh** billing wired end-to-end (sandbox + prod)
- **Resend** + React Email, **Cloudflare R2** storage + nightly `pg_dump` → R2
- **PostHog + GA4** analytics, **Sentry** errors, **next-intl** (EN + FR)
- **Dokploy** + docker-compose deploy, GitHub Actions CI
- **Biome v2**, Vitest + Playwright + a11y suite

```
new feature /grill-with-docs → /to-prd → /to-issues → /tdd → /review
bug /diagnose → /tdd
refactor /improve-codebase-architecture → ADR draft → /to-issues
new idea /prototype (throwaway to flush out the design)
```
Full ADR set under [`docs/adr/`](docs/adr/) — decisions you don't have to re-make.

Each skill is a short, opinionated playbook. They share a domain model (`CONTEXT.md`) and a decision log (`docs/adr/`) so multiple Claude sessions stay coherent.
## What's *not* in the box

See `.claude/skills/README.md` for the full catalogue.
- **App-level AI features.** The stack is AI-native *dev*, not an AI SaaS template. Add the `ai` SDK or any model wrapper when you build your features.
- **A name.** `npx create-vibestack` asks for one, or run `pnpm rename` after cloning.
- **A wall of required keys.** *Zero-key boot*: the app runs with just a database and an auth secret. Every third-party integration is optional and degrades gracefully until you add its key.

## Quickstart

One command, both crowds:

```bash
npx create-vibestack my-saas
```

The wizard clones the template and walks you through:

1. **Your product name** — renames the `@vibestack/*` scope and every brand string for you (lockfile-safe).
2. **Feature toggles** — email, billing, storage, Google sign-in, analytics, Sentry, French locale, the video swarm. Pick what you want; skip the rest.
3. **API keys** for the features you enabled — every single one skippable, with the signup URL printed next to it.
1. **Product name** — renames the `@vibestack/*` scope and every brand string (lockfile-safe).
2. **Feature toggles** — email, billing, storage, Google sign-in, analytics, Sentry, French locale, video swarm. Pick what you want; skip the rest.
3. **API keys** for what you enabled — every one skippable, signup URL printed next to it.
4. Writes `.env` with a generated `BETTER_AUTH_SECRET`.
5. Offers to run `pnpm install`, start Postgres (Docker), and push the schema.

When it finishes, `pnpm dev` gives you three apps:

- `http://localhost:3001` — your authed product
- `http://localhost:3000` — your marketing site + docs + blog
- `http://localhost:3002` — admin dashboard

**No keys? No problem.** Auth emails (magic links, verification, password reset) print to your terminal until you add a Resend key. Billing UI stays hidden until you add Polar. File storage tells you it's not configured only if you actually use it. `/api/health` reports unconfigured optional services as `disabled`.
Then `pnpm dev` gives you three apps:

### Vibe-coder track
| URL | App |
|---|---|
| `http://localhost:3001` | your authed product |
| `http://localhost:3000` | marketing site + docs + blog |
| `http://localhost:3002` | admin dashboard |

After `npx create-vibestack`, open the folder in Claude Code. Run `/setup` if you want a conversational hand to finish configuring keys (it knows every signup URL and free tier), or just describe what you want to build — the workflow above takes it from there.
> **No keys? No problem.** Auth emails (magic links, verification, password reset) print to your terminal until you add a Resend key. Billing UI stays hidden until you add Polar. File storage only complains if you actually use it. `/api/health` reports unconfigured optional services as `disabled`.

### Dev track — manual path

Already cloned the repo (or prefer doing it by hand)?
### Manual path (dev track)

```bash
git clone https://github.com/<you>/vibestack.git my-saas
git clone https://github.com/f-amine/vibe-stack.git my-saas
cd my-saas
pnpm install
pnpm db:start
cp .env.example .env
# only the core vars are needed to boot:
# DATABASE_URL — default matches pnpm db:start
# BETTER_AUTH_SECRET — openssl rand -base64 32
# APP_URL / CORS_ORIGIN / BETTER_AUTH_URL / NEXT_PUBLIC_APP_URL — localhost defaults
cp .env.example .env # only core vars needed to boot
pnpm db:push
pnpm dev
```

That's a fully working app — sign-up, sessions, orgs, the lot. Emails print to your terminal until you add Resend; add the other keys whenever the feature matters to you.
Core vars: `DATABASE_URL` (matches `pnpm db:start`), `BETTER_AUTH_SECRET` (`openssl rand -base64 32`), and the localhost URL vars. That's a fully working app — sign-up, sessions, orgs, the lot. Add other keys whenever the feature matters.

Prefer the wizard inside an existing clone? `pnpm init:app` runs the same flow. Full env reference: [`.claude/skills/setup/env-reference.md`](.claude/skills/setup/env-reference.md).

Prefer the wizard inside an existing clone? `pnpm init:app` runs the same interactive flow (rename + feature toggles + `.env`).
## The vibestack workflow

Need the full env-var key-by-key list? See [`.claude/skills/setup/env-reference.md`](.claude/skills/setup/env-reference.md). Deploying? See [`docs/deploy/production-env.md`](docs/deploy/production-env.md).
Open Claude Code in the repo. Skills come vendored, no install step:

```
new feature /grill-with-docs → /to-prd → /to-issues → /tdd → /review
bug /diagnose → /tdd
refactor /improve-codebase-architecture → ADR draft → /to-issues
new idea /prototype (throwaway, to flush out the design)
UI / design /impeccable (mandatory for anything visual)
content /blog-writer · /video-writer
```

Each skill is a short, opinionated playbook. They share a domain model ([`CONTEXT.md`](CONTEXT.md)) and a decision log ([`docs/adr/`](docs/adr/)) so multiple Claude sessions stay coherent. Full catalogue: [`.claude/skills/README.md`](.claude/skills/README.md).

## Common commands

```bash
pnpm dev # turbo dev across all apps
pnpm dev:web # just the product app (faster startup; also dev:marketing, dev:admin)
pnpm build # turbo build
pnpm check # biome format + lint
pnpm typecheck # tsc across packages
pnpm test # vitest
pnpm test:e2e # playwright

# Database
pnpm db:start # docker postgres
pnpm db:push # apply schema directly (dev)
pnpm db:generate # generate SQL migration
pnpm db:migrate # apply migrations (prod)
pnpm db:studio # drizzle studio UI
pnpm db:seed # seed demo data

# Auth schema regen after editing packages/auth plugins
pnpm auth:generate

# Email preview
pnpm email:dev # react-email at :3010

# First-run / branding
pnpm init:app # interactive wizard: name, features, keys, .env
pnpm rename <name> # rename @vibestack scope + brand strings only

# Skills maintenance
pnpm skills:update # pull latest upstream skills into .claude/skills/
pnpm dev # turbo dev across all apps (dev:web / dev:marketing / dev:admin for one)
pnpm build # turbo build
pnpm check # biome format + lint
pnpm typecheck # tsc across packages
pnpm test # vitest
pnpm test:e2e # playwright

pnpm db:start # docker postgres
pnpm db:push # apply schema directly (dev)
pnpm db:generate # generate SQL migration
pnpm db:migrate # apply migrations (prod)
pnpm db:studio # drizzle studio
pnpm db:seed # seed demo data
pnpm auth:generate # regen auth schema after editing packages/auth plugins
pnpm email:dev # react-email preview at :3010

pnpm init:app # interactive first-run wizard (name, features, keys, .env)
pnpm rename <name> # rename the @vibestack scope + brand strings only
pnpm skills:update # pull latest upstream skills
```

## Renaming for your product
## Renaming

`npx create-vibestack` and `pnpm init:app` already do this as their first step. If you only want the rename:
`npx create-vibestack` and `pnpm init:app` do this first. To rename only:

```bash
pnpm rename my-product
pnpm install # regenerates pnpm-lock.yaml for the new scope
pnpm install # regenerates the lockfile for the new scope
```

Unlike a raw `sed` over the tree, `pnpm rename` never touches `pnpm-lock.yaml`, skips `node_modules` / build output / binary assets, and handles case variants (`vibestack` / `Vibestack` / `VIBESTACK`). Review the diff before committing. Drop your own copy on the marketing landing hero.
Unlike a raw `sed`, `pnpm rename` never touches `pnpm-lock.yaml`, skips `node_modules` / build output / binaries, and handles case variants. Review the diff before committing.

## Deploying with Dokploy

1. Provision a small VPS (Hetzner / DigitalOcean / Vultr).
2. Install Dokploy via its one-liner.
3. Point a Compose service at `docker-compose.yml` in this repo.
4. Fill `.env.production` — see [`docs/deploy/production-env.md`](docs/deploy/production-env.md) for what's required vs optional in production.
5. Map domains to apps:
- `marketing.example.com` → `marketing:3000`
- `app.example.com` → `web:3001`
- `admin.example.com` → `admin:3002`
6. Enable Let's Encrypt SSL via the Dokploy UI.
7. The `backup` container runs `pg_dump` nightly → R2 (30-day retention).

Restore: `./scripts/restore-r2.sh` (latest dump) or pass a specific key.

## Power-user: 24/7 autonomous loop

Optional. Ship while you sleep — a long-running Claude swarm that picks up open `triaged` issues, implements them, opens PRs.
1. Provision a small VPS (Hetzner / DigitalOcean / Vultr) and install Dokploy.
2. Point a Compose service at [`docker-compose.prod.yml`](docker-compose.prod.yml).
3. Set env in the Dokploy Environment tab — see [`docs/deploy/production-env.md`](docs/deploy/production-env.md) for required vs optional.
4. Map a domain to each app (container ports: marketing `3000`, web `3001`, admin `3002`) and enable Let's Encrypt.

Setup + the prompts live under `.ruflo/`. See [`.ruflo/README.md`](.ruflo/README.md) for the runbook and risks.
The stack runs migrations on deploy (a healthcheck-gated `migrate` service) and ships a nightly `pg_dump` → R2 backup (`backup` container, 30-day retention; restore with `./scripts/restore-r2.sh`).

## Architecture decisions
> **Behind Cloudflare?** Its free SSL covers one subdomain level (`*.example.com`). Keep app hosts one level deep (e.g. `app.example.com`, not `app.x.example.com`) or grey-cloud the deep ones. Details in [`docs/deploy/production-env.md`](docs/deploy/production-env.md).

- `docs/adr/0001-tech-stack.md` — why this stack
- `docs/adr/0002-monorepo-shape.md` — workspace layout + import rules
- `docs/adr/0003-passkey-plugin.md` — Better Auth passkey choice
- `docs/adr/0004-ai-first-positioning.md` — why vibestack is positioned the way it is
## Power-user: 24/7 autonomous loop

Append new ADRs as numbered files. Reference them from `CONTEXT.md`.
Optional. A long-running Claude swarm that picks up `triaged` issues, implements them, and opens PRs. Runbook and risks: [`.ruflo/README.md`](.ruflo/README.md).

## Hard rules

- Don't touch `.env`, `.env.*`, `*.key`, `*.pem`, `secrets/*`.
- Don't bump major dep versions without an ADR.
- Don't push to `main` — branch → PR → CI → squash merge.
- Don't `--no-verify`.
- Branch → PR → CI → squash merge. Never push to `master`, never `--no-verify`.

## Credits

Initial scaffold via [Better-T-Stack](https://github.com/AmanVarshney01/create-better-t-stack). Workflow skills vendored from [mattpocock/skills](https://github.com/mattpocock/skills). Extended into vibestack with marketing/admin apps, Fumadocs, Resend, R2, PostHog/GA, Sentry, next-intl, Dokploy compose + R2 backup, and the full Claude Code skill set.
Initial scaffold via [Better-T-Stack](https://github.com/AmanVarshney01/create-better-t-stack). Workflow skills vendored from [mattpocock/skills](https://github.com/mattpocock/skills). Logos via [svgl.app](https://svgl.app). Extended into vibestack with marketing/admin apps, Fumadocs, Resend, R2, PostHog/GA, Sentry, next-intl, Dokploy compose + R2 backup, and the full Claude Code skill set.

<div align="center">

**[github.com/f-amine/vibe-stack](https://github.com/f-amine/vibe-stack)** · MIT

</div>
Loading