create-mikstack 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# create-mikstack
+
+Scaffold an opinionated SvelteKit project.
+
+```bash
+bun create mikstack@latest
+pnpm create mikstack@latest
+npm create mikstack@latest
+```
+
+## What you get
+
+**Always included:**
+
+- SvelteKit with TypeScript
+- PostgreSQL + Drizzle ORM (with Docker Compose)
+- better-auth with magic link (dev mode logs links to console)
+- ESLint (type-aware, flat config) + Prettier
+- `.env.example` with all keys stubbed
+
+**Configurable:**
+
+| Feature           | Default      | Options                              |
+| ----------------- | ------------ | ------------------------------------ |
+| UI                | Tailwind CSS | Tailwind / vanilla CSS (+ Stylelint) |
+| Testing           | on           | Vitest + testcontainers              |
+| GitHub Actions CI | on           | lint, format, typecheck, build       |
+| SvelteKit adapter | node         | node / vercel / cloudflare           |
+
+## Usage
+
+### Interactive
+
+```bash
+bun create mikstack@latest my-app
+```
+
+Prompts you to choose between recommended defaults or customize each option.
+
+### Non-interactive
+
+```bash
+bun create mikstack@latest my-app --yes
+```
+
+Scaffolds with all recommended defaults. Also activates when `CI=true`.
+
+## Package manager detection
+
+Automatically detected from `npm_config_user_agent`. Affects:
+
+- `package.json` scripts
+- `README.md` commands
+- GitHub Actions CI workflow (separate template per PM)

