@techstream/quark-create-app 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techstream/quark-create-app",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "type": "module",
   "bin": {
     "quark-create-app": "src/index.js",

package/src/index.js

@@ -484,11 +484,11 @@ program
 # Generate strong passwords with: openssl rand -base64 32
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
-POSTGRES_USER=quark_user
+POSTGRES_USER=${scope}_user
 POSTGRES_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
 POSTGRES_DB=${scope}_dev
 # Optional: Set DATABASE_URL to override the dynamic construction above
-# DATABASE_URL="postgresql://quark_user:CHANGE_ME_TO_STRONG_PASSWORD@localhost:5432/${scope}_dev?schema=public"
+# DATABASE_URL="postgresql://${scope}_user:CHANGE_ME_TO_STRONG_PASSWORD@localhost:5432/${scope}_dev?schema=public"
 
 # --- Redis Configuration ---
 REDIS_HOST=localhost
@@ -501,8 +501,6 @@ REDIS_PORT=6379
 MAIL_HOST=localhost
 MAIL_SMTP_PORT=1025
 MAIL_UI_PORT=8025
-# Optional: Set MAIL_SMTP_URL to override the dynamic construction above
-# MAIL_SMTP_URL="smtp://localhost:1025"
 
 # Production SMTP: Set these instead of MAIL_* when using a real SMTP relay
 # SMTP_HOST=smtp.example.com
@@ -525,6 +523,10 @@ MAIL_UI_PORT=8025
 # In production, set this to your real domain:
 # APP_URL=https://yourdomain.com
 
+# --- Application Identity ---
+# APP_NAME is used in metadata, emails, and page titles.
+APP_NAME=${projectName}
+
 # --- NextAuth Configuration ---
 # ⚠️  CRITICAL: Generate a secure secret with: openssl rand -base64 32
 # This secret is used to encrypt JWT tokens and session data
@@ -617,7 +619,7 @@ STORAGE_PROVIDER=local
 			const envContent = `# --- Database Configuration ---
 POSTGRES_HOST=localhost
 POSTGRES_PORT=${postgresPort}
-POSTGRES_USER=quark_user
+POSTGRES_USER=${scope}_user
 POSTGRES_PASSWORD=${dbPassword}
 POSTGRES_DB=${scope}_dev
 
@@ -630,6 +632,9 @@ MAIL_HOST=localhost
 MAIL_SMTP_PORT=${mailSmtpPort}
 MAIL_UI_PORT=${mailUiPort}
 
+# --- Application Identity ---
+APP_NAME=${projectName}
+
 # --- NextAuth Configuration ---
 NEXTAUTH_SECRET=${nextAuthSecret}
 

package/templates/base-project/apps/web/next.config.js

@@ -1,5 +1,9 @@
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+	// Required for Railway deployment — produces a self-contained build
+	// at .next/standalone that can run without node_modules.
+	output: "standalone",
+
 	// Support workspace package resolution (including @techstream/quark-db which uses
 	// the Prisma driver-adapter pattern — pure JS, no native engine binary)
 	transpilePackages: [

package/templates/base-project/apps/web/package.json

@@ -16,18 +16,18 @@
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
 		"@techstream/quark-ui": "workspace:*",
-		"@prisma/client": "^7.3.0",
+		"@prisma/client": "^7.4.0",
 		"next": "16.1.6",
 		"next-auth": "5.0.0-beta.30",
 		"pg": "^8.18.0",
-		"react": "19.2.0",
-		"react-dom": "19.2.0",
+		"react": "19.2.4",
+		"react-dom": "19.2.4",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@tailwindcss/postcss": "^4.1.18",
-		"@types/node": "^20.19.33",
-		"tailwindcss": "^4.1.18",
+		"@tailwindcss/postcss": "^4.2.0",
+		"@types/node": "^25.2.3",
+		"tailwindcss": "^4.2.0",
 		"@techstream/quark-config": "workspace:*"
 	}
 }

package/templates/base-project/apps/web/railway.json

@@ -0,0 +1,15 @@
+{
+	"$schema": "https://railway.com/railway.schema.json",
+	"build": {
+		"builder": "RAILPACK",
+		"buildCommand": "pnpm install --frozen-lockfile && pnpm db:generate && pnpm build",
+		"watchPatterns": ["apps/web/**", "packages/**"]
+	},
+	"deploy": {
+		"startCommand": "node apps/web/.next/standalone/server.js",
+		"healthcheckPath": "/api/health",
+		"healthcheckTimeout": 30,
+		"restartPolicyType": "ON_FAILURE",
+		"restartPolicyMaxRetries": 5
+	}
+}

package/templates/base-project/apps/worker/package.json

@@ -15,14 +15,14 @@
 	"license": "ISC",
 	"packageManager": "pnpm@10.12.1",
 	"dependencies": {
+		"@techstream/quark-config": "workspace:*",
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
-		"bullmq": "^5.67.3"
+		"bullmq": "^5.69.3"
 	},
 	"devDependencies": {
-		"@techstream/quark-config": "workspace:*",
-		"@types/node": "^24.10.12",
+		"@types/node": "^25.2.3",
 		"tsx": "^4.21.0"
 	}
 }

package/templates/base-project/apps/worker/railway.json

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://railway.com/railway.schema.json",
+	"build": {
+		"builder": "RAILPACK",
+		"buildCommand": "pnpm install --frozen-lockfile && pnpm db:generate",
+		"watchPatterns": ["apps/worker/**", "packages/**"]
+	},
+	"deploy": {
+		"startCommand": "node apps/worker/src/index.js",
+		"restartPolicyType": "ON_FAILURE",
+		"restartPolicyMaxRetries": 5
+	}
+}

package/templates/base-project/apps/worker/src/index.js

@@ -4,6 +4,7 @@
  * Handles job execution, retries, and error tracking
  */
 
+import { loadEnv } from "@techstream/quark-config";
 import {
 	createLogger,
 	createQueue,
@@ -13,6 +14,9 @@ import { prisma } from "@techstream/quark-db";
 import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 import { jobHandlers } from "./handlers/index.js";
 
+// Validate environment variables (worker-scoped — skips web-only checks)
+loadEnv("worker");
+
 const logger = createLogger("worker");
 
 // Store workers for graceful shutdown

package/templates/base-project/packages/db/package.json

@@ -21,7 +21,7 @@
 	"license": "ISC",
 	"packageManager": "pnpm@10.12.1",
 	"devDependencies": {
-		"@faker-js/faker": "^9.0.0",
+		"@faker-js/faker": "^10.3.0",
 		"@techstream/quark-config": "workspace:*",
 		"bcryptjs": "^3.0.3",
 		"prisma": "^7.4.0"

package/templates/base-project/packages/db/prisma.config.ts

@@ -1,19 +1,16 @@
 import { resolve } from "node:path";
 import { defineConfig } from "prisma/config";
+import { getConnectionString } from "./src/connection.js";
 
 // Load .env from monorepo root (needed for standalone commands like db:push, db:seed)
 try {
 	process.loadEnvFile(resolve(__dirname, "../../.env"));
 } catch {}
 
-// Construct DATABASE_URL from individual env vars - single source of truth
-const user = process.env.POSTGRES_USER || "quark_user";
-const password = process.env.POSTGRES_PASSWORD || "quark_password";
-const host = process.env.POSTGRES_HOST || "localhost";
-const port = process.env.POSTGRES_PORT || "5432";
-const db = process.env.POSTGRES_DB || "quark_dev";
-
-const databaseUrl = `postgresql://${user}:${password}@${host}:${port}/${db}?schema=public`;
+// Use shared connection builder — throwOnMissing=false so `prisma generate` works
+// even without database credentials (e.g. in CI). Commands that need a real
+// connection (migrate, push, studio) will fail at connect time.
+const databaseUrl = getConnectionString({ throwOnMissing: false });
 
 export default defineConfig({
 	schema: "prisma/schema.prisma",

package/templates/base-project/packages/db/src/client.js

@@ -1,24 +1,7 @@
 import { PrismaPg } from "@prisma/adapter-pg";
+import { getConnectionString } from "./connection.js";
 import { PrismaClient } from "./generated/prisma/client.ts";
 
-/**
- * Builds a Postgres connection string from individual env vars (mirrors prisma.config.ts).
- * Throws if any required variable is missing — but only when actually called,
- * so the module can be safely imported at build time (e.g. during `next build`).
- */
-function getConnectionString() {
-	const user = process.env.POSTGRES_USER;
-	if (!user) throw new Error("POSTGRES_USER environment variable is required");
-	const password = process.env.POSTGRES_PASSWORD;
-	if (!password)
-		throw new Error("POSTGRES_PASSWORD environment variable is required");
-	const host = process.env.POSTGRES_HOST || "localhost";
-	const port = process.env.POSTGRES_PORT || "5432";
-	const db = process.env.POSTGRES_DB;
-	if (!db) throw new Error("POSTGRES_DB environment variable is required");
-	return `postgresql://${user}:${password}@${host}:${port}/${db}?schema=public`;
-}
-
 /**
  * Returns the connection pool configuration for the `pg` driver.
  *

package/templates/base-project/packages/db/src/connection.js

@@ -0,0 +1,44 @@
+/**
+ * Shared connection string builder for PostgreSQL.
+ * Used by both the Prisma client (client.js) and Prisma CLI (prisma.config.ts).
+ *
+ * Priority: DATABASE_URL env var → assembled from POSTGRES_* env vars.
+ *
+ * @param {{ throwOnMissing?: boolean }} [options]
+ *   - throwOnMissing=true  (default) — runtime: throws if credentials are missing.
+ *   - throwOnMissing=false — CLI/CI: returns a placeholder URL so `prisma generate` works.
+ * @returns {string} PostgreSQL connection string
+ */
+export function getConnectionString({ throwOnMissing = true } = {}) {
+	// 1. Prefer an explicit DATABASE_URL if set
+	if (process.env.DATABASE_URL) {
+		return process.env.DATABASE_URL;
+	}
+
+	// 2. Assemble from individual POSTGRES_* vars
+	const user = process.env.POSTGRES_USER;
+	const password = process.env.POSTGRES_PASSWORD;
+	const host = process.env.POSTGRES_HOST || "localhost";
+	const port = process.env.POSTGRES_PORT || "5432";
+	const db = process.env.POSTGRES_DB;
+
+	const hasCredentials = user && password && db;
+
+	if (!hasCredentials) {
+		if (throwOnMissing) {
+			const missing = [];
+			if (!user) missing.push("POSTGRES_USER");
+			if (!password) missing.push("POSTGRES_PASSWORD");
+			if (!db) missing.push("POSTGRES_DB");
+			throw new Error(
+				`Missing required database environment variables: ${missing.join(", ")}. ` +
+					"Set DATABASE_URL or the individual POSTGRES_* variables.",
+			);
+		}
+
+		// Placeholder for prisma generate / CI — will fail at connect time, not at config time.
+		return "postgresql://placeholder:placeholder@localhost:5432/placeholder?schema=public";
+	}
+
+	return `postgresql://${user}:${password}@${host}:${port}/${db}?schema=public`;
+}

package/templates/base-project/packages/db/src/connection.test.js

@@ -0,0 +1,119 @@
+import assert from "node:assert";
+import { afterEach, beforeEach, describe, test } from "node:test";
+import { getConnectionString } from "./connection.js";
+
+describe("getConnectionString", () => {
+	const originalEnv = { ...process.env };
+
+	beforeEach(() => {
+		// Clear all DB-related env vars before each test
+		delete process.env.DATABASE_URL;
+		delete process.env.POSTGRES_USER;
+		delete process.env.POSTGRES_PASSWORD;
+		delete process.env.POSTGRES_HOST;
+		delete process.env.POSTGRES_PORT;
+		delete process.env.POSTGRES_DB;
+	});
+
+	afterEach(() => {
+		// Restore original env
+		process.env = { ...originalEnv };
+	});
+
+	test("returns DATABASE_URL when set", () => {
+		process.env.DATABASE_URL =
+			"postgresql://user:pass@remote:5433/mydb?schema=public";
+		const url = getConnectionString();
+		assert.strictEqual(url, process.env.DATABASE_URL);
+	});
+
+	test("DATABASE_URL takes priority over individual POSTGRES_* vars", () => {
+		process.env.DATABASE_URL =
+			"postgresql://url_user:url_pass@remote:5433/url_db?schema=public";
+		process.env.POSTGRES_USER = "individual_user";
+		process.env.POSTGRES_PASSWORD = "individual_pass";
+		process.env.POSTGRES_DB = "individual_db";
+
+		const url = getConnectionString();
+		assert.strictEqual(url, process.env.DATABASE_URL);
+	});
+
+	test("assembles from POSTGRES_* vars when DATABASE_URL is not set", () => {
+		process.env.POSTGRES_USER = "test_user";
+		process.env.POSTGRES_PASSWORD = "test_pass";
+		process.env.POSTGRES_DB = "test_db";
+
+		const url = getConnectionString();
+		assert.strictEqual(
+			url,
+			"postgresql://test_user:test_pass@localhost:5432/test_db?schema=public",
+		);
+	});
+
+	test("uses custom host and port when provided", () => {
+		process.env.POSTGRES_USER = "user";
+		process.env.POSTGRES_PASSWORD = "pass";
+		process.env.POSTGRES_HOST = "db.example.com";
+		process.env.POSTGRES_PORT = "5433";
+		process.env.POSTGRES_DB = "mydb";
+
+		const url = getConnectionString();
+		assert.strictEqual(
+			url,
+			"postgresql://user:pass@db.example.com:5433/mydb?schema=public",
+		);
+	});
+
+	test("throws when POSTGRES_USER is missing (throwOnMissing=true)", () => {
+		process.env.POSTGRES_PASSWORD = "pass";
+		process.env.POSTGRES_DB = "db";
+
+		assert.throws(() => getConnectionString(), {
+			message: /POSTGRES_USER/,
+		});
+	});
+
+	test("throws when POSTGRES_PASSWORD is missing (throwOnMissing=true)", () => {
+		process.env.POSTGRES_USER = "user";
+		process.env.POSTGRES_DB = "db";
+
+		assert.throws(() => getConnectionString(), {
+			message: /POSTGRES_PASSWORD/,
+		});
+	});
+
+	test("throws when POSTGRES_DB is missing (throwOnMissing=true)", () => {
+		process.env.POSTGRES_USER = "user";
+		process.env.POSTGRES_PASSWORD = "pass";
+
+		assert.throws(() => getConnectionString(), {
+			message: /POSTGRES_DB/,
+		});
+	});
+
+	test("lists all missing vars in error message", () => {
+		assert.throws(() => getConnectionString(), {
+			message: /POSTGRES_USER.*POSTGRES_PASSWORD.*POSTGRES_DB/,
+		});
+	});
+
+	test("returns placeholder when throwOnMissing=false and vars missing", () => {
+		const url = getConnectionString({ throwOnMissing: false });
+		assert.strictEqual(
+			url,
+			"postgresql://placeholder:placeholder@localhost:5432/placeholder?schema=public",
+		);
+	});
+
+	test("still assembles correctly with throwOnMissing=false when vars present", () => {
+		process.env.POSTGRES_USER = "user";
+		process.env.POSTGRES_PASSWORD = "pass";
+		process.env.POSTGRES_DB = "db";
+
+		const url = getConnectionString({ throwOnMissing: false });
+		assert.strictEqual(
+			url,
+			"postgresql://user:pass@localhost:5432/db?schema=public",
+		);
+	});
+});

package/templates/config/src/index.js

@@ -1,6 +1,8 @@
 export const config = {
-	appName: "Quark",
-	appDescription: "A modern monorepo with Next.js, React, and Prisma",
+	appName: process.env.APP_NAME || "Quark",
+	appDescription:
+		process.env.APP_DESCRIPTION ||
+		"A modern monorepo with Next.js, React, and Prisma",
 };
 
 export { getAllowedOrigins, getAppUrl, syncNextAuthUrl } from "./app-url.js";
@@ -11,3 +13,4 @@ export {
 	resolveEnvironment,
 } from "./environment.js";
 export { getConfig, loadConfig, resetConfig } from "./load-config.js";
+export { loadEnv, validateEnv } from "./validate-env.js";

package/templates/config/src/load-config.js

@@ -36,7 +36,7 @@ export function loadConfig(overrides = {}, options = {}) {
 	}
 
 	// Step 1: Validate environment variables
-	const validated = validateEnv();
+	const { validated } = validateEnv();
 
 	// Step 2: Resolve environment and get defaults
 	const envConfig = getEnvironmentConfig();

package/templates/config/src/validate-env.js

@@ -23,7 +23,6 @@ const envSchema = {
 	REDIS_PORT: { required: false, description: "Redis port" },
 
 	// Mail (local SMTP — Mailpit in dev)
-	MAIL_SMTP_URL: { required: false, description: "Mail SMTP URL" },
 	MAIL_HOST: { required: false, description: "Mail host" },
 	MAIL_SMTP_PORT: { required: false, description: "Mail SMTP port" },
 	MAIL_UI_PORT: { required: false, description: "Mail UI port" },
@@ -55,6 +54,10 @@ const envSchema = {
 	},
 
 	// Application
+	APP_NAME: {
+		required: false,
+		description: "Application name — used in metadata, emails, and page titles",
+	},
 	APP_URL: {
 		required: false,
 		description:
@@ -84,18 +87,30 @@ const envSchema = {
 };
 
 /**
- * Validates environment variables against schema
+ * Validates environment variables against schema.
+ *
+ * @param {"web" | "worker"} [service="web"] — The service being validated.
+ *   Worker skips web-only checks (e.g. NEXTAUTH_SECRET).
  * @throws {Error} If required environment variables are missing
- * @returns {Object} Validated environment object
+ * @returns {{ validated: Object, warnings: string[] }}
  */
-export function validateEnv() {
+export function validateEnv(service = "web") {
 	const errors = [];
+	const warnings = [];
 	const validated = {};
+	const isTest = process.env.NODE_ENV === "test";
+
+	// Web-only required fields that workers can skip
+	const webOnlyRequired = new Set(["NEXTAUTH_SECRET"]);
 
 	for (const [key, config] of Object.entries(envSchema)) {
 		const value = process.env[key];
 
-		if (config.required && !value) {
+		// Skip web-only required checks for worker service
+		const isRequired =
+			config.required && !(service === "worker" && webOnlyRequired.has(key));
+
+		if (isRequired && !value) {
 			errors.push(
 				`Missing required environment variable: ${key} (${config.description})`,
 			);
@@ -112,6 +127,30 @@ export function validateEnv() {
 		}
 	}
 
+	// --- Cross-field validation ---
+
+	// Database: either DATABASE_URL or POSTGRES_USER must be set (skip in test)
+	if (!isTest) {
+		const hasDbUrl = !!process.env.DATABASE_URL;
+		const hasPostgresUser = !!process.env.POSTGRES_USER;
+		if (!hasDbUrl && !hasPostgresUser) {
+			errors.push(
+				"Database not configured: set DATABASE_URL or POSTGRES_USER + POSTGRES_PASSWORD + POSTGRES_DB",
+			);
+		}
+	}
+
+	// Redis: warn if not configured (defaults to localhost in dev, will fail in prod)
+	if (
+		!process.env.REDIS_URL &&
+		!process.env.REDIS_HOST &&
+		process.env.NODE_ENV === "production"
+	) {
+		warnings.push(
+			"Redis not configured: set REDIS_URL or REDIS_HOST (defaults to localhost)",
+		);
+	}
+
 	// Conditional: S3 storage requires bucket + credentials
 	if (process.env.STORAGE_PROVIDER === "s3") {
 		for (const key of [
@@ -132,29 +171,39 @@ export function validateEnv() {
 		errors.push("Missing RESEND_API_KEY — required when EMAIL_PROVIDER=resend");
 	}
 
+	// Log warnings (non-fatal)
+	for (const warning of warnings) {
+		console.warn(`[env] ⚠️  ${warning}`);
+	}
+
 	if (errors.length > 0) {
 		const errorMessage = `Environment Validation Failed:\n${errors.join("\n")}`;
 		throw new Error(errorMessage);
 	}
 
 	// Ensure NEXTAUTH_URL is derived from APP_URL when not explicitly set
-	syncNextAuthUrl();
+	if (service === "web") {
+		syncNextAuthUrl();
 
-	// Include the (possibly derived) NEXTAUTH_URL in the validated object
-	if (process.env.NEXTAUTH_URL && !validated.NEXTAUTH_URL) {
-		validated.NEXTAUTH_URL = process.env.NEXTAUTH_URL;
+		// Include the (possibly derived) NEXTAUTH_URL in the validated object
+		if (process.env.NEXTAUTH_URL && !validated.NEXTAUTH_URL) {
+			validated.NEXTAUTH_URL = process.env.NEXTAUTH_URL;
+		}
 	}
 
-	return validated;
+	return { validated, warnings };
 }
 
 /**
- * Loads and validates environment variables
- * Call this function at application startup
+ * Loads and validates environment variables.
+ * Call this function at application startup.
+ *
+ * @param {"web" | "worker"} [service="web"]
  */
-export function loadEnv() {
+export function loadEnv(service = "web") {
 	try {
-		return validateEnv();
+		const { validated } = validateEnv(service);
+		return validated;
 	} catch (error) {
 		console.error(error.message);
 		process.exit(1);

package/templates/jobs/package.json

@@ -3,6 +3,6 @@
 	"version": "1.0.0",
 	"type": "module",
 	"dependencies": {
-		"bullmq": "^5.67.3"
+		"bullmq": "^5.69.3"
 	}
 }

package/templates/ui/package.json

@@ -3,9 +3,9 @@
 	"version": "1.0.0",
 	"type": "module",
 	"devDependencies": {
-		"@types/react": "^19.2.13",
+		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
-		"react": "19.2.0",
-		"react-dom": "19.2.0"
+		"react": "19.2.4",
+		"react-dom": "19.2.4"
 	}
 }