@alfredmouelle/create-stack 0.1.0

package/_stack/apps/next-base/src/server/email/core/port.ts

@@ -0,0 +1,89 @@
+import type { ReactElement } from 'react'
+
+/** A structured email address. */
+export interface MailAddress {
+  email: string
+  name?: string
+}
+
+/**
+ * A recipient, either as a plain string (`"hi@acme.com"` or
+ * `"Acme <hi@acme.com>"`) or a structured {@link MailAddress}.
+ */
+export type MailRecipient = string | MailAddress
+
+export interface MailAttachment {
+  filename: string
+  /** Raw bytes or a base64 string. */
+  content: Uint8Array | string
+  contentType?: string
+}
+
+/**
+ * A message as authored by application code. We never send raw HTML strings:
+ * the body is always a React Email component, rendered to HTML + plain text by
+ * the mailer before it reaches the adapter.
+ */
+export interface MailMessage {
+  to: MailRecipient | MailRecipient[]
+  subject: string
+  /** A React Email component. Rendered to HTML and plain text automatically. */
+  react: ReactElement
+  /** Overrides the default `from` configured on the mailer. */
+  from?: MailRecipient
+  replyTo?: MailRecipient
+  cc?: MailRecipient | MailRecipient[]
+  bcc?: MailRecipient | MailRecipient[]
+  headers?: Record<string, string>
+  /** Provider-agnostic key/value tags for analytics & filtering. */
+  tags?: Record<string, string>
+  attachments?: MailAttachment[]
+}
+
+export interface SentMail {
+  /** Provider message id. */
+  id: string
+}
+
+/**
+ * The port the application depends on. Swapping providers means swapping the
+ * adapter passed to {@link createMailer}; this interface never changes.
+ */
+export interface Mailer {
+  send(message: MailMessage): Promise<SentMail>
+}
+
+/**
+ * The message shape an adapter receives: addresses are normalized and the body
+ * is already rendered to `html` + `text`. Adapters do no rendering.
+ */
+export interface RenderedMessage {
+  to: MailAddress[]
+  from: MailAddress
+  subject: string
+  html: string
+  text: string
+  replyTo?: MailAddress
+  cc?: MailAddress[]
+  bcc?: MailAddress[]
+  headers?: Record<string, string>
+  tags?: Record<string, string>
+  attachments?: MailAttachment[]
+}
+
+/** The contract each provider implements. Kept intentionally tiny. */
+export interface MailerAdapter {
+  readonly name: string
+  send(message: RenderedMessage): Promise<SentMail>
+}
+
+/** Normalized error thrown by adapters so callers never catch provider types. */
+export class MailerError extends Error {
+  readonly adapter: string
+
+  constructor(message: string, options: { adapter: string; cause?: unknown }) {
+    super(message, { cause: options.cause })
+    this.name = 'MailerError'
+    this.adapter = options.adapter
+  }
+}

package/_stack/apps/next-base/src/server/email/core/render.ts

@@ -0,0 +1,16 @@
+import type { ReactElement } from 'react'
+import { render } from 'react-email'
+
+export interface RenderedBody {
+  html: string
+  text: string
+}
+
+/** A function that turns a React Email component into HTML + plain text. */
+export type EmailRenderer = (react: ReactElement) => Promise<RenderedBody>
+
+/** Default renderer backed by `@react-email/render`. */
+export const renderEmail: EmailRenderer = async (react) => {
+  const [html, text] = await Promise.all([render(react), render(react, { plainText: true })])
+  return { html, text }
+}

package/_stack/apps/next-base/src/server/email/factory.ts