package/dist/index.js

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+import * as p from "@clack/prompts";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+
+//#region src/config.ts
+const defaults = {
+	mode: "recommended",
+	uiMode: "dependency",
+	i18n: true,
+	testing: true,
+	githubActions: true,
+	adapter: "node"
+};
+
+//#endregion
+//#region src/pm.ts
+function detectPackageManager() {
+	const ua = process.env.npm_config_user_agent;
+	if (!ua) return "npm";
+	if (ua.startsWith("pnpm/")) return "pnpm";
+	if (ua.startsWith("bun/")) return "bun";
+	return "npm";
+}
+function pmInstall(pm) {
+	return pm === "npm" ? "npm install" : `${pm} install`;
+}
+function pmRun(pm) {
+	return pm === "npm" ? "npm run" : `${pm} run`;
+}
+function pmExec(pm) {
+	if (pm === "npm") return "npx";
+	if (pm === "pnpm") return "pnpm exec";
+	return "bunx";
+}
+function pmLockfile(pm) {
+	if (pm === "npm") return "package-lock.json";
+	if (pm === "pnpm") return "pnpm-lock.yaml";
+	return "bun.lock";
+}
+
+//#endregion
+//#region src/post-scaffold.ts
+function postScaffold(targetDir, packageManager) {
+	const cwd = path.resolve(process.cwd(), targetDir);
+	const run = (cmd) => execSync(cmd, {
+		cwd,
+		stdio: "pipe"
+	});
+	const s = p.spinner();
+	s.start("Installing dependencies...");
+	try {
+		run(`${packageManager} install`);
+		s.stop("Dependencies installed.");
+	} catch {
+		s.stop("Failed to install dependencies. You can run install manually.");
+	}
+	try {
+		run(`${packageManager} run format`);
+	} catch {}
+	s.start("Initializing git repository...");
+	try {
+		run("git init");
+		run("git add .");
+		run("git commit -m \"the future is now\"");
+		s.stop("Git repository initialized.");
+	} catch {
+		s.stop("Failed to initialize git. You can run git init manually.");
+	}
+}
+
+//#endregion
+//#region src/prompts.ts
+function isCancel(value) {
+	return p.isCancel(value);
+}
+function onCancel() {
+	p.cancel("Operation cancelled.");
+	process.exit(0);
+}
+async function runPrompts(projectName, packageManager) {
+	p.intro("create-mikstack");
+	if (!projectName) {
+		const name = await p.text({
+			message: "Project name:",
+			placeholder: "my-app",
+			validate(value) {
+				if (!value.trim()) return "Project name is required.";
+				if (!/^[a-z0-9][a-z0-9._-]*$/.test(value)) return "Invalid package name. Use lowercase, numbers, hyphens, dots, and underscores.";
+			}
+		});
+		if (isCancel(name)) onCancel();
+		projectName = name;
+	}
+	const targetDir = projectName;
+	const mode = await p.select({
+		message: "Setup mode:",
+		options: [{
+			value: "recommended",
+			label: "Recommended (full stack)"
+		}, {
+			value: "customize",
+			label: "Customize"
+		}]
+	});
+	if (isCancel(mode)) onCancel();
+	if (mode === "recommended") {
+		p.outro(`Scaffolding ${projectName} with recommended defaults...`);
+		return {
+			projectName,
+			targetDir,
+			packageManager,
+			...defaults
+		};
+	}
+	const uiMode = await p.select({
+		message: "UI components (@mikstack/ui):",
+		options: [{
+			value: "dependency",
+			label: "Dependency (import from package)"
+		}, {
+			value: "vendor",
+			label: "Vendor (copy into project)"
+		}]
+	});
+	if (isCancel(uiMode)) onCancel();
+	const i18n = await p.confirm({
+		message: "Include i18n? (@mikstack/svelte-lingui)",
+		initialValue: true
+	});
+	if (isCancel(i18n)) onCancel();
+	const testing = await p.confirm({
+		message: "Include testing setup? (Vitest + testcontainers)",
+		initialValue: true
+	});
+	if (isCancel(testing)) onCancel();
+	const githubActions = await p.confirm({
+		message: "Include GitHub Actions CI?",
+		initialValue: true
+	});
+	if (isCancel(githubActions)) onCancel();
+	const adapter = await p.select({
+		message: "SvelteKit adapter:",
+		options: [
+			{
+				value: "node",
+				label: "Node"
+			},
+			{
+				value: "vercel",
+				label: "Vercel"
+			},
+			{
+				value: "cloudflare",
+				label: "Cloudflare"
+			}
+		]
+	});
+	if (isCancel(adapter)) onCancel();
+	p.outro(`Scaffolding ${projectName}...`);
+	return {
+		projectName,
+		targetDir,
+		packageManager,
+		mode,
+		uiMode,
+		i18n,
+		testing,
+		githubActions,
+		adapter
+	};
+}
+
+//#endregion
+//#region src/template-engine.ts
+const CONDITIONAL_BLOCK_RE = /^[^\S\n]*(?:\/\/|#|<!--)[^\S\n]*\{\{#if:(\w+)\}\}[^\S\n]*(?:-->)?[^\S\n]*\n([\s\S]*?)^[^\S\n]*(?:\/\/|#|<!--)[^\S\n]*\{\{\/if:\1\}\}[^\S\n]*(?:-->)?[^\S\n]*\n?/gm;
+const VARIABLE_RE = /\{\{(\w+)\}\}/g;
+function renderTemplate(content, context) {
+	let result = content.replace(CONDITIONAL_BLOCK_RE, (_match, name, body) => {
+		if (context[name]) return body;
+		return "";
+	});
+	result = result.replace(VARIABLE_RE, (_match, name) => {
+		const value = context[name];
+		if (value === void 0) throw new Error(`Undefined template variable: {{${name}}}`);
+		return String(value);
+	});
+	return result;
+}
+
+//#endregion
+//#region src/scaffold.ts
+const TEMPLATES_DIR = path.resolve(import.meta.dirname, "..", "templates");
+function scaffold(config) {
+	const target = path.resolve(process.cwd(), config.targetDir);
+	if (fs.existsSync(target)) {
+		if (fs.readdirSync(target).length > 0) throw new Error(`Target directory "${config.targetDir}" is not empty. Please choose a different name or remove the directory.`);
+	}
+	execSync(`${path.resolve(import.meta.dirname, "..", "node_modules", ".bin", "sv")} create ${target} --template minimal --types ts --add devtools-json --no-install`, { stdio: "pipe" });
+	const overlay = (dir) => {
+		copyDir(dir, target);
+		mergePartials(target);
+	};
+	overlay(path.join(TEMPLATES_DIR, "base"));
+	if (config.testing) overlay(path.join(TEMPLATES_DIR, "testing"));
+	overlay(path.join(TEMPLATES_DIR, "ui"));
+	if (config.i18n) overlay(path.join(TEMPLATES_DIR, "i18n"));
+	if (config.uiMode === "vendor") overlay(path.join(TEMPLATES_DIR, "ui-vendor"));
+	else overlay(path.join(TEMPLATES_DIR, "ui-dependency"));
+	if (config.githubActions) overlay(path.join(TEMPLATES_DIR, `github-actions-${config.packageManager}`));
+	overlay(path.join(TEMPLATES_DIR, `supply-chain-${config.packageManager}`));
+	overlay(path.join(TEMPLATES_DIR, "adapters", config.adapter));
+	renderDir(target, buildContext(config));
+	appendGitignoreFiles(target);
+	appendLockfileIgnores(target, config.packageManager);
+	fs.symlinkSync("AGENTS.md", path.join(target, "CLAUDE.md"));
+	const envExample = path.join(target, ".env.example");
+	const envFile = path.join(target, ".env");
+	if (fs.existsSync(envExample) && !fs.existsSync(envFile)) fs.copyFileSync(envExample, envFile);
+}
+function copyDir(src, dest) {
+	if (!fs.existsSync(src)) return;
+	for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+		const srcPath = path.join(src, entry.name);
+		const destPath = path.join(dest, entry.name);
+		if (entry.isDirectory()) {
+			fs.mkdirSync(destPath, { recursive: true });
+			copyDir(srcPath, destPath);
+		} else {
+			fs.mkdirSync(path.dirname(destPath), { recursive: true });
+			fs.copyFileSync(srcPath, destPath);
+		}
+	}
+}
+function mergePartials(dir) {
+	const pkgPath = path.join(dir, "package.json");
+	if (!fs.existsSync(pkgPath)) return;
+	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+	const partials = findFiles(dir, "package.json.partial");
+	for (const partialPath of partials) {
+		deepMerge(pkg, JSON.parse(fs.readFileSync(partialPath, "utf-8")));
+		fs.unlinkSync(partialPath);
+	}
+	fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+function deepMerge(target, source) {
+	for (const key of Object.keys(source)) {
+		const targetVal = target[key];
+		const sourceVal = source[key];
+		if (targetVal && sourceVal && typeof targetVal === "object" && typeof sourceVal === "object" && !Array.isArray(targetVal) && !Array.isArray(sourceVal)) deepMerge(targetVal, sourceVal);
+		else target[key] = sourceVal;
+	}
+}
+function findFiles(dir, filename) {
+	const results = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) results.push(...findFiles(fullPath, filename));
+		else if (entry.name === filename) results.push(fullPath);
+	}
+	return results;
+}
+function buildContext(config) {
+	return {
+		projectName: config.projectName,
+		pmInstall: pmInstall(config.packageManager),
+		pmRun: pmRun(config.packageManager),
+		pmExec: pmExec(config.packageManager),
+		pm: config.packageManager,
+		lockfile: pmLockfile(config.packageManager),
+		adapter: config.adapter,
+		seedRunner: config.packageManager === "bun" ? "bun" : "node --experimental-strip-types --env-file=.env",
+		i18n: config.i18n,
+		testing: config.testing,
+		githubActions: config.githubActions,
+		uiVendor: config.uiMode === "vendor",
+		uiPrefix: config.uiMode === "vendor" ? "$lib/components/ui" : "@mikstack/ui",
+		pmIsNpm: config.packageManager === "npm",
+		pmIsPnpm: config.packageManager === "pnpm",
+		pmIsBun: config.packageManager === "bun"
+	};
+}
+function appendGitignoreFiles(dir) {
+	const gitignorePath = path.join(dir, ".gitignore");
+	if (!fs.existsSync(gitignorePath)) return;
+	const appendFiles = findFiles(dir, ".gitignore.append");
+	if (appendFiles.length === 0) return;
+	let content = fs.readFileSync(gitignorePath, "utf-8");
+	for (const appendFile of appendFiles) {
+		const appendContent = fs.readFileSync(appendFile, "utf-8").trim();
+		if (appendContent) content = content.trimEnd() + "\n\n" + appendContent + "\n";
+		fs.unlinkSync(appendFile);
+	}
+	fs.writeFileSync(gitignorePath, content);
+}
+const ALL_LOCKFILES = {
+	"package-lock.json": "npm",
+	"pnpm-lock.yaml": "pnpm",
+	"bun.lock": "bun"
+};
+function appendLockfileIgnores(dir, pm) {
+	const gitignorePath = path.join(dir, ".gitignore");
+	const lines = Object.entries(ALL_LOCKFILES).filter(([, lockPm]) => lockPm !== pm).map(([file]) => file);
+	if (lines.length > 0) {
+		const content = fs.readFileSync(gitignorePath, "utf-8");
+		fs.writeFileSync(gitignorePath, content.trimEnd() + "\n\n# Other package manager lockfiles\n" + lines.join("\n") + "\n");
+	}
+}
+const BINARY_EXTENSIONS = new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".ico",
+	".webp",
+	".avif",
+	".woff",
+	".woff2",
+	".ttf",
+	".eot",
+	".zip",
+	".tar",
+	".gz"
+]);
+function renderDir(dir, context) {
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === ".git") continue;
+			renderDir(fullPath, context);
+		} else {
+			const ext = path.extname(entry.name).toLowerCase();
+			if (BINARY_EXTENSIONS.has(ext)) continue;
+			const content = fs.readFileSync(fullPath, "utf-8");
+			const rendered = renderTemplate(content, context);
+			if (rendered !== content) fs.writeFileSync(fullPath, rendered);
+		}
+	}
+}
+
+//#endregion
+//#region src/cli.ts
+async function cli() {
+	const { values, positionals } = parseArgs({
+		allowPositionals: true,
+		options: {
+			yes: {
+				type: "boolean",
+				short: "y",
+				default: false
+			},
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			}
+		}
+	});
+	if (values.help) {
+		printHelp();
+		return;
+	}
+	const packageManager = detectPackageManager();
+	const projectName = positionals[0];
+	const nonInteractive = values.yes || process.env.CI === "true";
+	let config;
+	if (nonInteractive) {
+		const targetDir = projectName || "my-mikstack-app";
+		config = {
+			projectName: path.basename(targetDir),
+			targetDir,
+			packageManager,
+			...defaults
+		};
+		p.intro("create-mikstack");
+		p.log.info(`Scaffolding ${config.projectName} with recommended defaults (non-interactive)...`);
+	} else config = await runPrompts(projectName, packageManager);
+	try {
+		scaffold(config);
+	} catch (err) {
+		p.log.error(err instanceof Error ? err.message : String(err));
+		process.exit(1);
+	}
+	postScaffold(config.targetDir, config.packageManager);
+	p.note([`cd ${config.targetDir}`, `${config.packageManager} run dev`].join("\n"), "Next steps");
+}
+function printHelp() {
+	console.log(`
+  create-mikstack — scaffold an opinionated SvelteKit project
+
+  Usage:
+    create-mikstack [project-name] [options]
+
+  Options:
+    -y, --yes    Use recommended defaults (non-interactive)
+    -h, --help   Show this help message
+`);
+}
+
+//#endregion
+//#region src/index.ts
+cli().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-mikstack",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MikaelSiidorow/mikstack.git",
+    "directory": "packages/create-mikstack"
+  },
+  "bin": {
+    "create-mikstack": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "type": "module",
+  "scripts": {
+    "sync:ui": "bash scripts/sync-ui-vendor.sh",
+    "build": "bun run sync:ui && tsdown",
+    "dev": "tsdown --watch",
+    "check": "tsc --noEmit",
+    "lint": "oxlint --type-aware --type-check --ignore-pattern templates && oxfmt --check src tsdown.config.ts",
+    "format": "oxfmt src tsdown.config.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "picocolors": "^1.1.1",
+    "sv": "0.12.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "oxfmt": "^0.28.0",
+    "oxlint": "^1.43.0",
+    "oxlint-tsgolint": "^0.11.4",
+    "tsdown": "^0.12.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/adapters/cloudflare/package.json.partial

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "@sveltejs/adapter-cloudflare": "^7.2.6"
+  }
+}

