@alfredmouelle/create-stack 0.1.0

package/_stack/apps/tanstack-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/tanstack-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/tanstack-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/tanstack-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/tanstack-base/src/styles.css

@@ -0,0 +1,171 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@fontsource-variable/geist";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.511 0.096 186.391);
+  --primary-foreground: oklch(0.984 0.014 180.72);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --radius: 0.45rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.6 0.118 184.704);
+  --sidebar-primary-foreground: oklch(0.984 0.014 180.72);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.437 0.078 188.216);
+  --primary-foreground: oklch(0.984 0.014 180.72);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.637 0.237 25.331);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.704 0.14 182.503);
+  --sidebar-primary-foreground: oklch(0.277 0.046 192.524);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@theme inline {
+  --font-sans: "Geist Variable", sans-serif;
+  --font-heading: var(--font-sans);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+  }
+}
+
+@layer utilities {
+  .scrollbar {
+    scrollbar-width: thin;
+    scrollbar-color: var(--border) transparent;
+  }
+  .scrollbar::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+  }
+  .scrollbar::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  .scrollbar::-webkit-scrollbar-thumb {
+    background-color: var(--border);
+    border-radius: var(--radius-3xl);
+  }
+  .scrollbar:hover::-webkit-scrollbar-thumb {
+    background-color: var(--muted-foreground);
+  }
+
+  .scrollbar-padded-x::-webkit-scrollbar {
+    width: 16px;
+  }
+  .scrollbar-padded-x::-webkit-scrollbar-thumb {
+    border-left: 4px solid transparent;
+    border-right: 4px solid transparent;
+    background-clip: padding-box;
+  }
+
+  .scrollbar-padded-y::-webkit-scrollbar {
+    height: 16px;
+  }
+  .scrollbar-padded-y::-webkit-scrollbar-thumb {
+    border-top: 4px solid transparent;
+    border-bottom: 4px solid transparent;
+    background-clip: padding-box;
+  }
+}

package/_stack/apps/tanstack-base/src/trpc/devtools.tsx

@@ -0,0 +1,6 @@
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
+
+export default {
+  name: 'Tanstack Query',
+  render: <ReactQueryDevtoolsPanel />,
+}

package/_stack/apps/tanstack-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/tanstack-base/src/trpc/react.tsx

@@ -0,0 +1,49 @@
+import { type QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { createTRPCClient, httpBatchStreamLink, loggerLink } from '@trpc/client'
+import type { inferRouterInputs, inferRouterOutputs } from '@trpc/server'
+import { createTRPCContext, createTRPCOptionsProxy } from '@trpc/tanstack-react-query'
+import type { ReactNode } from 'react'
+import superjson from 'superjson'
+import type { AppRouter } from '~/server/api/root'
+
+export const { TRPCProvider, useTRPC } = createTRPCContext<AppRouter>()
+
+export type RouterInputs = inferRouterInputs<AppRouter>
+
+export type RouterOutputs = inferRouterOutputs<AppRouter>
+
+function getBaseUrl() {
+  if (typeof window !== 'undefined') return window.location.origin
+  return `http://localhost:${process.env.PORT ?? 3000}`
+}
+
+export const trpcClient = createTRPCClient<AppRouter>({
+  links: [
+    loggerLink({
+      enabled: (op) =>
+        process.env.NODE_ENV === 'development' ||
+        (op.direction === 'down' && op.result instanceof Error),
+    }),
+    httpBatchStreamLink({
+      transformer: superjson,
+      url: `${getBaseUrl()}/api/trpc`,
+    }),
+  ],
+})
+
+export function createServerHelpers(queryClient: QueryClient) {
+  return createTRPCOptionsProxy<AppRouter>({
+    client: trpcClient,
+    queryClient,
+  })
+}
+
+export function TRPCReactProvider(props: { children: ReactNode; queryClient: QueryClient }) {
+  return (
+    <QueryClientProvider client={props.queryClient}>
+      <TRPCProvider queryClient={props.queryClient} trpcClient={trpcClient}>
+        {props.children}
+      </TRPCProvider>
+    </QueryClientProvider>
+  )
+}

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

@@ -0,0 +1,11 @@
+import { getRequest } from '@tanstack/react-start/server'
+import { createCaller } from '~/server/api/root'
+import { createTRPCContext } from '~/server/api/trpc'
+
+export const getServerCaller = async () => {
+  const request = getRequest()
+
+  const context = await createTRPCContext({ headers: request.headers })
+
+  return createCaller(context)
+}

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

@@ -0,0 +1,27 @@
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "paths": {
+      "~/*": ["./src/*"]
+    },
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    /* Linting */
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}

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

@@ -0,0 +1,3 @@
+{
+  "target": "react"
+}

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