@@ -0,0 +1,47 @@
+import { normalizeAddress, normalizeRecipients } from './core/address'
+import type { Mailer, MailerAdapter, MailRecipient, RenderedMessage } from './core/port'
+import { type EmailRenderer, renderEmail } from './core/render'
+
+export interface CreateMailerOptions {
+  /** The provider implementation (Resend, Brevo, …). */
+  adapter: MailerAdapter
+  /** Default sender used when a message omits `from`. */
+  from: MailRecipient
+  /** Override the React Email renderer (mostly for tests). */
+  render?: EmailRenderer
+}
+
+/**
+ * Build a {@link Mailer}. This is the composition root: pick the adapter here,
+ * the rest of the app depends only on the `Mailer` port.
+ *
+ * The mailer renders the React body to HTML + plain text, normalizes every
+ * address, applies the default sender, then hands a {@link RenderedMessage} to
+ * the adapter.
+ */
+export function createMailer(options: CreateMailerOptions): Mailer {
+  const defaultFrom = normalizeAddress(options.from)
+  const render = options.render ?? renderEmail
+
+  return {
+    async send(message) {
+      const { html, text } = await render(message.react)
+
+      const rendered: RenderedMessage = {
+        to: normalizeRecipients(message.to),
+        from: message.from ? normalizeAddress(message.from) : defaultFrom,
+        subject: message.subject,
+        html,
+        text,
+        replyTo: message.replyTo ? normalizeAddress(message.replyTo) : undefined,
+        cc: message.cc ? normalizeRecipients(message.cc) : undefined,
+        bcc: message.bcc ? normalizeRecipients(message.bcc) : undefined,
+        headers: message.headers,
+        tags: message.tags,
+        attachments: message.attachments,
+      }
+
+      return options.adapter.send(rendered)
+    },
+  }
+}

package/_stack/apps/next-base/src/server/email/index.ts

@@ -0,0 +1,36 @@
+import type { ReactElement } from 'react'
+import { env } from '~/env'
+import { resendAdapter } from './adapters/resend/index'
+import type { MailAddress, Mailer } from './core/port'
+import { createMailer } from './factory'
+
+export type EmailRecipient = MailAddress
+
+function required(value: string | undefined, name: string): string {
+  if (!value) throw new Error(`${name} is required to send email`)
+  return value
+}
+
+// Lazy so the app boots without RESEND_API_KEY; the adapter is built on first send.
+let mailer: Mailer | null = null
+function getMailer(): Mailer {
+  if (!mailer) {
+    mailer = createMailer({
+      from: env.EMAIL_FROM,
+      adapter: resendAdapter({ apiKey: required(env.RESEND_API_KEY, 'RESEND_API_KEY') }),
+    })
+  }
+  return mailer
+}
+
+export async function sendEmail(params: {
+  to: EmailRecipient
+  subject: string
+  template: ReactElement
+}) {
+  return getMailer().send({
+    to: params.to,
+    subject: params.subject,
+    react: params.template,
+  })
+}

package/_stack/apps/next-base/src/trpc/query-client.ts

@@ -0,0 +1,19 @@
+import { defaultShouldDehydrateQuery, QueryClient } from '@tanstack/react-query'
+import SuperJSON from 'superjson'
+
+export const createQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 30 * 1000,
+      },
+      dehydrate: {
+        serializeData: SuperJSON.serialize,
+        shouldDehydrateQuery: (query) =>
+          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
+      },
+      hydrate: {
+        deserializeData: SuperJSON.deserialize,
+      },
+    },
+  })

package/_stack/apps/next-base/src/trpc/react.tsx

