@clubedge/create-clubedge-app 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +49 -13
  3. package/dist/cli/args.js +20 -0
  4. package/dist/cli/ui.js +6 -0
  5. package/dist/core/customize.js +167 -1
  6. package/dist/core/manifest.js +130 -3
  7. package/dist/core/plan.js +203 -3
  8. package/dist/index.js +91 -7
  9. package/dist/utils/fs.js +3 -0
  10. package/package.json +5 -4
  11. package/template/.dockerignore +3 -0
  12. package/template/.env.example +19 -6
  13. package/template/.github/workflows/ci.yml +34 -4
  14. package/template/.prettierignore +1 -0
  15. package/template/AGENTS.md +11 -3
  16. package/template/CONTRIBUTING.md +2 -2
  17. package/template/README.md +73 -54
  18. package/template/SETUP.md +112 -40
  19. package/template/_gitignore +6 -0
  20. package/template/apps/start/.env.example +40 -0
  21. package/template/apps/start/AGENTS.md +11 -0
  22. package/template/apps/start/Dockerfile +38 -0
  23. package/template/apps/start/components.json +21 -0
  24. package/template/apps/start/package.json +43 -0
  25. package/template/apps/start/public/.well-known/logo.svg +1 -0
  26. package/template/apps/start/public/favicon.ico +0 -0
  27. package/template/apps/start/src/components/auth/auth-form-controls.tsx +108 -0
  28. package/template/apps/start/src/components/branding/clubedge-mark.tsx +24 -0
  29. package/template/apps/start/src/components/dashboard/account-button.tsx +33 -0
  30. package/template/apps/start/src/components/dashboard/app-sidebar.tsx +90 -0
  31. package/template/apps/start/src/components/dashboard/variants/account-button.none.tsx +9 -0
  32. package/template/apps/start/src/components/landing/copy-command.tsx +46 -0
  33. package/template/apps/start/src/components/theme/theme-provider.tsx +41 -0
  34. package/template/apps/start/src/components/theme/theme-toggle.tsx +21 -0
  35. package/template/apps/start/src/config/site.json +11 -0
  36. package/template/apps/start/src/config/site.ts +20 -0
  37. package/template/apps/start/src/env/auth.test.ts +26 -0
  38. package/template/apps/start/src/env/auth.ts +46 -0
  39. package/template/apps/start/src/env/server.test.ts +32 -0
  40. package/template/apps/start/src/env/server.ts +43 -0
  41. package/template/apps/start/src/lib/login-url.test.ts +16 -0
  42. package/template/apps/start/src/lib/login-url.ts +16 -0
  43. package/template/apps/start/src/router.tsx +27 -0
  44. package/template/apps/start/src/routes/__root.tsx +59 -0
  45. package/template/apps/start/src/routes/api/health.ts +15 -0
  46. package/template/apps/start/src/routes/auth/callback.ts +10 -0
  47. package/template/apps/start/src/routes/auth/sign-in.ts +11 -0
  48. package/template/apps/start/src/routes/auth/sign-out.ts +11 -0
  49. package/template/apps/start/src/routes/auth/sign-up.ts +11 -0
  50. package/template/apps/start/src/routes/dashboard.tsx +361 -0
  51. package/template/apps/start/src/routes/index.tsx +237 -0
  52. package/template/apps/start/src/routes/login.tsx +164 -0
  53. package/template/apps/start/src/server/auth-forms.test.ts +169 -0
  54. package/template/apps/start/src/server/auth-forms.ts +118 -0
  55. package/template/apps/start/src/server/auth.functions.ts +27 -0
  56. package/template/apps/start/src/server/auth.ts +51 -0
  57. package/template/apps/start/src/server/cache.test.ts +65 -0
  58. package/template/apps/start/src/server/cache.ts +58 -0
  59. package/template/apps/start/src/server/cookies.test.ts +41 -0
  60. package/template/apps/start/src/server/cookies.ts +31 -0
  61. package/template/apps/start/src/server/db.ts +16 -0
  62. package/template/apps/start/src/server/storage.ts +42 -0
  63. package/template/apps/start/src/server/users.ts +17 -0
  64. package/template/apps/start/src/server/variants/auth.better-auth.ts +57 -0
  65. package/template/apps/start/src/server/variants/auth.functions.none.ts +9 -0
  66. package/template/apps/start/src/server/variants/auth.none.ts +28 -0
  67. package/template/apps/start/src/server/variants/cache.memory.ts +26 -0
  68. package/template/apps/start/src/server/variants/storage.supabase.ts +35 -0
  69. package/template/apps/start/src/start.ts +40 -0
  70. package/template/apps/start/src/styles.css +2 -0
  71. package/template/apps/start/tsconfig.json +19 -0
  72. package/template/apps/start/tsr.config.json +7 -0
  73. package/template/apps/start/vite.config.ts +27 -0
  74. package/template/apps/web/next.config.ts +9 -9
  75. package/template/apps/web/package.json +7 -2
  76. package/template/{scripts → apps/web/scripts}/start-standalone.mjs +1 -2
  77. package/template/apps/web/src/app/dashboard/_components/account-button.tsx +1 -1
  78. package/template/apps/web/src/app/dashboard/_components/app-sidebar.tsx +1 -1
  79. package/template/apps/web/src/app/dashboard/_components/variants/account-button.none.tsx +9 -0
  80. package/template/apps/web/src/app/dashboard/page.tsx +18 -8
  81. package/template/apps/web/src/app/login/page.tsx +5 -4
  82. package/template/apps/web/src/app/page.tsx +7 -3
  83. package/template/apps/web/src/env/auth.ts +48 -0
  84. package/template/apps/web/src/env/client.ts +1 -8
  85. package/template/apps/web/src/env/server.test.ts +27 -4
  86. package/template/apps/web/src/env/server.ts +19 -29
  87. package/template/apps/web/src/proxy.ts +5 -8
  88. package/template/apps/web/src/server/auth.ts +14 -26
  89. package/template/apps/web/src/server/cache.ts +36 -16
  90. package/template/apps/web/src/server/cookies.ts +18 -0
  91. package/template/apps/web/src/server/storage.ts +22 -19
  92. package/template/apps/web/src/server/variants/auth.better-auth.ts +63 -0
  93. package/template/apps/web/src/server/variants/auth.none.ts +26 -0
  94. package/template/apps/web/src/server/variants/cache.memory.ts +26 -0
  95. package/template/apps/web/src/server/variants/storage.supabase.ts +35 -0
  96. package/template/apps/web/src/variants/proxy.better-auth.ts +46 -0
  97. package/template/clubedge.template.json +173 -2
  98. package/template/e2e/app.ts +12 -0
  99. package/template/e2e/auth-flow.spec.ts +29 -0
  100. package/template/{apps/web/e2e → e2e}/auth.spec.ts +2 -12
  101. package/template/e2e/home.spec.ts +24 -0
  102. package/template/eslint.config.mjs +6 -1
  103. package/template/package.json +6 -6
  104. package/template/packages/auth/package.json +3 -6
  105. package/template/packages/auth-better-auth/drizzle/0000_initial.sql +50 -0
  106. package/template/packages/auth-better-auth/drizzle/meta/0000_snapshot.json +320 -0
  107. package/template/packages/auth-better-auth/drizzle/meta/_journal.json +13 -0
  108. package/template/packages/auth-better-auth/drizzle.config.ts +12 -0
  109. package/template/packages/auth-better-auth/package.json +31 -0
  110. package/template/packages/auth-better-auth/scripts/migrate.ts +14 -0
  111. package/template/packages/auth-better-auth/src/index.test.ts +118 -0
  112. package/template/packages/auth-better-auth/src/index.ts +135 -0
  113. package/template/packages/auth-better-auth/src/schema.ts +74 -0
  114. package/template/packages/auth-better-auth/tsconfig.json +4 -0
  115. package/template/packages/auth-supabase/package.json +24 -0
  116. package/template/packages/{auth/src/supabase.test.ts → auth-supabase/src/index.test.ts} +2 -2
  117. package/template/packages/{auth/src/supabase.ts → auth-supabase/src/index.ts} +1 -1
  118. package/template/packages/auth-supabase/tsconfig.json +4 -0
  119. package/template/packages/cache/package.json +1 -4
  120. package/template/packages/cache/src/index.ts +3 -13
  121. package/template/packages/cache/src/memory-cache.test.ts +40 -0
  122. package/template/packages/cache/src/memory-cache.ts +37 -0
  123. package/template/packages/cache-redis/package.json +22 -0
  124. package/template/packages/{cache → cache-redis}/src/index.test.ts +6 -15
  125. package/template/packages/{cache/src/redis.ts → cache-redis/src/index.ts} +2 -6
  126. package/template/packages/cache-redis/tsconfig.json +4 -0
  127. package/template/packages/core/package.json +1 -1
  128. package/template/packages/db/package.json +3 -2
  129. package/template/packages/storage/package.json +2 -9
  130. package/template/packages/storage-s3/package.json +23 -0
  131. package/template/packages/{storage/src/s3.test.ts → storage-s3/src/index.test.ts} +1 -1
  132. package/template/packages/{storage/src/s3.ts → storage-s3/src/index.ts} +1 -1
  133. package/template/packages/storage-s3/tsconfig.json +4 -0
  134. package/template/packages/storage-supabase/package.json +22 -0
  135. package/template/packages/{storage/src/supabase.ts → storage-supabase/src/index.ts} +1 -1
  136. package/template/packages/storage-supabase/tsconfig.json +4 -0
  137. package/template/packages/ui/package.json +1 -1
  138. package/template/playwright.config.ts +6 -2
  139. package/template/pnpm-lock.yaml +1912 -27
  140. package/template/turbo.json +1 -1
  141. package/template/vitest.config.ts +2 -0
  142. package/template.lock.json +96 -12
  143. package/template/apps/web/e2e/home.spec.ts +0 -15
