create-nexst-monorepo 0.1.0 → 0.2.0

package/dist/credentials.js

@@ -0,0 +1,58 @@
+// Safe to write unquoted into .env files (no spaces, quotes, `$` or `#`).
+const TOKEN = { hint: "Letters, digits, '.', '-' and '_' only", pattern: /^[\w.-]+$/ };
+/** In prompt order. */
+export const CREDENTIALS = [
+    {
+        flag: "db-password",
+        // Written single-quoted into .env, URL-encoded into DATABASE_URL.
+        hint: "No spaces or single quotes",
+        label: "Postgres password (local dev database)",
+        masked: true,
+        name: "dbPassword",
+        pattern: /^[^\s']+$/,
+    },
+    {
+        feature: "auth",
+        flag: "google-client-id",
+        hint: "Expected <id>.apps.googleusercontent.com",
+        label: "Google OAuth client ID",
+        name: "googleClientId",
+        pattern: /^[\w.-]+\.apps\.googleusercontent\.com$/,
+    },
+    {
+        feature: "auth",
+        flag: "google-client-secret",
+        label: "Google OAuth client secret",
+        masked: true,
+        name: "googleClientSecret",
+        ...TOKEN,
+    },
+    {
+        feature: "r2",
+        flag: "r2-account-id",
+        hint: "Expected the 32-character hex Cloudflare account ID",
+        label: "Cloudflare account ID",
+        name: "r2AccountId",
+        pattern: /^[\da-f]{32}$/i,
+    },
+    {
+        feature: "r2",
+        flag: "r2-access-key-id",
+        label: "R2 access key ID",
+        name: "r2AccessKeyId",
+        ...TOKEN,
+    },
+    {
+        feature: "r2",
+        flag: "r2-secret-access-key",
+        label: "R2 secret access key",
+        masked: true,
+        name: "r2SecretAccessKey",
+        ...TOKEN,
+    },
+];
+export function validateCredential(spec, value) {
+    if (!value)
+        return "Required";
+    return spec.pattern.test(value) ? undefined : spec.hint;
+}

package/dist/features.js

@@ -0,0 +1,145 @@
+/**
+ * What each optional feature owns in the template. Inline code is handled by
+ * `@if` markers (see markers.ts); this manifest covers what markers cannot:
+ * whole files/directories, package.json entries and JSON message keys.
+ *
+ * Keep it in sync when template code for a feature is added or moved —
+ * `pnpm run test:matrix` in cli/ generates every combination and typechecks it.
+ */
+export const FEATURE_NAMES = ["auth", "r2", "ui", "worker"];
+const WEB_MESSAGES = ["apps/web/messages/en.json", "apps/web/messages/de.json"];
+export const FEATURES = {
+    auth: {
+        description: "Better Auth (email + password, passkeys, Google, verification & reset mails) in API and web",
+        jsonKeys: Object.fromEntries(WEB_MESSAGES.map((file) => [
+            file,
+            [
+                "Auth",
+                "Dashboard",
+                "Header.dashboard",
+                "Header.signIn",
+                "Header.signOut",
+                "Home.cta",
+                "ApiErrors.EMAIL_NOT_VERIFIED",
+                "ApiErrors.INSUFFICIENT_ROLE",
+            ],
+        ])),
+        label: "Auth",
+        packages: {
+            "apps/api/package.json": {
+                dependencies: [
+                    "@better-auth/passkey",
+                    "@thallesp/nestjs-better-auth",
+                    "better-auth",
+                    "nodemailer",
+                    "resend",
+                ],
+                devDependencies: ["@types/nodemailer"],
+                scripts: ["auth:generate"],
+            },
+            "apps/web/package.json": {
+                dependencies: [
+                    "@better-auth/passkey",
+                    "better-auth",
+                    "@hookform/resolvers",
+                    "react-hook-form",
+                ],
+            },
+        },
+        paths: [
+            "apps/api/scripts/auth.cli.ts",
+            "apps/api/src/auth",
+            "apps/api/src/bootstrap/register-graphql-enums.ts",
+            "apps/api/src/mail",
+            "apps/api/src/user",
+            "apps/api/tests/auth.e2e-spec.ts",
+            "apps/web/src/app/[locale]/(auth)",
+            "apps/web/src/app/[locale]/dashboard",
+            "apps/web/src/components/icons.tsx",
+            "apps/web/src/config/routes.ts",
+            "apps/web/src/features/auth",
+            "apps/web/src/lib/auth-client.ts",
+            "apps/web/src/lib/auth-server.ts",
+            "apps/web/src/lib/auth.ts",
+            "apps/web/tests/auth.spec.ts",
+        ],
+    },
+    r2: {
+        description: "Cloudflare R2 object storage service (uploads, presigned URLs)",
+        label: "Cloudflare R2",
+        packages: {
+            "apps/api/package.json": {
+                dependencies: ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"],
+                devDependencies: ["aws-sdk-client-mock"],
+            },
+        },
+        paths: ["apps/api/src/r2"],
+    },
+    ui: {
+        description: "Extra UI components (dialog, drawer, select, switch, tabs, tooltip, …) with stories",
+        jsonKeys: Object.fromEntries(WEB_MESSAGES.map((file) => [
+            file,
+            [
+                "Common.cancel",
+                "Common.a11y.clearSearch",
+                "Common.a11y.close",
+                "Common.a11y.scrollDown",
+                "Common.a11y.scrollUp",
+            ],
+        ])),
+        label: "UI components",
+        packages: {
+            "apps/web/package.json": {
+                dependencies: [
+                    "@radix-ui/react-checkbox",
+                    "@radix-ui/react-dialog",
+                    "@radix-ui/react-dropdown-menu",
+                    "@radix-ui/react-popover",
+                    "@radix-ui/react-select",
+                    "@radix-ui/react-tabs",
+                    "@radix-ui/react-tooltip",
+                    "vaul",
+                ],
+            },
+        },
+        paths: [
+            ...[
+                "avatar",
+                "checkbox",
+                "dialog",
+                "dialog-buttons.stories.tsx",
+                "dialog-buttons.tsx",
+                "drawer",
+                "dropdown-menu",
+                "empty-state.stories.tsx",
+                "empty-state.tsx",
+                "field-group.stories.tsx",
+                "field-group.tsx",
+                "field-label.stories.tsx",
+                "field-label.tsx",
+                "input/input-otp.stories.tsx",
+                "input/input-otp.tsx",
+                "popover",
+                "responsive-dialog",
+                "searchbar",
+                "select",
+                "skeleton",
+                "switch",
+                "tabs",
+                "textarea",
+                "tooltip",
+            ].map((component) => `apps/web/src/components/${component}`),
+            "apps/web/src/lib/hooks",
+        ],
+    },
+    worker: {
+        description: "BullMQ worker app + Redis, with shared queue contracts",
+        label: "Worker",
+        packages: {
+            "apps/api/package.json": {
+                dependencies: ["@nexst/queues", "@nestjs/bullmq", "bullmq", "ioredis"],
+            },
+        },
+        paths: ["apps/worker", "packages/queues", "apps/api/src/queue"],
+    },
+};

package/dist/generate.js

@@ -0,0 +1,167 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { FEATURE_NAMES, FEATURES } from "./features.js";
+import { applyMarkers, hasMarkers } from "./markers.js";
+/** Paths never copied from the template (build output, caches, local state). */
+const SKIP = new Set([
+    ".env",
+    ".env.development",
+    ".next",
+    ".turbo",
+    "coverage",
+    "dist",
+    "node_modules",
+    "playwright-report",
+    "storybook-static",
+    "test-results",
+]);
+const BINARY = /\.(?:png|jpe?g|gif|webp|ico|woff2?|ttf|pdf|zip)$/i;
+export const NAME_PATTERN = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+export function toTitle(name) {
+    return name
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+/**
+ * Replaces the template's placeholder tokens: `nexst` (slug), `nexst_` (SQL-safe
+ * slug), `Nexst` (display name), `your-org`, `example.com`.
+ */
+export function replaceTokens(text, options) {
+    const snake = options.name.replaceAll("-", "_");
+    return text
+        .replaceAll("create-nexst-monorepo", "\u0000CLI\u0000")
+        .replaceAll("nexst_", `${snake}_`)
+        .replaceAll("Nexst", toTitle(options.name))
+        .replaceAll("nexst", options.name)
+        .replaceAll("your-org", options.owner)
+        .replaceAll("example.com", options.domain)
+        .replaceAll("\u0000CLI\u0000", "create-nexst-monorepo");
+}
+export async function generate(options) {
+    if (!NAME_PATTERN.test(options.name)) {
+        throw new Error(`Invalid project name "${options.name}" (lowercase letters, digits, dashes)`);
+    }
+    if (existsSync(options.targetDir) && (await readdir(options.targetDir)).length > 0) {
+        throw new Error(`${options.targetDir} already exists and is not empty`);
+    }
+    await mkdir(options.targetDir, { recursive: true });
+    await cp(options.templateDir, options.targetDir, {
+        filter: (source) => !SKIP.has(path.basename(source)) && !source.endsWith(".tsbuildinfo"),
+        recursive: true,
+    });
+    // npm strips .gitignore from published packages, so the packed template ships _gitignore.
+    for (const file of await walk(options.targetDir)) {
+        if (path.basename(file) === "_gitignore") {
+            await rename(file, path.join(path.dirname(file), ".gitignore"));
+        }
+    }
+    const disabled = FEATURE_NAMES.filter((feature) => !options.features[feature]);
+    for (const feature of disabled) {
+        await removeFeature(options.targetDir, feature);
+    }
+    const r2AccountId = options.credentials?.r2AccountId;
+    const allOn = Object.fromEntries(FEATURE_NAMES.map((feature) => [feature, true]));
+    for (const file of await walk(options.targetDir)) {
+        if (BINARY.test(file) || path.basename(file) === "pnpm-lock.yaml") {
+            if (path.basename(file) === "pnpm-lock.yaml") {
+                await writeFile(file, replaceTokens(await readFile(file, "utf8"), options));
+            }
+            continue;
+        }
+        const original = await readFile(file, "utf8");
+        const resolved = hasMarkers(original)
+            ? applyMarkers(original, options.features, allOn, path.relative(options.targetDir, file))
+            : original;
+        let replaced = replaceTokens(resolved, options);
+        if (r2AccountId)
+            replaced = replaced.replaceAll("<account-id>", r2AccountId);
+        if (replaced !== original)
+            await writeFile(file, replaced);
+    }
+    await writeEnvFiles(options);
+}
+async function removeFeature(root, feature) {
+    const manifest = FEATURES[feature];
+    for (const target of manifest.paths) {
+        await rm(path.join(root, target), { force: true, recursive: true });
+    }
+    for (const [file, edits] of Object.entries(manifest.packages ?? {})) {
+        const full = path.join(root, file);
+        if (!existsSync(full))
+            continue;
+        const pkg = JSON.parse(await readFile(full, "utf8"));
+        for (const [section, names] of Object.entries(edits)) {
+            for (const name of names)
+                delete pkg[section]?.[name];
+        }
+        await writeFile(full, `${JSON.stringify(pkg, null, 2)}\n`);
+    }
+    for (const [file, keys] of Object.entries(manifest.jsonKeys ?? {})) {
+        const full = path.join(root, file);
+        if (!existsSync(full))
+            continue;
+        const json = JSON.parse(await readFile(full, "utf8"));
+        for (const key of keys)
+            deleteKey(json, key.split("."));
+        await writeFile(full, `${JSON.stringify(json, null, 2)}\n`);
+    }
+}
+function deleteKey(object, [head, ...rest]) {
+    if (rest.length === 0) {
+        delete object[head];
+        return;
+    }
+    const child = object[head];
+    if (child && typeof child === "object")
+        deleteKey(child, rest);
+}
+/**
+ * Turns every `.env.example` into the git-ignored file the dev scripts (root: docker
+ * compose) load, with a fresh auth secret and the credentials entered at init.
+ */
+async function writeEnvFiles(options) {
+    const targets = {
+        ".": ".env",
+        "apps/api": ".env.development",
+        "apps/web": ".env",
+        "apps/worker": ".env",
+    };
+    const credentials = options.credentials ?? {};
+    const values = {
+        BETTER_AUTH_SECRET: randomBytes(32).toString("base64"),
+        GOOGLE_CLIENT_ID: credentials.googleClientId,
+        GOOGLE_CLIENT_SECRET: credentials.googleClientSecret,
+        NEXT_PUBLIC_GOOGLE_CLIENT_ID: credentials.googleClientId,
+        // Single-quoted so docker compose takes it literally (no `$` interpolation).
+        POSTGRES_PASSWORD: credentials.dbPassword && `'${credentials.dbPassword}'`,
+        R2_ACCESS_KEY_ID: credentials.r2AccessKeyId,
+        R2_SECRET_ACCESS_KEY: credentials.r2SecretAccessKey,
+    };
+    for (const [dir, envFile] of Object.entries(targets)) {
+        const example = path.join(options.targetDir, dir, ".env.example");
+        if (!existsSync(example))
+            continue;
+        let content = await readFile(example, "utf8");
+        for (const [key, value] of Object.entries(values)) {
+            // Also uncomments optional `# KEY=` placeholders.
+            if (value)
+                content = content.replace(new RegExp(`^(?:# )?${key}=.*$`, "m"), () => `${key}=${value}`);
+        }
+        if (credentials.dbPassword) {
+            const password = encodeURIComponent(credentials.dbPassword);
+            content = content.replace(/^(DATABASE_URL=\w+:\/\/[^:/@]+:)[^@]*@/m, (_, prefix) => `${prefix}${password}@`);
+        }
+        await writeFile(path.join(options.targetDir, dir, envFile), content);
+    }
+}
+async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = await Promise.all(entries.map((entry) => {
+        const full = path.join(dir, entry.name);
+        return entry.isDirectory() ? walk(full) : Promise.resolve([full]);
+    }));
+    return files.flat();
+}