@@ -0,0 +1,62 @@
+'use client'
+
+import { type QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { httpBatchStreamLink, loggerLink } from '@trpc/client'
+import { createTRPCReact } from '@trpc/react-query'
+import type { inferRouterInputs, inferRouterOutputs } from '@trpc/server'
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+import SuperJSON from 'superjson'
+import type { AppRouter } from '~/server/api/root'
+import { createQueryClient } from './query-client'
+
+let clientQueryClientSingleton: QueryClient | undefined
+const getQueryClient = () => {
+  if (typeof window === 'undefined') {
+    // Server: always make a new query client.
+    return createQueryClient()
+  }
+  // Browser: reuse the same query client across renders.
+  clientQueryClientSingleton ??= createQueryClient()
+  return clientQueryClientSingleton
+}
+
+export const api = createTRPCReact<AppRouter>()
+
+export type RouterInputs = inferRouterInputs<AppRouter>
+
+export type RouterOutputs = inferRouterOutputs<AppRouter>
+
+function getBaseUrl() {
+  if (typeof window !== 'undefined') return window.location.origin
+  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`
+  return `http://localhost:${process.env.PORT ?? 3000}`
+}
+
+export function TRPCReactProvider(props: { children: ReactNode }) {
+  const queryClient = getQueryClient()
+
+  const [trpcClient] = useState(() =>
+    api.createClient({
+      links: [
+        loggerLink({
+          enabled: (op) =>
+            process.env.NODE_ENV === 'development' ||
+            (op.direction === 'down' && op.result instanceof Error),
+        }),
+        httpBatchStreamLink({
+          transformer: SuperJSON,
+          url: `${getBaseUrl()}/api/trpc`,
+        }),
+      ],
+    }),
+  )
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <api.Provider client={trpcClient} queryClient={queryClient}>
+        {props.children}
+      </api.Provider>
+    </QueryClientProvider>
+  )
+}

package/_stack/apps/next-base/src/trpc/server.ts

@@ -0,0 +1,23 @@
+import 'server-only'
+
+import { createHydrationHelpers } from '@trpc/react-query/rsc'
+import { headers } from 'next/headers'
+import { cache } from 'react'
+import { type AppRouter, createCaller } from '~/server/api/root'
+import { createTRPCContext } from '~/server/api/trpc'
+import { createQueryClient } from './query-client'
+
+/** Context for tRPC calls made from React Server Components. */
+const createContext = cache(async () => {
+  const heads = new Headers(await headers())
+  heads.set('x-trpc-source', 'rsc')
+  return createTRPCContext({ headers: heads })
+})
+
+const getQueryClient = cache(createQueryClient)
+const caller = createCaller(createContext)
+
+export const { trpc: api, HydrateClient } = createHydrationHelpers<AppRouter>(
+  caller,
+  getQueryClient,
+)

package/_stack/apps/next-base/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/_stack/apps/tanstack-base/.dockerignore

@@ -0,0 +1,13 @@
+node_modules
+.output
+.nitro
+.tanstack
+dist
+.git
+.env
+.env.*
+!.env.example
+src/routeTree.gen.ts
+Dockerfile
+.dockerignore
+README.md

package/_stack/apps/tanstack-base/Dockerfile

@@ -0,0 +1,28 @@
+# syntax=docker/dockerfile:1
+# Optimized multi-stage build for VPS deployment (TanStack Start + Nitro).
+# `vite build` emits a self-contained Nitro server under .output/ (deps bundled),
+# so the runner image carries only that — no node_modules, no dev deps.
+
+FROM node:22-alpine AS base
+RUN corepack enable
+WORKDIR /app
+
+# ---- build (needs dev deps for vite/nitro) ----
+FROM base AS build
+COPY package.json pnpm-lock.yaml* ./
+RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
+    pnpm install --frozen-lockfile
+COPY . .
+# Env is validated at runtime, not build — skip it so the build needs no secrets.
+ENV SKIP_ENV_VALIDATION=1
+RUN pnpm build
+
+# ---- runner: just the Nitro output ----
+FROM base AS runner
+ENV NODE_ENV=production
+RUN addgroup -g 1001 nodejs && adduser -u 1001 -G nodejs -S tanstack
+COPY --from=build --chown=tanstack:nodejs /app/.output ./.output
+USER tanstack
+EXPOSE 3000
+ENV PORT=3000 HOST=0.0.0.0
+CMD ["node", ".output/server/index.mjs"]

package/_stack/apps/tanstack-base/README.md