@@ -3,57 +3,65 @@
3
3
  [![CI](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml)
4
4
  [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
5
5
 
6
- Clubedge Starter is a production-oriented, modular Next.js application foundation. It brings together a pnpm monorepo, shared shadcn/ui components, PostgreSQL access through Drizzle, Supabase Auth, optional Redis and storage adapters, and a working example dashboard. It provides engineering conventions and a reference implementation; review its security and deployment choices for your application before production use.
6
+ Clubedge Starter is a production-oriented, modular React application foundation. It brings together a pnpm monorepo, shared shadcn/ui components, PostgreSQL access through Drizzle, replaceable infrastructure providers, and a working example dashboard. It provides engineering conventions and a reference implementation; review its security and deployment choices for your application before production use.
7
7
 
8
- This is a starter, not a hosted service or a one-command app generator. Fork it or use it as a reference, then adapt the app and provider configuration to your project. Contributions and bug reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Repository maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist.
8
+ <!-- clubedge:if starter-repository -->
9
+
10
+ This repository contains the same application for two frameworks, Next.js (`apps/web`) and TanStack Start (`apps/start`), plus every optional module. [create-clubedge-app](https://github.com/Clubedge/create-clubedge-app) generates a project with one framework and only the modules you choose; sections of this README marked for a framework or module appear only in projects that use it. Contributions and bug reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Repository maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist.
11
+
12
+ <!-- clubedge:end -->
9
13
 
10
14
  ## Features
11
15
 
12
- - Next.js App Router, React, TypeScript, Tailwind CSS 4, and shadcn/ui using Base UI primitives.
13
- - pnpm workspaces and Turborepo, with the web app in `apps/web` and reusable UI source in `packages/ui`.
16
+ - Next.js App Router with React, TypeScript, Tailwind CSS 4, and shadcn/ui using Base UI primitives. <!-- clubedge:only framework=next -->
17
+ - TanStack Start with React, TypeScript, Vite, Tailwind CSS 4, and shadcn/ui using Base UI primitives. <!-- clubedge:only framework=tanstack-start -->
18
+ - pnpm workspaces and Turborepo, with the web app in `apps/web` and framework-agnostic packages under `packages/`.
14
19
  - Drizzle ORM and PostgreSQL schema, migrations, and seed commands.
15
- - Supabase Auth using cookie based server clients from `@supabase/ssr`.
16
- - S3 compatible storage (including Cloudflare R2) and Supabase Storage adapters.
17
- - Optional Redis cache and fixed-window rate limiter using a standard Redis URL.
20
+ - Supabase Auth with server-verified sessions in secure cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=supabase -->
21
+ - Better Auth with users and sessions in your own PostgreSQL, secure session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=better-auth -->
22
+ - S3-compatible storage adapter for AWS S3, Cloudflare R2, and MinIO. <!-- clubedge:only storage=s3 -->
23
+ - Supabase Storage adapter that uses the signed-in user's session. <!-- clubedge:only storage=supabase -->
24
+ - Fixed-window rate limiter and cache on Redis, falling back to process memory without `REDIS_URL`. <!-- clubedge:only cache=redis -->
25
+ - Fixed-window rate limiter and cache in process memory, suited to a single server instance. <!-- clubedge:only cache=memory -->
18
26
  - Zod environment validation, security headers, structured errors, and `/api/health`.
19
27
  - Docker support, GitHub Actions CI, Vitest, Playwright, ESLint, and Prettier.
20
28
 
21
- ## Stack and provider choices
22
-
23
- | Capability | Included choice | Other supported options |
24
- | ----------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
25
- | Web app | Next.js App Router, React, TypeScript | — |
26
- | UI | Tailwind CSS 4, shadcn/ui, and Base UI | Add or replace components in your app or shared UI package. |
27
- | Database | PostgreSQL through Drizzle ORM | Any reachable PostgreSQL provider; Supabase PostgreSQL is documented. |
28
- | Authentication | Supabase Auth with `@supabase/ssr` | No alternate auth adapter is currently included. |
29
- | Cache and rate limiting | Optional Redis protocol client | Upstash, self-hosted Redis, or a compatible Redis service. |
30
- | Object storage | S3-compatible adapter or Supabase Storage | AWS S3, Cloudflare R2, and other S3-compatible services. |
31
- | Local runtime | Docker and Next.js standalone output | Run directly with Node.js during development. |
32
- | Verification | Vitest, Playwright, ESLint, Prettier, GitHub Actions | — |
33
-
34
29
  ## Architecture
35
30
 
36
31
  ```mermaid
37
32
  flowchart TB
38
- Browser --> Next[Next.js application]
39
- Next -->|auth interface and server sessions| Auth[Supabase Auth]
40
- Next -->|Drizzle ORM| DB[(PostgreSQL)]
41
- Next -->|optional cache and rate limits| Redis[(Redis)]
42
- Next -->|storage interface| Storage{Storage provider}
43
- Storage --> S3[S3-compatible storage: AWS S3, R2, MinIO]
44
- Storage --> SupabaseStorage[Supabase Storage]
33
+ %% clubedge:if framework=next
34
+ Browser --> App[Next.js application]
35
+ %% clubedge:end
36
+ %% clubedge:if framework=tanstack-start
37
+ Browser --> App[TanStack Start application]
38
+ %% clubedge:end
39
+ App -->|Drizzle ORM| DB[(PostgreSQL)]
40
+ %% clubedge:if auth=supabase
41
+ App -->|auth interface and server sessions| Auth[Supabase Auth]
42
+ %% clubedge:end
43
+ %% clubedge:if auth=better-auth
44
+ App -->|auth interface and server sessions| Auth[Better Auth]
45
+ Auth -->|users and sessions| DB
46
+ %% clubedge:end
47
+ %% clubedge:if cache=redis
48
+ App -->|cache and rate limits| Redis[(Redis, or memory)]
49
+ %% clubedge:end
50
+ %% clubedge:if storage=s3
51
+ App -->|storage interface| S3[S3-compatible storage: AWS S3, R2, MinIO]
52
+ %% clubedge:end
53
+ %% clubedge:if storage=supabase
54
+ App -->|storage interface| SupabaseStorage[Supabase Storage]
55
+ %% clubedge:end
45
56
  ```
46
57
 
47
- Drizzle manages application data in PostgreSQL. Supabase Auth manages identity and sessions separately; it is not accessed through Drizzle. The PostgreSQL database may be Supabase PostgreSQL or another PostgreSQL provider.
48
-
49
58
  ### Architecture principles
50
59
 
51
60
  - **PostgreSQL is the source of truth for application data.** Drizzle centralizes application schema, queries, and migrations.
52
- - **Authentication stays separate from application data.** Supabase Auth owns credentials and sessions; application tables are managed by Drizzle.
53
- - **Infrastructure dependencies stay optional where practical.** Redis is only needed for distributed cache and rate limiting. Without Redis, the rate limiter falls back to a per-process memory window, which is suitable for a single server instance only.
54
- - **Storage has a provider boundary.** Application code can use the storage interface with S3-compatible services or Supabase Storage; authorization and upload validation remain the caller's responsibility.
55
- - **Shared packages are framework-agnostic.** Packages under `packages/` receive configuration and request cookies as arguments and never import Next.js, so another app (for example a TanStack Start app) can reuse them unchanged. ESLint enforces these boundaries.
56
- - **One composition root per app.** `apps/web/src/server/` is the only place that reads environment variables and chooses providers. Routes, actions, and components call it rather than a provider SDK.
61
+ - **Authentication stays separate from application data.** The auth provider owns credentials and sessions; application tables are managed by Drizzle. <!-- clubedge:only auth!=none -->
62
+ - **Providers sit behind interfaces.** Interfaces live in `packages/{auth,storage,cache}` and each provider in its own package, so replacing a provider does not touch application code.
63
+ - **Shared packages are framework-agnostic.** Packages under `packages/` receive configuration and request cookies as arguments and never import a web framework. ESLint enforces these boundaries.
64
+ - **One composition root.** `apps/web/src/server/` is the only place that reads environment variables and chooses providers. Routes and components call it rather than a provider SDK.
57
65
  - **Keep the baseline focused.** Additional providers, queues, and generator tooling should be added when a real use case calls for them.
58
66
 
59
67
  ## Quick start
@@ -62,7 +70,7 @@ Drizzle manages application data in PostgreSQL. Supabase Auth manages identity a
62
70
 
63
71
  - Node.js 22.12 or newer (Node.js 22 LTS recommended).
64
72
  - pnpm 10.9.0. The repository pins its package manager version using Corepack.
65
- - PostgreSQL when using database features. A Supabase project can provide both PostgreSQL and Auth.
73
+ - PostgreSQL when using database features.
66
74
 
67
75
  ### Install and run
68
76
 
@@ -85,13 +93,13 @@ macOS/Linux:
85
93
  cp .env.example apps/web/.env.local
86
94
  ```
87
95
 
88
- Set `DATABASE_URL` in `apps/web/.env.local`. Supabase Auth is optional for exploring the UI; set `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` to enable it. See [SETUP.md](SETUP.md) for provider setup and optional integrations. Then start the app:
96
+ Set `DATABASE_URL` in `apps/web/.env.local`, then start the app. [SETUP.md](SETUP.md) describes every variable and provider.
89
97
 
90
98
  ```sh
91
99
  pnpm dev
92
100
  ```
93
101
 
94
- Open <http://localhost:3000> for the landing page, <http://localhost:3000/dashboard> for the starter dashboard, or <http://localhost:3000/api/health> for the liveness endpoint. The pages render without connecting to providers. Database, authentication, storage, and Redis operations require their respective configuration.
102
+ Open <http://localhost:3000> for the landing page, <http://localhost:3000/dashboard> for the dashboard, or <http://localhost:3000/api/health> for the liveness endpoint. The pages render without connecting to providers; database and provider operations require their configuration.
95
103
 
96
104
  ## Common commands
97
105
 
@@ -101,14 +109,14 @@ Run these from the repository root:
101
109
  | ------------------- | ---------------------------------------------- |
102
110
  | `pnpm dev` | Start the web app in development mode. |
103
111
  | `pnpm build` | Create a production build. |
104
- | `pnpm start` | Start the standalone production build. |
112
+ | `pnpm start` | Start the production build. |
105
113
  | `pnpm lint` | Run ESLint. |
106
114
  | `pnpm typecheck` | Typecheck the workspaces. |
107
115
  | `pnpm test` | Run Vitest. |
108
116
  | `pnpm test:e2e` | Run Playwright browser checks. |
109
117
  | `pnpm format` | Format supported repository files. |
110
118
  | `pnpm format:check` | Check formatting without writing files. |
111
- | `pnpm db:generate` | Generate Drizzle migrations from the schema. |
119
+ | `pnpm db:generate` | Generate Drizzle migrations from the schemas. |
112
120
  | `pnpm db:migrate` | Apply checked-in Drizzle migrations. |
113
121
  | `pnpm db:push` | Push schema directly (local development only). |
114
122
  | `pnpm db:studio` | Open Drizzle Studio. |
@@ -117,22 +125,33 @@ Run these from the repository root:
117
125
 
118
126
  Playwright's first run may require installing Chromium with `pnpm exec playwright install chromium`. CI runs the browser checks automatically.
119
127
 
128
+ <!-- clubedge:if starter-repository -->
129
+
130
+ ## Working on this repository
131
+
132
+ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start dev`. It reads `apps/start/.env.local`, copied from `apps/start/.env.example`. Run the browser suite against it with `E2E_APP=start pnpm test:e2e`, and build its image with `docker build -f apps/start/Dockerfile --build-arg APP_DIR=apps/start --build-arg APP_PACKAGE=@clubedge/start .`.
133
+
134
+ `clubedge.template.json` tells create-clubedge-app what each framework and module owns: packages, files, variant files under `variants/` that replace a default, and files with `clubedge:if` blocks. Write those blocks so the default selection keeps every block; use a variant file when two options need different code. `.github/workflows/starter.yml` generates projects for several combinations and runs their full pipeline.
135
+
136
+ <!-- clubedge:end -->
137
+
120
138
  ## Repository structure
121
139
 
122
- ```text
123
- apps/web/ Next.js app: routes, actions, UI, and the composition root
124
- src/server/ Wires environment, cookies, and providers into the packages
125
- packages/core/ Errors, Result type, and HTTP helpers (no dependencies)
126
- packages/auth/ AuthProvider and CookieStore interfaces, Supabase adapter
127
- packages/db/ Drizzle schema, client factory, migrations, and seed script
128
- packages/storage/ StorageProvider interface, S3 and Supabase Storage adapters
129
- packages/cache/ Rate limiters (memory and Redis) and Redis cache
130
- packages/ui/ Shared shadcn/ui components, utilities, and global theme styles
131
- .github/ CI workflow, issue forms, and pull request template
132
- SETUP.md Detailed local and provider setup
133
- CONTRIBUTING.md Contribution workflow and review expectations
134
- SECURITY.md Vulnerability reporting guidance
135
- ```
140
+ - `apps/web/`: the web app, with routes, UI, and the composition root in `src/server/`
141
+ - `e2e/`: Playwright browser checks
142
+ - `packages/core/`: errors, `Result` type, and HTTP helpers (no dependencies)
143
+ - `packages/db/`: Drizzle schema, client factory, migrations, and seed script
144
+ - `packages/auth/`: `AuthProvider` and `CookieStore` interfaces <!-- clubedge:only auth!=none -->
145
+ - `packages/auth-supabase/`: Supabase Auth adapter <!-- clubedge:only auth=supabase -->
146
+ - `packages/auth-better-auth/`: Better Auth adapter, with its own tables and migrations <!-- clubedge:only auth=better-auth -->
147
+ - `packages/storage/`: `StorageProvider` interface <!-- clubedge:only storage!=none -->
148
+ - `packages/storage-s3/`: S3-compatible storage adapter <!-- clubedge:only storage=s3 -->
149
+ - `packages/storage-supabase/`: Supabase Storage adapter <!-- clubedge:only storage=supabase -->
150
+ - `packages/cache/`: `Cache` and `RateLimiter` interfaces with in-memory implementations
151
+ - `packages/cache-redis/`: Redis rate limiter and cache <!-- clubedge:only cache=redis -->
152
+ - `packages/ui/`: shared shadcn/ui components, utilities, and global theme styles
153
+ - `.github/`: CI workflow, issue forms, and pull request template
154
+ - `SETUP.md`, `CONTRIBUTING.md`, `SECURITY.md`: setup, contribution, and security guides
136
155
 
137
156
  The project name, description, service identifier, and documentation links live in `apps/web/src/config/site.json`. Edit that file to rename the app; `create-clubedge-app` writes it for generated projects.
138
157
 
@@ -146,7 +165,7 @@ Add a component from the repository root using the web app's config:
146
165
  pnpm dlx shadcn@latest add badge -c apps/web
147
166
  ```
148
167
 
149
- Shared components are generated under `packages/ui/src/components` and can be imported from `@clubedge/ui/components/<component>`. The two `components.json` files intentionally share the `base-nova` style, neutral color base, Lucide icons, Tailwind v4 stylesheet, and RTL-aware generation setting. The app currently renders English in LTR; set the root document's `lang` and `dir` for the locale used by your application. Put app-only components in `apps/web/src/components`.
168
+ Shared components are generated under `packages/ui/src/components` and can be imported from `@clubedge/ui/components/<component>`. The app and `packages/ui` `components.json` files intentionally share the `base-nova` style, neutral color base, Lucide icons, Tailwind v4 stylesheet, and RTL-aware generation setting. The app currently renders English in LTR; set the root document's `lang` and `dir` for the locale used by your application. Put app-only components in `apps/web/src/components`.
150
169
 
151
170
  ## Contributing
152
171
 
package/template/SETUP.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Setup guide
2
2
 
3
- This guide covers local development and provider setup for Clubedge Starter. Start with the [README](README.md) for the architecture overview, then follow only the provider sections your project needs.
3
+ This guide covers local development and provider setup. Start with the [README](README.md) for the architecture overview.
4
4
 
5
- ## 1. Install the toolchain
5
+ ## Install the toolchain
6
6
 
7
7
  Install Node.js 22.12 or newer, then enable Corepack and install pnpm dependencies from the repository root:
8
8
 
@@ -15,7 +15,7 @@ The root `package.json` pins pnpm 10.9.0 through its `packageManager` field. Use
15
15
 
16
16
  If pnpm reports that it ignored a package build script needed by your environment, review the package name and approve only the required dependency with `pnpm approve-builds`.
17
17
 
18
- ## 2. Configure local environment
18
+ ## Configure the local environment
19
19
 
20
20
  Copy `.env.example` to `apps/web/.env.local`.
21
21
 
@@ -31,18 +31,19 @@ macOS/Linux:
31
31
  cp .env.example apps/web/.env.local
32
32
  ```
33
33
 
34
- The example file leaves optional provider URLs and keys blank so the app can build and start without connecting to real services. At minimum, set `DATABASE_URL`; set the Supabase values when you want to use authentication.
34
+ The example file leaves provider URLs and keys blank so the app can build and start without connecting to real services. At minimum, set `DATABASE_URL`. The variables are:
35
35
 
36
- Edit these values as needed:
36
+ - `DATABASE_URL` (required): PostgreSQL connection URL, such as a Supabase transaction pooler URL.
37
+ - `NEXT_PUBLIC_APP_URL` (recommended): the app's origin, defaulting to `http://localhost:3000`. <!-- clubedge:only framework=next -->
38
+ - `APP_URL` (recommended): the app's origin, defaulting to `http://localhost:3000`. <!-- clubedge:only framework=tanstack-start -->
39
+ - `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (for sign-in): see [Supabase Auth](#supabase-auth). <!-- clubedge:only framework=next && auth=supabase -->
40
+ - `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` (for sign-in): see [Supabase Auth](#supabase-auth). <!-- clubedge:only framework=tanstack-start && auth=supabase -->
41
+ - `BETTER_AUTH_SECRET` (for sign-in): see [Better Auth](#better-auth). <!-- clubedge:only auth=better-auth -->
42
+ - `REDIS_URL` (optional): see [Redis](#redis). <!-- clubedge:only cache=redis -->
43
+ - `STORAGE_*` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=s3 -->
44
+ - `SUPABASE_STORAGE_BUCKET` (for file storage): see [File storage](#file-storage). <!-- clubedge:only storage=supabase -->
37
45
 
38
- | Variable | Required | Description |
39
- | -------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
40
- | `DATABASE_URL` | Yes | PostgreSQL connection URL. Use a Supabase transaction pooler URL or another PostgreSQL connection. |
41
- | `NEXT_PUBLIC_SUPABASE_URL` | For Supabase Auth | Project URL, such as `https://<project-ref>.supabase.co`. |
42
- | `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | For Supabase Auth | Supabase publishable key. This key is intended for the browser; never use a service role key here. |
43
- | `NEXT_PUBLIC_APP_URL` | Recommended | The app's origin, defaulting to `http://localhost:3000`. |
44
-
45
- `DATABASE_URL` must be a non-empty string for server environment validation. If you are only exploring the UI, you can use a local placeholder URL, but database operations will fail until it points to a real PostgreSQL database.
46
+ `DATABASE_URL` must be a non-empty string for server environment validation. If you are only exploring the UI, a local placeholder URL works, but database operations fail until it points to a real PostgreSQL database.
46
47
 
47
48
  Start the development server:
48
49
 
@@ -52,9 +53,11 @@ pnpm dev
52
53
 
53
54
  The app is available at <http://localhost:3000> and the liveness endpoint at <http://localhost:3000/api/health>.
54
55
 
55
- ## 3. Configure Supabase Auth
56
+ <!-- clubedge:if auth=supabase -->
57
+
58
+ ## Supabase Auth
56
59
 
57
- Create or select a Supabase project. Set `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` from the project's API settings. For the database, use the transaction pooler URL when appropriate; the Postgres.js client is configured with `prepare: false` for compatibility with Supabase transaction pooling.
60
+ Create or select a Supabase project and copy its URL and publishable key from the project's API settings into the Supabase variables above. Authentication runs on the server, which validates every user with Supabase; never use a service role key.
58
61
 
59
62
  In Supabase Auth URL configuration, add this redirect URL for local email confirmation:
60
63
 
@@ -62,11 +65,27 @@ In Supabase Auth URL configuration, add this redirect URL for local email confir
62
65
  http://localhost:3000/auth/callback
63
66
  ```
64
67
 
65
- For deployed environments, add the corresponding `${NEXT_PUBLIC_APP_URL}/auth/callback` URL. The app uses the publishable key and validates users through its server auth adapter. Never expose a Supabase service role key to the client.
68
+ For deployed environments, add your deployed origin followed by `/auth/callback`. Until the Supabase variables are set, the dashboard stays viewable as a demo and the login page explains what is missing; once they are set, the dashboard redirects signed-out visitors to the login page.
69
+
70
+ <!-- clubedge:end -->
71
+
72
+ <!-- clubedge:if auth=better-auth -->
66
73
 
67
- ## 4. Set up the database
74
+ ## Better Auth
75
+
76
+ Better Auth keeps users, passwords, and sessions in your PostgreSQL database, in its own `auth_*` tables with a separate migration history (`packages/auth-better-auth/drizzle`). Set `DATABASE_URL` and apply the migrations (see [Set up the database](#set-up-the-database)), then set a secret of at least 32 random characters:
77
+
78
+ ```sh
79
+ openssl rand -base64 32
80
+ ```
68
81
 
69
- Application tables are managed with Drizzle. Supabase Auth manages its own auth tables. Keep one migration source of truth for application tables: do not also create an independent Supabase migration history for those same tables.
82
+ Put the result in `BETTER_AUTH_SECRET`. Until it is set, the dashboard stays viewable as a demo and the login page explains what is missing; once it is set, the dashboard redirects signed-out visitors to the login page. Sign-up signs the user in immediately; add email verification in `packages/auth-better-auth` if your application needs it. Signing in again on another device creates another session row, and signing out deletes it.
83
+
84
+ <!-- clubedge:end -->
85
+
86
+ ## Set up the database
87
+
88
+ Application tables are managed with Drizzle. Keep one migration source of truth for application tables: do not also create an independent Supabase migration history for those same tables.
70
89
 
71
90
  From the repository root:
72
91
 
@@ -76,11 +95,14 @@ pnpm db:generate
76
95
  pnpm db:migrate
77
96
  ```
78
97
 
79
- `db:generate` creates migration files from `packages/db/src/schema` into `packages/db/drizzle`; review and commit those files. `db:migrate` applies committed migrations. `db:push` is available for local development, but do not use it as a production migration workflow. Use `pnpm db:seed` only against a database where seed data is appropriate. The database commands run in `packages/db` and read `DATABASE_URL` from `apps/web/.env.local`, so the project keeps one environment file.
98
+ `db:generate` creates migration files from `packages/db/src/schema` into `packages/db/drizzle`; review and commit those files. Better Auth's tables have their own schema and migrations in `packages/auth-better-auth`, applied by the same commands. <!-- clubedge:only auth=better-auth -->
99
+ `db:generate` creates migration files from `packages/db/src/schema` into `packages/db/drizzle`; review and commit those files. <!-- clubedge:only auth!=better-auth -->
100
+
101
+ `db:migrate` applies committed migrations. `db:push` is available for local development, but do not use it as a production migration workflow. Use `pnpm db:seed` only against a database where seed data is appropriate. The database commands run in `packages/db` and read `DATABASE_URL` from `apps/web/.env.local`, so the project keeps one environment file. The Postgres.js client is configured with `prepare: false` for compatibility with Supabase transaction pooling.
80
102
 
81
- ## 5. Configure optional services
103
+ <!-- clubedge:if cache=redis -->
82
104
 
83
- ### Redis
105
+ ## Redis
84
106
 
85
107
  Redis is optional. Set `REDIS_URL` to a TCP connection URL:
86
108
 
@@ -88,21 +110,42 @@ Redis is optional. Set `REDIS_URL` to a TCP connection URL:
88
110
  REDIS_URL=rediss://default:<password>@<host>:6379
89
111
  ```
90
112
 
91
- Use `rediss://` for TLS connections such as Upstash and `redis://` for an unencrypted connection on a trusted network. Self-hosted Redis can use either scheme according to its TLS configuration. The app uses the standard Redis protocol and requires a Node.js runtime with outbound TCP access; this adapter is not for Edge runtimes that cannot open TCP connections.
113
+ Use `rediss://` for TLS connections such as Upstash and `redis://` for an unencrypted connection on a trusted network. The app uses the standard Redis protocol and requires a Node.js runtime with outbound TCP access.
114
+
115
+ Without `REDIS_URL`, the rate limiter and cache use process memory. Memory limits apply per server process, so configure Redis when you run several instances or serverless functions. Never commit a real Redis URL or password.
116
+
117
+ <!-- clubedge:end -->
118
+ <!-- clubedge:if cache=memory -->
119
+
120
+ ## Cache and rate limits
92
121
 
93
- When Redis is not configured, cache reads return a miss and `createRateLimiter()` falls back to an in-memory fixed window. Memory limits apply per server process, so configure Redis when you run several instances or serverless functions. Sign-in and sign-up attempts are limited to ten per minute per client address. Never commit a real Redis URL or password.
122
+ The rate limiter and cache keep their state in process memory, which suits a single server instance. Limits and cached values are not shared between instances and reset on restart.
94
123
 
95
- ### Object storage
124
+ <!-- clubedge:end -->
125
+ <!-- clubedge:if storage!=none -->
96
126
 
97
- Set `STORAGE_PROVIDER=s3` for AWS S3 or an S3-compatible provider such as Cloudflare R2. Configure `STORAGE_BUCKET`, `STORAGE_REGION`, `STORAGE_ENDPOINT` when required, and the access key, secret, and optional public URL. For R2, use the account's S3 API endpoint and region `auto`.
127
+ ## File storage
98
128
 
99
- Set `STORAGE_PROVIDER=supabase` to select the Supabase Storage adapter and configure `SUPABASE_STORAGE_BUCKET`. This adapter uses the configured Supabase server client. Choose a bucket policy that matches your application's access model.
129
+ <!-- clubedge:end -->
130
+ <!-- clubedge:if storage=s3 -->
100
131
 
101
- The storage adapter does not authorize users or validate uploads. Before calling it, the route or action must check ownership and authorization, file size, content type, and the object key. Keep credentials server side.
132
+ The storage adapter works with AWS S3 and S3-compatible providers such as Cloudflare R2 and MinIO. Configure `STORAGE_BUCKET`, `STORAGE_REGION`, `STORAGE_ENDPOINT` when required, and the access key, secret, and optional public URL. For R2, use the account's S3 API endpoint and region `auto`.
102
133
 
103
- ## 6. Shared UI development
134
+ <!-- clubedge:end -->
135
+ <!-- clubedge:if storage=supabase -->
104
136
 
105
- The repo uses matching `apps/web/components.json` and `packages/ui/components.json` files to direct the shadcn CLI into the shared `packages/ui` package. The selected `base-nova` style uses `@base-ui/react` primitives, not Radix UI. Tailwind CSS 4 and semantic theme tokens are defined in `packages/ui/src/styles/globals.css` and imported by the web app's root layout.
137
+ The storage adapter uses Supabase Storage through the signed-in user's Supabase session, so bucket policies can rely on that user. Set `SUPABASE_STORAGE_BUCKET` and choose a bucket policy that matches your application's access model.
138
+
139
+ <!-- clubedge:end -->
140
+ <!-- clubedge:if storage!=none -->
141
+
142
+ The storage adapter does not authorize users or validate uploads. Before calling it, the route must check ownership and authorization, file size, content type, and the object key. Keep credentials server side.
143
+
144
+ <!-- clubedge:end -->
145
+
146
+ ## Shared UI development
147
+
148
+ The app's `components.json` and `packages/ui/components.json` direct the shadcn CLI into the shared `packages/ui` package. The selected `base-nova` style uses `@base-ui/react` primitives, not Radix UI. Tailwind CSS 4 and semantic theme tokens are defined in `packages/ui/src/styles/globals.css` and imported by the app's root route.
106
149
 
107
150
  Generate a shared component from the repository root:
108
151
 
@@ -114,7 +157,7 @@ Shared components live in `packages/ui/src/components` and are imported from `@c
114
157
 
115
158
  The root route is a public landing page; the reference dashboard is available at `/dashboard`. The dashboard uses the shared shadcn sidebar and breadcrumb. A light/dark switch is available in the landing page and dashboard navigation; its choice is saved in local storage and the initial theme follows the system preference until the user selects one. Theme colors are centralized in `packages/ui/src/styles/globals.css` (blue `#2563eb`, dark background `#151515`).
116
159
 
117
- ## 7. Docker
160
+ ## Docker
118
161
 
119
162
  Create `apps/web/.env.local` first. Start the development image with:
120
163
 
@@ -129,9 +172,10 @@ pnpm docker:build
129
172
  pnpm docker:start
130
173
  ```
131
174
 
132
- The Docker image uses Next.js standalone output and runs as an unprivileged user. Ensure the configured database and provider hosts are reachable from the container.
175
+ The image runs the Next.js standalone output as an unprivileged user. Ensure the configured database and provider hosts are reachable from the container. <!-- clubedge:only framework=next -->
176
+ The image runs the self-contained Nitro server bundle as an unprivileged user, with no `node_modules`. Ensure the configured database and provider hosts are reachable from the container. <!-- clubedge:only framework=tanstack-start -->
133
177
 
134
- ## 8. Checks
178
+ ## Checks
135
179
 
136
180
  Run the checks relevant to your change before opening a pull request:
137
181
 
@@ -152,23 +196,51 @@ pnpm test:e2e
152
196
 
153
197
  The Playwright configuration starts the local app with a placeholder database URL; browser scenarios should not require real provider credentials.
154
198
 
199
+ <!-- clubedge:if starter-repository -->
200
+
201
+ ## The TanStack Start app
202
+
203
+ `apps/start` is the same application built with TanStack Start. It reuses every package and differs only in its framework layer:
204
+
205
+ | Concern | Next.js (`apps/web`) | TanStack Start (`apps/start`) |
206
+ | --------------------- | -------------------------------------- | --------------------------------------------------------------- |
207
+ | Environment file | `apps/web/.env.local` | `apps/start/.env.local`, from `apps/start/.env.example` |
208
+ | App URL and Supabase | `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_*` | `APP_URL`, `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY` |
209
+ | Sign-in and sign-up | Server actions | Form posts to `/auth/sign-in` and `/auth/sign-up` server routes |
210
+ | Session refresh | `src/proxy.ts` | Request middleware in `src/start.ts` |
211
+ | Cross-site protection | Built into server actions | `createCsrfMiddleware` in `src/start.ts` |
212
+ | Production output | Next.js standalone (`pnpm start`) | Nitro `.output` (`pnpm --filter @clubedge/start start`) |
213
+ | Docker image | `Dockerfile` | `apps/start/Dockerfile` (see below) |
214
+
215
+ Run it with `pnpm --filter @clubedge/start dev` and the browser suite with `E2E_APP=start pnpm test:e2e`. The database commands still read `DATABASE_URL` from `apps/web/.env.local`. Build its image from the repository root:
216
+
217
+ ```sh
218
+ docker build -f apps/start/Dockerfile --build-arg APP_DIR=apps/start --build-arg APP_PACKAGE=@clubedge/start -t clubedge-starter .
219
+ ```
220
+
221
+ In generated projects the app lives in `apps/web`, its Dockerfile is the root `Dockerfile`, and the build arguments are not needed.
222
+
223
+ <!-- clubedge:end -->
224
+
155
225
  ## Before deploying
156
226
 
157
- This repository is a starting point; review the security and operational choices for your application before production use:
227
+ This project is a starting point; review the security and operational choices for your application before production use:
158
228
 
159
229
  - Set production environment variables through your hosting provider's secret manager. Use unique, rotated credentials and TLS for external connections.
160
- - Set `NEXT_PUBLIC_APP_URL` to the deployed origin and add its `/auth/callback` URL to Supabase's allowed redirect URLs.
161
- - Make authenticated server routes call `getCurrentUser()` or `requireUser()` from `@/server/auth` (the latter throws a 401 `AppError`), and protect pages with `getPageUser(pathname)`, which redirects signed-out visitors to `/login`. Do not treat cookie contents alone as proof of identity.
162
- - Authorize storage access and validate upload size, content type, and object ownership in the route or action before using the storage adapter.
163
- - Configure Redis for rate limiting when you deploy more than one instance; the in-memory fallback does not share counts between instances. Client addresses come from `x-forwarded-for`, so deploy behind a proxy that sets it.
230
+ - Set the app URL variable to the deployed origin and add its `/auth/callback` URL to Supabase's allowed redirect URLs. <!-- clubedge:only auth=supabase -->
231
+ - Make authenticated server routes call `getCurrentUser()` or `requireUser()` from `@/server/auth` (the latter throws a 401 `AppError`), and protect pages with `getPageUser`, which redirects signed-out visitors to `/login`. Do not treat cookie contents alone as proof of identity. <!-- clubedge:only auth!=none -->
232
+ - Authorize storage access and validate upload size, content type, and object ownership in the route before using the storage adapter. <!-- clubedge:only storage!=none -->
233
+ - Configure Redis for rate limiting when you deploy more than one instance; the in-memory fallback does not share counts between instances. <!-- clubedge:only cache=redis -->
234
+ - The rate limiter keeps counts in memory, so deploy one instance or switch to a shared store before scaling out. <!-- clubedge:only cache=memory -->
235
+ - Client addresses come from `x-forwarded-for`, so deploy behind a proxy that sets it.
164
236
  - Configure and verify a restrictive Content Security Policy for the scripts and asset origins used by your deployment. A generic policy is not included because it can break framework tooling and project-specific assets.
165
237
  - Review database migration and backup procedures, provider access policies, and application-specific error handling.
166
238
 
167
239
  ## Troubleshooting
168
240
 
169
- - **Environment validation fails:** confirm you copied the example to `apps/web/.env.local` and set `DATABASE_URL`.
170
- - **Auth redirects fail:** add the exact local or deployed `/auth/callback` URL to Supabase Auth's allowed redirect URLs.
241
+ - **Environment validation fails:** confirm you copied the example to `apps/web/.env.local` and set `DATABASE_URL`. The error names the module whose variables are invalid.
242
+ - **Auth redirects fail:** add the exact local or deployed `/auth/callback` URL to Supabase Auth's allowed redirect URLs. <!-- clubedge:only auth=supabase -->
171
243
  - **Database connection fails:** check the URL, network access, and whether your provider expects a transaction pooler. Keep `prepare: false` for the current Supabase pooler setup.
172
- - **Redis cannot connect:** check that the URL uses `redis://` or `rediss://`, credentials are current, and outbound TCP access is allowed.
244
+ - **Redis cannot connect:** check that the URL uses `redis://` or `rediss://`, credentials are current, and outbound TCP access is allowed. <!-- clubedge:only cache=redis -->
173
245
  - **Playwright cannot find Chromium:** run `pnpm exec playwright install chromium`.
174
246
  - **A package file appears missing after an offline install:** retry with a normal registry-backed `pnpm install`; an incomplete local package cache can satisfy offline resolution while leaving package contents incomplete.
@@ -11,3 +11,9 @@ test-results/
11
11
  !.env.example
12
12
  !.env.test.example
13
13
  *.tsbuildinfo
14
+ .output/
15
+ .nitro/
16
+ .tanstack/
17
+ dist/
18
+ # Generated by TanStack Router during dev, build, and typecheck
19
+ routeTree.gen.ts
@@ -0,0 +1,40 @@
1
+ # Do not set NODE_ENV here: Vite reads it from env files, and vite build would then compile
2
+ # development JSX that crashes the production server. `vite dev` and `vite build` set it.
3
+ APP_URL=http://localhost:3000
4
+
5
+ # Supabase PostgreSQL: use the transaction pooler with prepare disabled (configured in packages/db).
6
+ DATABASE_URL=postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
7
+
8
+ # clubedge:if auth=supabase
9
+ # Supabase Auth (publishable key only; never use a service role key here).
10
+ # All auth runs on the server, so these need no browser prefix.
11
+ SUPABASE_URL=
12
+ SUPABASE_PUBLISHABLE_KEY=
13
+ # clubedge:end
14
+
15
+ # clubedge:if auth=better-auth
16
+ # Better Auth keeps users and sessions in DATABASE_URL (run pnpm db:migrate first).
17
+ # Generate a secret with: openssl rand -base64 32
18
+ BETTER_AUTH_SECRET=
19
+ # clubedge:end
20
+
21
+ # clubedge:if cache=redis
22
+ # Optional cache and rate limits (Redis protocol; rediss:// enables TLS). Without it, both use
23
+ # process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
24
+ REDIS_URL=
25
+ # clubedge:end
26
+
27
+ # clubedge:if storage=s3
28
+ # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
29
+ STORAGE_BUCKET=
30
+ STORAGE_REGION=auto
31
+ STORAGE_ENDPOINT=
32
+ STORAGE_ACCESS_KEY_ID=
33
+ STORAGE_SECRET_ACCESS_KEY=
34
+ STORAGE_PUBLIC_URL=
35
+ # clubedge:end
36
+
37
+ # clubedge:if storage=supabase
38
+ # Supabase Storage bucket, accessed with the signed-in user's Supabase session
39
+ SUPABASE_STORAGE_BUCKET=
40
+ # clubedge:end
@@ -0,0 +1,11 @@
1
+ # TanStack Start app
2
+
3
+ This app mirrors `apps/web` with TanStack Start. Follow the root `AGENTS.md`, plus:
4
+
5
+ - Read the skills bundled with the installed packages before changing framework code: `node_modules/@tanstack/react-start/skills/` and `node_modules/@tanstack/start-client-core/skills/`. They match the installed version; APIs change often.
6
+ - Route loaders run on the server and in the browser. Keep database, provider, and secret access in `src/server/`, reached from loaders through `createServerFn` (see `src/server/auth.functions.ts`).
7
+ - Every server function and server route that touches private data must check the user itself. A route guard only protects the page, not the endpoint.
8
+ - Modules in `src/server/` start with `import "@tanstack/react-start/server-only";` so they can never reach the browser bundle.
9
+ - Forms post to server routes that answer with 303 redirects (`src/server/auth-forms.ts`), so they work before hydration. Do not throw a router `redirect` from a POST handler; it uses 307 and repeats the POST.
10
+ - Search params are plain strings (`src/router.tsx`). Build login links with `loginUrl()` so they match the Next.js app.
11
+ - `src/routeTree.gen.ts` is generated by `vite dev` and `vite build`. Commit it, but do not edit it by hand.
@@ -0,0 +1,38 @@
1
+ # Production image for the TanStack Start app. Build it from the repository root.
2
+ # Generated projects keep the app in apps/web; the starter repository builds it with
3
+ # docker build -f apps/start/Dockerfile --build-arg APP_DIR=apps/start \
4
+ # --build-arg APP_PACKAGE=@clubedge/start .
5
+ ARG APP_DIR=apps/web
6
+ ARG APP_PACKAGE=@clubedge/web
7
+
8
+ FROM node:22-alpine AS base
9
+ RUN corepack enable
10
+ WORKDIR /app
11
+
12
+ # Reduce the workspace to the app and the packages it depends on, split into manifests
13
+ # (for a cacheable install layer) and full sources. New packages are picked up automatically.
14
+ FROM base AS pruner
15
+ ARG APP_PACKAGE
16
+ COPY . .
17
+ RUN pnpm dlx turbo@^2.5.0 prune ${APP_PACKAGE} --docker
18
+
19
+ FROM base AS deps
20
+ COPY --from=pruner /app/out/json/ .
21
+ RUN pnpm install --frozen-lockfile
22
+
23
+ FROM base AS builder
24
+ COPY --from=deps /app/ .
25
+ COPY --from=pruner /app/out/full/ .
26
+ COPY tsconfig.base.json ./
27
+ RUN pnpm build
28
+
29
+ # Nitro bundles the server and its dependencies into .output, so no node_modules are needed.
30
+ FROM node:22-alpine AS runner
31
+ ARG APP_DIR
32
+ ENV NODE_ENV=production HOST=0.0.0.0 PORT=3000
33
+ WORKDIR /app
34
+ RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 app
35
+ COPY --from=builder --chown=app:nodejs /app/${APP_DIR}/.output ./.output
36
+ USER app
37
+ EXPOSE 3000
38
+ CMD ["node", ".output/server/index.mjs"]
@@ -0,0 +1,21 @@
1
+ {
2
+ "$schema": "https://ui.shadcn.com/schema.json",
3
+ "style": "base-nova",
4
+ "rsc": false,
5
+ "tsx": true,
6
+ "tailwind": {
7
+ "config": "",
8
+ "css": "../../packages/ui/src/styles/globals.css",
9
+ "baseColor": "neutral",
10
+ "cssVariables": true
11
+ },
12
+ "aliases": {
13
+ "components": "@/components",
14
+ "utils": "@clubedge/ui/lib/utils",
15
+ "ui": "@clubedge/ui/components",
16
+ "lib": "@/lib",
17
+ "hooks": "@/hooks"
18
+ },
19
+ "iconLibrary": "lucide",
20
+ "rtl": true
21
+ }