@@ -0,0 +1,15 @@
+import tailwindcss from '@tailwindcss/vite'
+import { devtools } from '@tanstack/devtools-vite'
+
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+
+import viteReact from '@vitejs/plugin-react'
+import { nitro } from 'nitro/vite'
+import { defineConfig } from 'vite'
+
+const config = defineConfig({
+  resolve: { tsconfigPaths: true },
+  plugins: [devtools(), nitro(), tailwindcss(), tanstackStart(), viteReact()],
+})
+
+export default config

package/_stack/packages/analytics/capability.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "analytics",
+  "description": "Product analytics behind a swappable port. Capture events and identify users; flush/shutdown to drain pending events.",
+  "port": "src/core/port.ts",
+  "defaultAdapter": "posthog",
+  "adapters": {
+    "posthog": {
+      "deps": ["posthog-node"],
+      "env": ["POSTHOG_API_KEY", "POSTHOG_HOST"],
+      "files": ["src/adapters/posthog"]
+    },
+    "plausible": {
+      "deps": ["@alfredmouelle/http"],
+      "env": ["PLAUSIBLE_DOMAIN", "PLAUSIBLE_API_HOST"],
+      "files": ["src/adapters/plausible"]
+    },
+    "noop": {
+      "deps": [],
+      "env": [],
+      "files": ["src/adapters/noop"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/packages/cache/capability.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "cache",
+  "description": "Key/value cache behind a swappable port. Values are serialized as JSON for remote stores.",
+  "port": "src/core/port.ts",
+  "defaultAdapter": "redis",
+  "adapters": {
+    "redis": {
+      "deps": ["ioredis"],
+      "env": ["REDIS_URL"],
+      "files": ["src/adapters/redis"]
+    },
+    "memory": {
+      "deps": [],
+      "env": [],
+      "files": ["src/adapters/memory"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/packages/error-tracking/capability.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "error-tracking",
+  "description": "Error reporting behind a swappable port. Capture exceptions, messages, breadcrumbs and user context, then ship them to a provider.",
+  "port": "src/core/port.ts",
+  "defaultAdapter": "sentry",
+  "adapters": {
+    "sentry": {
+      "deps": ["@sentry/node"],
+      "env": ["SENTRY_DSN", "SENTRY_ENVIRONMENT"],
+      "files": ["src/adapters/sentry"]
+    },
+    "console": {
+      "deps": [],
+      "env": [],
+      "files": ["src/adapters/console"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/packages/jobs/capability.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "jobs",
+  "description": "Background jobs / events behind a swappable port. Event-driven: define jobs against named events and trigger them; the adapter handles delivery and execution.",
+  "port": "src/core/port.ts",
+  "defaultAdapter": "inngest",
+  "adapters": {
+    "inngest": {
+      "deps": ["inngest"],
+      "env": ["INNGEST_EVENT_KEY", "INNGEST_SIGNING_KEY"],
+      "files": ["src/adapters/inngest"]
+    },
+    "trigger": {
+      "deps": ["@trigger.dev/sdk"],
+      "env": ["TRIGGER_SECRET_KEY"],
+      "files": ["src/adapters/trigger"]
+    },
+    "memory": {
+      "deps": [],
+      "env": [],
+      "files": ["src/adapters/memory"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/packages/logger/capability.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "logger",
+  "description": "Structured logging behind a swappable port. Application code depends only on the Logger interface; pick an adapter (pino, console) at the composition root.",
+  "port": "src/core/port.ts",
+  "defaultAdapter": "pino",
+  "adapters": {
+    "pino": {
+      "deps": ["pino"],
+      "env": [],
+      "files": ["src/adapters/pino"]
+    },
+    "console": {
+      "deps": [],
+      "env": [],
+      "files": ["src/adapters/console"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/packages/mailer/capability.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "mailer",
+  "description": "Transactional email. Bodies are always React Email components, rendered to HTML + plain text.",
+  "port": "src/core/port.ts",
+  "factory": "src/factory.ts",
+  "defaultAdapter": "resend",
+  "adapters": {
+    "resend": {
+      "deps": ["resend"],
+      "env": ["RESEND_API_KEY"],
+      "files": ["src/adapters/resend"]
+    },
+    "brevo": {
+      "deps": ["@getbrevo/brevo"],
+      "env": ["BREVO_API_KEY"],
+      "files": ["src/adapters/brevo"]
+    },
+    "ses": {
+      "deps": ["@aws-sdk/client-sesv2"],
+      "env": ["AWS_REGION", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+      "files": ["src/adapters/ses"]
+    }
+  },
+  "sharedDeps": ["valibot", "@react-email/render"],
+  "peerDeps": ["react", "react-dom"],
+  "sharedFiles": ["src/core", "src/factory.ts", "src/index.ts"]
+}