@techstream/quark-create-app 1.6.0 → 1.8.0

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 } 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"
 	}
 }