create-mikstack 0.1.0

package/templates/base/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["svelte.svelte-vscode", "dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
+}

package/templates/base/AGENTS.md

@@ -0,0 +1,123 @@
+# {{projectName}}
+
+SvelteKit app with Drizzle ORM, Zero (real-time sync), and better-auth.
+
+## Stack
+
+- **Framework**: SvelteKit with TypeScript
+- **Database**: PostgreSQL via Drizzle ORM
+- **Real-time**: Zero (@rocicorp/zero) for client-side sync
+- **Auth**: better-auth with magic link
+- **Styling**: See `src/app.css`
+<!-- {{#if:i18n}} -->
+- **i18n**: @mikstack/svelte-lingui (Lingui-based)
+<!-- {{/if:i18n}} -->
+
+## Key Patterns
+
+### Zero Queries & Mutations
+
+Queries: `src/lib/zero/queries.ts` — define with `defineQueries`
+Mutators: `src/lib/zero/mutators.ts` — define with `defineMutators`
+Client usage: `get_z()` from `$lib/z.svelte` returns the Zero instance
+
+```typescript
+const z = get_z();
+const query = z.q(queries.myQuery());
+const data = $derived(query.data);
+await z.mutate(mutators.myMutation(args));
+```
+
+### Auth
+
+Server: `src/lib/server/auth.ts` (better-auth config)
+Client: `src/lib/auth-client.ts` (magic link + client helpers)
+Session is available in `locals.user` and `locals.session` via `src/hooks.server.ts`.
+
+### Forms (@mikstack/form)
+
+Use `createForm` from `@mikstack/form` for client-side forms with Valibot validation.
+Ideal for Zero mutators where forms don't use SvelteKit form actions.
+
+```svelte
+<script lang="ts">
+  import { createForm } from "@mikstack/form";
+  import * as v from "valibot";
+
+  const form = createForm({
+    schema: v.object({
+      title: v.pipe(v.string(), v.minLength(1, "Required")),
+      content: v.string(),
+    }),
+    initialValues: { title: "", content: "" },
+    async onSubmit(data) {
+      await z.mutate(mutators.note.create({ id: crypto.randomUUID(), ...data }));
+      form.reset();
+    },
+  });
+</script>
+
+<form id={form.id} onsubmit={form.onsubmit}>
+  <input {...form.fields.title.as("text")} />
+  <button type="submit" disabled={form.pending}>Create</button>
+</form>
+```
+
+Key APIs: `form.fields.<name>.as(type)` for input props, `.issues()` for errors,
+`form.pending` / `form.error` / `form.result` for submit state, `form.reset()` to clear.
+
+### Notifications (@mikstack/notifications)
+
+Config: `src/lib/server/notifications.ts` (lazy-initialized via Proxy)
+Definitions: `src/lib/server/notifications/definitions.ts`
+API routes: `src/routes/api/notifications/` (mark-read, preferences)
+
+Send a notification:
+
+```typescript
+import { notif } from "$lib/server/notifications";
+await notif.send({ type: "welcome", userId: user.id, data: { userName: user.name } });
+```
+
+Define new notification types in `definitions.ts` using `defineNotification()`.
+In-app notifications sync to the client via Zero (`inAppNotification` table).
+Email delivery tracking and retries are handled automatically.
+
+### Database
+
+Schema: `src/lib/server/db/schema.ts`
+Connection: `src/lib/server/db/index.ts` (lazy-initialized via Proxy)
+
+<!-- {{#if:i18n}} -->
+### i18n
+
+Setup: `src/lib/i18n.ts` — initialized in root layout
+Config: `lingui.config.ts`
+Catalogs: `src/locales/{locale}.po`
+
+Use `useLingui()` for translations, `<T>` component for rich text:
+
+```svelte
+<script lang="ts">
+  import { useLingui } from "@mikstack/svelte-lingui";
+  const { t } = useLingui();
+</script>
+
+<h1>{t`Hello world`}</h1>
+```
+
+Run `{{pmRun}} i18n:extract` to extract messages into `.po` catalogs.
+<!-- {{/if:i18n}} -->
+
+## Commands
+
+- `{{pmRun}} dev` — start dev server
+- `{{pmRun}} build` — production build
+- `{{pmRun}} db:push` — push schema to database
+- `{{pmRun}} db:seed` — seed database
+- `{{pmRun}} zero:generate` — generate Zero schema from Drizzle
+- `{{pmRun}} lint` — run ESLint
+- `{{pmRun}} format` — format with Prettier
+<!-- {{#if:i18n}} -->
+- `{{pmRun}} i18n:extract` — extract messages to .po catalogs
+<!-- {{/if:i18n}} -->

package/templates/base/README.md

@@ -0,0 +1,27 @@
+# {{projectName}}
+
+Built with [mikstack](https://github.com/mikaelsiidorow/mikstack).
+
+## Getting Started
+
+```bash
+{{pmRun}} db:start
+{{pmRun}} db:push
+{{pmRun}} db:seed
+{{pmRun}} dev
+```
+
+## Scripts
+
+- `{{pmRun}} dev` — Start dev server
+- `{{pmRun}} build` — Build for production
+- `{{pmRun}} preview` — Preview production build
+- `{{pmRun}} check` — Run svelte-check
+- `{{pmRun}} lint` — Lint with ESLint
+- `{{pmRun}} format` — Format with Prettier
+- `{{pmRun}} db:start` — Start Postgres (Docker)
+- `{{pmRun}} db:generate` — Generate Drizzle migrations
+- `{{pmRun}} db:migrate` — Run Drizzle migrations
+- `{{pmRun}} db:push` — Push schema to database
+- `{{pmRun}} db:studio` — Open Drizzle Studio
+- `{{pmRun}} db:seed` — Seed the database

package/templates/base/agents.md

@@ -0,0 +1,28 @@
+# Agent Guidelines for {{projectName}}
+
+## Architecture Overview
+
+This is a SvelteKit application using:
+
+- **Drizzle ORM** for database schema and migrations
+- **Zero** (@rocicorp/zero) for real-time client-side data sync
+- **better-auth** for authentication (magic link flow)
+
+## File Conventions
+
+- Server-only code: `src/lib/server/` (enforced by SvelteKit)
+- Zero schema/queries/mutators: `src/lib/zero/`
+- Auth client: `src/lib/auth-client.ts`
+- Zero client context: `src/lib/z.svelte.ts`
+- API routes for Zero: `src/routes/api/zero/`
+
+## When Modifying the Schema
+
+1. Update Drizzle schema in `src/lib/server/db/schema.ts`
+2. Run `{{pmRun}} db:push` (dev) or `{{pmRun}} db:generate` + `{{pmRun}} db:migrate` (production)
+3. Run `{{pmRun}} zero:generate` to regenerate Zero schema
+4. Update queries/mutators in `src/lib/zero/` as needed
+
+## Testing
+
+Run `{{pmRun}} check` for type checking and `{{pmRun}} lint` for linting before committing.

package/templates/base/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  db:
+    image: postgres
+    restart: always
+    ports:
+      - 5432:5432
+    environment:
+      POSTGRES_USER: root
+      POSTGRES_PASSWORD: mysecretpassword
+      POSTGRES_DB: local
+    command: ["postgres", "-c", "wal_level=logical"]
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+volumes:
+  pgdata:

package/templates/base/drizzle-zero.config.ts

@@ -0,0 +1,17 @@
+import { drizzleZeroConfig } from "drizzle-zero";
+import * as schema from "./src/lib/server/db/schema";
+
+export default drizzleZeroConfig(schema, {
+  tables: {
+    user: true,
+    note: true,
+    inAppNotification: true,
+    // Exclude auth-internal and server-only tables from client sync
+    session: false,
+    account: false,
+    verification: false,
+    notificationDelivery: false,
+    notificationPreference: false,
+  },
+  casing: "snake_case",
+});

package/templates/base/drizzle.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "drizzle-kit";
+import { existsSync } from "fs";
+
+if (existsSync(".env")) {
+  process.loadEnvFile();
+}
+
+const DATABASE_URL = process.env.DATABASE_URL || "postgresql://placeholder";
+
+export default defineConfig({
+  schema: "./src/lib/server/db/schema.ts",
+  dialect: "postgresql",
+  dbCredentials: { url: DATABASE_URL },
+  verbose: true,
+  strict: true,
+  casing: "snake_case",
+});

package/templates/base/eslint.config.ts

@@ -0,0 +1,65 @@
+import prettier from "eslint-config-prettier";
+import { fileURLToPath } from "node:url";
+import { includeIgnoreFile } from "@eslint/compat";
+import js from "@eslint/js";
+import svelte from "eslint-plugin-svelte";
+import { defineConfig } from "eslint/config";
+import globals from "globals";
+import ts from "typescript-eslint";
+import svelteConfig from "./svelte.config.js";
+
+const gitignorePath = fileURLToPath(new URL("./.gitignore", import.meta.url));
+
+const extraFileExtensions = [".svelte"];
+
+export default defineConfig(
+  includeIgnoreFile(gitignorePath),
+  { ignores: ["!*.gen.ts"] },
+  js.configs.recommended,
+  ...ts.configs.recommendedTypeChecked,
+  ...svelte.configs.recommended,
+  prettier,
+  ...svelte.configs.prettier,
+  {
+    languageOptions: {
+      globals: { ...globals.browser, ...globals.node },
+      parserOptions: {
+        projectService: true,
+        extraFileExtensions,
+      },
+    },
+    rules: {
+      "no-undef": "off",
+      "no-restricted-imports": [
+        "error",
+        {
+          paths: [
+            {
+              name: "$app/stores",
+              message: "Use $app/state instead of $app/stores.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    files: ["**/*.svelte", "**/*.svelte.ts", "**/*.svelte.js"],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        parser: ts.parser,
+        svelteConfig,
+        extraFileExtensions,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+      "@typescript-eslint/no-unnecessary-type-assertion": "off",
+    },
+  },
+);

package/templates/base/package.json.partial

@@ -0,0 +1,43 @@
+{
+  "scripts": {
+    "check": "drizzle-zero generate --output src/lib/zero/zero-schema.gen.ts && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "drizzle-zero generate --output src/lib/zero/zero-schema.gen.ts && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "lint": "drizzle-zero generate --output src/lib/zero/zero-schema.gen.ts && eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "db:start": "docker compose up -d",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "db:seed": "{{seedRunner}} src/lib/server/db/seed.ts",
+    "zero:generate": "drizzle-zero generate --output src/lib/zero/zero-schema.gen.ts",
+    "zero:start": "zero-cache-server"
+  },
+  "dependencies": {
+    "@mikstack/email": "^0.1.0",
+    "@mikstack/form": "^0.1.0",
+    "@mikstack/notifications": "^0.1.0",
+    "@rocicorp/zero": "^0.25.12",
+    "better-auth": "^1.4.18",
+    "drizzle-orm": "^0.45.1",
+    "nodemailer": "^8.0.1",
+    "postgres": "^3.4.8",
+    "valibot": "^1.2.0",
+    "zero-svelte": "^1.2.2"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^1.4.1",
+    "@eslint/js": "^9.39.2",
+    "@types/nodemailer": "^7.0.9",
+    "drizzle-kit": "^0.31.8",
+    "drizzle-zero": "^0.17.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-svelte": "^3.14.0",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-svelte": "^3.4.1",
+    "typescript-eslint": "^8.54.0"
+  }
+}

package/templates/base/prettier.config.js

@@ -0,0 +1,6 @@
+/** @type {import("prettier").Config} */
+export default {
+  printWidth: 100,
+  plugins: ["prettier-plugin-svelte"],
+  overrides: [{ files: "*.svelte", options: { parser: "svelte" } }],
+};

package/templates/base/src/app.d.ts

@@ -0,0 +1,12 @@
+import type { Session, User } from "$lib/server/auth";
+
+declare global {
+  namespace App {
+    interface Locals {
+      user: User | null;
+      session: Session | null;
+    }
+  }
+}
+
+export {};

package/templates/base/src/app.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    %sveltekit.head%
+  </head>
+  <body data-sveltekit-preload-data="hover">
+    <div style="display: contents">%sveltekit.body%</div>
+  </body>
+</html>

package/templates/base/src/hooks.server.ts

@@ -0,0 +1,15 @@
+import type { Handle } from "@sveltejs/kit";
+import { auth } from "$lib/server/auth";
+import { svelteKitHandler } from "better-auth/svelte-kit";
+import { building } from "$app/environment";
+
+export const handle: Handle = async ({ event, resolve }) => {
+  const session = await auth.api.getSession({
+    headers: event.request.headers,
+  });
+
+  event.locals.user = session?.user ?? null;
+  event.locals.session = session?.session ?? null;
+
+  return svelteKitHandler({ event, resolve, auth, building });
+};

package/templates/base/src/lib/auth-client.ts

@@ -0,0 +1,6 @@
+import { createAuthClient } from "better-auth/client";
+import { magicLinkClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [magicLinkClient()],
+});

package/templates/base/src/lib/server/auth.ts

@@ -0,0 +1,52 @@
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { magicLink } from "better-auth/plugins";
+import { sveltekitCookies } from "better-auth/svelte-kit";
+import { getRequestEvent } from "$app/server";
+import { building } from "$app/environment";
+import { env } from "$env/dynamic/private";
+import { db } from "./db";
+import * as schema from "./db/schema";
+import { notif } from "./notifications";
+
+let _auth: Auth | undefined;
+
+function createAuth() {
+  return betterAuth({
+    baseURL: env.BETTER_AUTH_URL,
+    database: drizzleAdapter(db, {
+      provider: "pg",
+      schema,
+    }),
+    plugins: [
+      magicLink({
+        sendMagicLink: async ({ email, url }) => {
+          await notif.send({
+            type: "magic-link",
+            userId: email, // before user exists, use email as userId
+            recipientEmail: email,
+            data: { url },
+          });
+        },
+      }),
+      sveltekitCookies(getRequestEvent),
+    ],
+  });
+}
+
+type Auth = ReturnType<typeof createAuth>;
+
+export const auth: Auth = new Proxy({} as Auth, {
+  get(_, prop) {
+    if (building) {
+      throw new Error("Cannot access auth during build");
+    }
+    if (!_auth) {
+      _auth = createAuth();
+    }
+    return (_auth as unknown as Record<string | symbol, unknown>)[prop];
+  },
+});
+
+export type Session = Auth["$Infer"]["Session"]["session"];
+export type User = Auth["$Infer"]["Session"]["user"];

package/templates/base/src/lib/server/db/index.ts

@@ -0,0 +1,19 @@
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import * as schema from "./schema";
+import { env } from "$env/dynamic/private";
+
+export type DrizzleDB = ReturnType<typeof drizzle<typeof schema>>;
+
+let _db: DrizzleDB | undefined;
+
+export const db = new Proxy({} as DrizzleDB, {
+  get(_, prop) {
+    if (!_db) {
+      if (!env.DATABASE_URL) throw new Error("DATABASE_URL is not set");
+      const client = postgres(env.DATABASE_URL);
+      _db = drizzle(client, { schema, casing: "snake_case" });
+    }
+    return _db[prop as keyof typeof _db];
+  },
+});

package/templates/base/src/lib/server/db/schema.ts

@@ -0,0 +1,117 @@
+import { boolean, integer, jsonb, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+// better-auth tables (managed by better-auth, do not insert/update directly)
+export const user = pgTable("user", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
+  emailVerified: timestamp("email_verified"),
+  image: text("image"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const session = pgTable("session", {
+  id: text("id").primaryKey(),
+  expiresAt: timestamp("expires_at").notNull(),
+  token: text("token").notNull().unique(),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const account = pgTable("account", {
+  id: text("id").primaryKey(),
+  accountId: text("account_id").notNull(),
+  providerId: text("provider_id").notNull(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+  accessToken: text("access_token"),
+  refreshToken: text("refresh_token"),
+  idToken: text("id_token"),
+  accessTokenExpiresAt: timestamp("access_token_expires_at"),
+  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+  scope: text("scope"),
+  password: text("password"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const verification = pgTable("verification", {
+  id: text("id").primaryKey(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at"),
+  updatedAt: timestamp("updated_at"),
+});
+
+// Notification tables (managed by @mikstack/notifications)
+export const notificationDelivery = pgTable("notification_delivery", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+  type: text("type").notNull(),
+  channel: text("channel").notNull(),
+  status: text("status", { enum: ["pending", "sent", "delivered", "failed"] })
+    .notNull()
+    .default("pending"),
+  content: jsonb("content"),
+  error: text("error"),
+  retryOf: text("retry_of"),
+  retriesLeft: integer("retries_left").notNull().default(0),
+  recipientEmail: text("recipient_email"),
+  externalId: text("external_id"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const inAppNotification = pgTable("in_app_notification", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+  type: text("type").notNull(),
+  title: text("title").notNull(),
+  body: text("body"),
+  url: text("url"),
+  icon: text("icon"),
+  read: boolean("read").notNull().default(false),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+});
+
+export const notificationPreference = pgTable("notification_preference", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+  notificationType: text("notification_type").notNull(),
+  channel: text("channel").notNull(),
+  enabled: boolean("enabled").notNull(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+// Application tables
+
+export const note = pgTable("note", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content").notNull().default(""),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id),
+  createdAt: timestamp("created_at").notNull(),
+  updatedAt: timestamp("updated_at").notNull(),
+});

package/templates/base/src/lib/server/db/seed.ts

@@ -0,0 +1,21 @@
+/**
+ * Database seed script.
+ *
+ * Run with: {{pmRun}} db:seed
+ */
+
+// import { db } from './index';
+
+// eslint-disable-next-line @typescript-eslint/require-await
+async function seed() {
+  console.log("Seeding database...");
+
+  // Add your seed data here
+
+  console.log("Seeding complete.");
+}
+
+seed().catch((err) => {
+  console.error("Seed failed:", err);
+  process.exit(1);
+});