package/templates/adapters/cloudflare/svelte.config.js

@@ -0,0 +1,19 @@
+// {{#if:i18n}}
+import { linguiPreprocess } from "@mikstack/svelte-lingui/preprocessor";
+// {{/if:i18n}}
+import adapter from "@sveltejs/adapter-cloudflare";
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  // {{#if:i18n}}
+  preprocess: [linguiPreprocess()],
+  // {{/if:i18n}}
+  kit: {
+    adapter: adapter(),
+    experimental: {
+      remoteFunctions: true,
+    },
+  },
+};
+
+export default config;

package/templates/adapters/node/Dockerfile

@@ -0,0 +1,30 @@
+FROM node:22-slim AS base
+WORKDIR /app
+
+FROM base AS deps
+COPY package.json {{lockfile}} ./
+# {{#if:pmIsNpm}}
+RUN npm ci
+# {{/if:pmIsNpm}}
+# {{#if:pmIsPnpm}}
+RUN corepack enable && pnpm install --frozen-lockfile
+# {{/if:pmIsPnpm}}
+# {{#if:pmIsBun}}
+RUN npm i -g bun && bun install --frozen-lockfile
+# {{/if:pmIsBun}}
+
+FROM base AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+RUN npm prune --omit=dev
+
+FROM base
+WORKDIR /app
+COPY --from=build /app/build ./build
+COPY --from=build /app/node_modules ./node_modules
+COPY package.json .
+ENV NODE_ENV=production
+EXPOSE 3000
+CMD ["node", "build"]