@@ -0,0 +1,31 @@
+# tanstack-base
+
+Reference TanStack Start app — fork it to start a new project. Comes wired with
+the full personal foundation:
+
+- **baseline** — `~/*` alias, typed `env.ts`, strict Biome, Tailwind v4 + shadcn
+  (Geist, dark mode)
+- **data** — Drizzle (Postgres) + drizzle-kit, faker seed harness
+- **auth** — better-auth (email/password + verification, optional Google) + a full
+  auth UI (sign-in/up, forgot/reset, verify) with `@tanstack/react-form`
+- **email** — mailer (Resend) + email-kit templates (`email:dev` studio)
+- **API** — tRPC (`useTRPC`) + TanStack React Query with SSR hydration
+- **UI utilities** — theme toggle (light/dark/system), DataTable, DatePicker
+- **deploy** — multi-stage `Dockerfile` (Nitro output) for a VPS
+
+```bash
+pnpm --filter @alfredmouelle/tanstack-base dev    # http://localhost:3000
+```
+
+Add more swappable tools with **add-capability**.
+
+# Author
+
+Alfred MOUELLE | FullStack Developer
+
+[![ComeUp](https://img.shields.io/static/v1?style=for-the-badge&label=&message=ComeUp&color=yellow)](https://comeup.com/@alfredmouelle)
+[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/alfredmouelle)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/alfredmouelle)
+[![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://twitter.com/kali47_)
+[![Gmail](https://img.shields.io/badge/Gmail-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:alfredmouelle@gmail.com)
+[![Portfolio](https://img.shields.io/static/v1?style=for-the-badge&label=&message=Portfolio&color=blue)](https://alfredmouelle.com)

package/_stack/apps/tanstack-base/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-luma",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "~/components",
+    "utils": "~/lib/utils",
+    "ui": "~/components/ui",
+    "lib": "~/lib",
+    "hooks": "~/hooks"
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "menuColor": "default-translucent",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/_stack/apps/tanstack-base/drizzle.config.ts

@@ -0,0 +1,16 @@
+import { config } from 'dotenv'
+import { defineConfig } from 'drizzle-kit'
+
+config({ path: ['.env.local', '.env'] })
+
+const url = process.env.DATABASE_URL
+if (!url) {
+  throw new Error('DATABASE_URL is not set')
+}
+
+export default defineConfig({
+  out: './drizzle',
+  schema: './src/server/db/schemas/*.schema.ts',
+  dialect: 'postgresql',
+  dbCredentials: { url },
+})

package/_stack/apps/tanstack-base/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@alfredmouelle/tanstack-base",
+  "private": true,
+  "type": "module",
+  "author": {
+    "name": "Alfred MOUELLE",
+    "email": "alfredmouelle@gmail.com",
+    "url": "https://alfredmouelle.com"
+  },
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "generate-routes": "tsr generate",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "email:dev": "email dev --dir src/emails --port 3001",
+    "typecheck": "tsr generate && tsc --noEmit",
+    "check": "biome check .",
+    "check:unsafe": "biome check --write --unsafe .",
+    "check:write": "biome check --write .",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "db:seed": "tsx src/server/db/seed.ts"
+  },
+  "dependencies": {
+    "@fontsource-variable/geist": "^5.2.9",
+    "@t3-oss/env-core": "^0.13.11",
+    "@tailwindcss/vite": "^4.3.1",
+    "@tanstack/react-devtools": "^0.10.7",
+    "@tanstack/react-router": "^1.170.16",
+    "@tanstack/react-router-devtools": "^1.167.0",
+    "@tanstack/react-router-ssr-query": "^1.167.1",
+    "@tanstack/react-form": "^1.33.0",
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-query-devtools": "^5.101.0",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-start": "^1.168.26",
+    "@tanstack/router-plugin": "^1.132.0",
+    "@trpc/client": "^11.17.0",
+    "@trpc/server": "^11.17.0",
+    "@trpc/tanstack-react-query": "^11.17.0",
+    "better-auth": "^1.6.19",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.4.0",
+    "drizzle-orm": "^0.45.2",
+    "lucide-react": "^0.545.0",
+    "nitro": "3.0.260522-beta",
+    "pg": "^8.21.0",
+    "radix-ui": "^1.6.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-day-picker": "^10.0.1",
+    "react-email": "^6.6.3",
+    "resend": "^6.14.0",
+    "superjson": "^2.2.2",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.1",
+    "valibot": "^1.4.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@faker-js/faker": "^10.5.0",
+    "@tailwindcss/typography": "^0.5.16",
+    "@tanstack/devtools-vite": "^0.8.0",
+    "@tanstack/router-cli": "^1.132.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.10.2",
+    "@types/pg": "^8.15.6",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "drizzle-kit": "^0.31.10",
+    "dotenv": "^17.2.4",
+    "jsdom": "^28.1.0",
+    "tsx": "^4.22.4",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.5"
+  }
+}

package/_stack/apps/tanstack-base/public/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "TanStack App",
+  "name": "Create TanStack App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

package/_stack/apps/tanstack-base/public/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:

package/_stack/apps/tanstack-base/src/components/data-table.tsx

@@ -0,0 +1,77 @@
+import { flexRender, type Table as ReactTable } from '@tanstack/react-table'
+import { Skeleton } from '~/components/ui/skeleton'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '~/components/ui/table'
+
+interface DataTableProps<TData> {
+  table: ReactTable<TData>
+  columnCount: number
+  isLoading: boolean
+  emptyLabel: string
+  skeletonRows?: number
+}
+
+export function DataTable<TData>({
+  table,
+  columnCount,
+  isLoading,
+  emptyLabel,
+  skeletonRows = 3,
+}: DataTableProps<TData>) {
+  const rows = table.getRowModel().rows
+
+  return (
+    <div className="overflow-hidden rounded-lg border">
+      <Table>
+        <TableHeader>
+          {table.getHeaderGroups().map((headerGroup) => (
+            <TableRow key={headerGroup.id}>
+              {headerGroup.headers.map((header) => (
+                <TableHead key={header.id}>
+                  {header.isPlaceholder
+                    ? null
+                    : flexRender(header.column.columnDef.header, header.getContext())}
+                </TableHead>
+              ))}
+            </TableRow>
+          ))}
+        </TableHeader>
+        <TableBody>
+          {isLoading ? (
+            Array.from({ length: skeletonRows }, (_, rowIndex) => (
+              <TableRow key={rowIndex}>
+                {Array.from({ length: columnCount }, (_, cellIndex) => (
+                  <TableCell key={cellIndex}>
+                    <Skeleton className="h-6 w-full" />
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))
+          ) : rows.length === 0 ? (
+            <TableRow>
+              <TableCell className="h-24 text-center text-muted-foreground" colSpan={columnCount}>
+                {emptyLabel}
+              </TableCell>
+            </TableRow>
+          ) : (
+            rows.map((row) => (
+              <TableRow className="group" key={row.id}>
+                {row.getVisibleCells().map((cell) => (
+                  <TableCell key={cell.id}>
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))
+          )}
+        </TableBody>
+      </Table>
+    </div>
+  )
+}

package/_stack/apps/tanstack-base/src/components/form/field-error.tsx

@@ -0,0 +1,18 @@
+import type { AnyFieldApi } from '@tanstack/react-form'
+
+const errorMessage = (error: unknown): string =>
+  typeof error === 'string' ? error : ((error as { message?: string } | undefined)?.message ?? '')
+
+export function hasFieldError(field: AnyFieldApi): boolean {
+  return field.state.meta.isTouched && field.state.meta.errors.length > 0
+}
+
+export function FieldError({ field }: { field: AnyFieldApi }) {
+  const { isTouched, errors } = field.state.meta
+  if (!isTouched || errors.length === 0) return null
+
+  const message = errors.map(errorMessage).filter(Boolean).join(', ')
+  if (!message) return null
+
+  return <p className="text-destructive text-xs">{message}</p>
+}