package/templates/adapters/node/docker-compose.prod.yml

@@ -0,0 +1,27 @@
+services:
+  db:
+    image: postgres
+    restart: always
+    environment:
+      POSTGRES_USER: root
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: { { projectName } }
+    command: ["postgres", "-c", "wal_level=logical"]
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+  app:
+    build: .
+    restart: always
+    ports:
+      - 3000:3000
+    environment:
+      DATABASE_URL: postgres://root:${POSTGRES_PASSWORD}@db:5432/{{projectName}}
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      BETTER_AUTH_URL: ${BETTER_AUTH_URL}
+      ORIGIN: ${BETTER_AUTH_URL}
+    depends_on:
+      - db
+
+volumes:
+  pgdata:

package/templates/adapters/node/package.json.partial

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "@sveltejs/adapter-node": "^5.5.2"
+  }
+}

package/templates/adapters/node/svelte.config.js

@@ -0,0 +1,19 @@
+// {{#if:i18n}}
+import { linguiPreprocess } from "@mikstack/svelte-lingui/preprocessor";
+// {{/if:i18n}}
+import adapter from "@sveltejs/adapter-node";
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  // {{#if:i18n}}
+  preprocess: [linguiPreprocess()],
+  // {{/if:i18n}}
+  kit: {
+    adapter: adapter(),
+    experimental: {
+      remoteFunctions: true,
+    },
+  },
+};
+
+export default config;

package/templates/adapters/vercel/package.json.partial

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "@sveltejs/adapter-vercel": "^6.3.1"
+  }
+}

package/templates/adapters/vercel/svelte.config.js

@@ -0,0 +1,19 @@
+// {{#if:i18n}}
+import { linguiPreprocess } from "@mikstack/svelte-lingui/preprocessor";
+// {{/if:i18n}}
+import adapter from "@sveltejs/adapter-vercel";
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  // {{#if:i18n}}
+  preprocess: [linguiPreprocess()],
+  // {{/if:i18n}}
+  kit: {
+    adapter: adapter(),
+    experimental: {
+      remoteFunctions: true,
+    },
+  },
+};
+
+export default config;

package/templates/base/.env.example

@@ -0,0 +1,23 @@
+# Database (PostgreSQL with wal_level=logical required for Zero replication)
+DATABASE_URL="postgres://root:mysecretpassword@localhost:5432/local"
+ZERO_UPSTREAM_DB="postgres://root:mysecretpassword@localhost:5432/local"
+
+# Zero Cache Configuration
+ZERO_REPLICA_FILE="/tmp/{{projectName}}-sync-replica.db"
+ZERO_MUTATE_URL="http://localhost:5173/api/zero/mutate"
+ZERO_QUERY_URL="http://localhost:5173/api/zero/get-queries"
+PUBLIC_SERVER="http://localhost:4848"
+ZERO_QUERY_FORWARD_COOKIES=true
+ZERO_MUTATE_FORWARD_COOKIES=true
+
+# better-auth
+# Generate with: openssl rand -base64 32
+BETTER_AUTH_SECRET="change-me-generate-a-real-secret"
+BETTER_AUTH_URL="http://localhost:5173"
+
+# SMTP (for magic link emails in production)
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=
+# SMTP_FROM=noreply@example.com

package/templates/base/.gitignore.append

@@ -0,0 +1,2 @@
+# Generated
+*.gen.ts

package/templates/base/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "svelte": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@sveltejs/mcp"]
+    }
+  }
+}

package/templates/base/.prettierignore

@@ -0,0 +1,10 @@
+# Package Managers
+package-lock.json
+pnpm-lock.yaml
+bun.lock
+
+# Generated
+.svelte-kit
+build
+dist
+*.gen.ts