@dahoolabs/create 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @dahoolabs/create
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffold a new Dahoo Labs project.
+
+```sh
+bunx @dahoolabs/create my-app
+# or
+bun create @dahoolabs my-app
+```
+
+## Options
+| Flag | Description |
+|---|---|
+| `-t, --template <id>` | Template to use (default `bun-nest-next`) |
+| `--no-install` | Skip `bun install` |
+| `--no-git` | Skip `git init` and the initial commit |
+| `-f, --force` | Allow a non-empty target directory |
+| `-y, --yes` | Use defaults, no prompts |
+
+## Templates
+### `bun-nest-next`
+A Bun workspace + Turborepo monorepo:
+- `apps/api`: NestJS on Bun, with Swagger at `/docs` and a `GET /health` endpoint
+- `apps/web`: Next.js (App Router) + Tailwind CSS v4
+- `packages/shared`: types shared by both apps
+
+Every project gets these defaults, and they can't be turned off:
+- Turbo
+- Husky: pre-commit runs check and test; commit-msg runs commitlint
+- commitlint + Commitizen (`bun run commit`)
+- Playwright e2e
+- release-please
+- GitHub Actions CI
+- `AGENT.md`
+
+## Developing
+```sh
+bun install
+bun run test                                  # unit tests for the CLI
+bun src/index.ts ../../../scratch/demo --yes  # try it locally
+```
+
+Template files are copied as-is. `{{projectName}}` and `{{scope}}` are replaced, and `_gitignore` is renamed to `.gitignore`, because npm drops `.gitignore` from published packages.
+
+## Releasing
+Releases are automated with release-please. Merge conventional commits that touch `packages/create` into `main`, then merge the release PR. The workflow publishes to npm using the `NPM_TOKEN` secret.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@dahoolabs/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Scaffold a new Dahoo Labs project",
+  "type": "module",
+  "bin": {
+    "create": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "templates"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahoolabs/base.git",
+    "directory": "packages/create"
+  },
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "bun check",
+    "test": "bun test ./src"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+import * as p from "@clack/prompts";
+import { existsSync, readdirSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { parseOptions, USAGE } from "./options";
+import { promptOptions } from "./prompts";
+import { getTemplate } from "./registry";
+import { scaffold, toPackageName } from "./scaffold";
+
+async function run(cmd: string[], cwd: string): Promise<void> {
+  const proc = Bun.spawn(cmd, { cwd, stdout: "inherit", stderr: "inherit" });
+  const code = await proc.exited;
+  if (code !== 0) throw new Error(`\`${cmd.join(" ")}\` exited with code ${code}`);
+}
+
+async function main(): Promise<void> {
+  const parsed = parseOptions(process.argv.slice(2));
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  p.intro("Dahoo Labs · create");
+  const options = await promptOptions(parsed);
+  const template = getTemplate(options.template);
+  const targetDir = resolve(options.dir);
+  const projectName = toPackageName(targetDir);
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !options.force) {
+    p.cancel(`${targetDir} is not empty. Use --force to scaffold into it anyway.`);
+    process.exit(1);
+  }
+
+  const spinner = p.spinner();
+  spinner.start(`Scaffolding ${template.label}`);
+  await scaffold(template.dir, targetDir, { projectName, scope: projectName });
+  spinner.stop(`Scaffolded ${template.label} into ${targetDir}`);
+
+  // git must exist before install so husky's `prepare` script can register the hooks.
+  if (options.git) await run(["git", "init", "-q", "-b", "main"], targetDir);
+
+  if (options.install) {
+    p.log.step("Installing dependencies");
+    await run(["bun", "install"], targetDir);
+  }
+
+  if (options.git) {
+    await run(["git", "add", "-A"], targetDir);
+    // Hooks need installed deps; skip them when the user opted out of installing.
+    const commit = ["git", "commit", "-q", "-m", "chore: initial scaffold"];
+    if (!options.install) commit.push("--no-verify");
+    p.log.step("Creating initial commit");
+    await run(commit, targetDir);
+  }
+
+  const cd = relative(process.cwd(), targetDir) || ".";
+  const steps = [
+    cd !== "." && `cd ${cd}`,
+    !options.install && "bun install",
+    "bun run e2e:install   # once, downloads Playwright browsers",
+    "bun run dev",
+  ].filter(Boolean);
+  p.note(steps.join("\n"), "Next steps");
+  p.outro("Happy building.");
+}
+
+main().catch((error: unknown) => {
+  p.cancel(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/options.ts

@@ -0,0 +1,49 @@
+import { parseArgs } from "node:util";
+import { DEFAULT_TEMPLATE } from "./registry";
+
+export interface Options {
+  dir?: string;
+  template: string;
+  install: boolean;
+  git: boolean;
+  force: boolean;
+  yes: boolean;
+  help: boolean;
+}
+
+export const USAGE = `Usage: bunx @dahoolabs/create [dir] [options]
+
+Options:
+  -t, --template <id>   Template to use (default: ${DEFAULT_TEMPLATE})
+      --no-install      Skip \`bun install\`
+      --no-git          Skip \`git init\` and the initial commit
+  -f, --force           Allow scaffolding into a non-empty directory
+  -y, --yes             Accept defaults, no prompts
+  -h, --help            Show this help
+`;
+
+export function parseOptions(argv: string[]): Options {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    allowNegative: true,
+    options: {
+      template: { type: "string", short: "t", default: DEFAULT_TEMPLATE },
+      install: { type: "boolean", default: true },
+      git: { type: "boolean", default: true },
+      force: { type: "boolean", short: "f", default: false },
+      yes: { type: "boolean", short: "y", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  return {
+    dir: positionals[0],
+    template: values.template,
+    install: values.install,
+    git: values.git,
+    force: values.force,
+    yes: values.yes,
+    help: values.help,
+  };
+}

package/src/prompts.ts

@@ -0,0 +1,48 @@
+import * as p from "@clack/prompts";
+import type { Options } from "./options";
+import { TEMPLATES } from "./registry";
+
+function bail(value: unknown): void {
+  if (p.isCancel(value)) {
+    p.cancel("Cancelled.");
+    process.exit(1);
+  }
+}
+
+/** Fills in anything not given on the command line. Returns options unchanged with --yes. */
+export async function promptOptions(options: Options): Promise<Options & { dir: string }> {
+  if (options.yes) return { ...options, dir: options.dir ?? "my-app" };
+
+  const dir =
+    options.dir ??
+    (await p.text({
+      message: "Where should the project be created?",
+      placeholder: "my-app",
+      defaultValue: "my-app",
+    }));
+  bail(dir);
+
+  const template =
+    TEMPLATES.length === 1
+      ? options.template
+      : await p.select({
+          message: "Which template?",
+          initialValue: options.template,
+          options: TEMPLATES.map((t) => ({ value: t.id, label: t.label, hint: t.hint })),
+        });
+  bail(template);
+
+  const install = options.install ? await p.confirm({ message: "Install dependencies?", initialValue: true }) : false;
+  bail(install);
+
+  const git = options.git ? await p.confirm({ message: "Initialize a git repository?", initialValue: true }) : false;
+  bail(git);
+
+  return {
+    ...options,
+    dir: dir as string,
+    template: template as string,
+    install: install as boolean,
+    git: git as boolean,
+  };
+}

package/src/registry.ts

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+
+export interface Template {
+  id: string;
+  label: string;
+  hint: string;
+  dir: string;
+}
+
+const TEMPLATES_DIR = join(import.meta.dir, "..", "templates");
+
+export const TEMPLATES: Template[] = [
+  {
+    id: "bun-nest-next",
+    label: "Bun + NestJS + Next.js",
+    hint: "Turbo monorepo: apps/api (NestJS), apps/web (Next.js), packages/shared",
+    dir: join(TEMPLATES_DIR, "bun-nest-next"),
+  },
+];
+
+export const DEFAULT_TEMPLATE = "bun-nest-next";
+
+export function getTemplate(id: string): Template {
+  const template = TEMPLATES.find((t) => t.id === id);
+  if (!template) {
+    const ids = TEMPLATES.map((t) => t.id).join(", ");
+    throw new Error(`Unknown template "${id}". Available: ${ids}`);
+  }
+  return template;
+}

package/src/scaffold.ts

@@ -0,0 +1,57 @@
+import { cp, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+
+export interface TemplateVars {
+  projectName: string;
+  scope: string;
+}
+
+// npm strips these from published tarballs, so templates store them with a leading underscore.
+const RENAMES: Record<string, string> = {
+  _gitignore: ".gitignore",
+  _npmrc: ".npmrc",
+};
+
+const BINARY_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".ico", ".webp", ".woff", ".woff2"]);
+
+/** Turns an arbitrary directory name into a valid npm package name. */
+export function toPackageName(name: string): string {
+  return (
+    basename(name)
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9-~]+/g, "-")
+      .replace(/^[-.~]+|-+$/g, "") || "app"
+  );
+}
+
+export function render(content: string, vars: TemplateVars): string {
+  return content.replace(/\{\{(\w+)\}\}/g, (match, key: string) =>
+    key in vars ? vars[key as keyof TemplateVars] : match,
+  );
+}
+
+export async function scaffold(templateDir: string, targetDir: string, vars: TemplateVars): Promise<void> {
+  await cp(templateDir, targetDir, { recursive: true, force: true });
+  await processDir(targetDir, vars);
+}
+
+async function processDir(dir: string, vars: TemplateVars): Promise<void> {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    let path = join(dir, entry.name);
+    const renamed = RENAMES[entry.name];
+    if (renamed) {
+      const next = join(dir, renamed);
+      await rename(path, next);
+      path = next;
+    }
+
+    if (entry.isDirectory()) {
+      await processDir(path, vars);
+    } else if (!BINARY_EXTENSIONS.has(extname(path))) {
+      const content = await readFile(path, "utf8");
+      const output = render(content, vars);
+      if (output !== content) await writeFile(path, output);
+    }
+  }
+}

package/templates/bun-nest-next/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/bun-nest-next/.env.example

@@ -0,0 +1,6 @@
+# apps/api
+PORT=3001
+WEB_ORIGIN=http://localhost:3000
+
+# apps/web
+NEXT_PUBLIC_API_URL=http://localhost:3001

package/templates/bun-nest-next/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  commitlint:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx --bun commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
+
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run check
+      - run: bun run test
+      - run: bun run build
+
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx playwright install --with-deps chromium
+      - run: bun run e2e
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report
+          retention-days: 7

package/templates/bun-nest-next/.github/workflows/release-please.yml

@@ -0,0 +1,18 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

package/templates/bun-nest-next/.husky/commit-msg

@@ -0,0 +1 @@
+bunx --bun commitlint --edit "$1"

package/templates/bun-nest-next/.husky/pre-commit

@@ -0,0 +1,2 @@
+bun run check
+bun run test

package/templates/bun-nest-next/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.0.0"
+}

package/templates/bun-nest-next/AGENT.md

@@ -0,0 +1,49 @@
+# AGENT.md
+
+Guidance for AI coding agents (and humans) working in **{{projectName}}**.
+
+## Stack
+- **Runtime / package manager:** Bun (workspaces). Always use `bun` / `bunx`, never npm, yarn, or pnpm.
+- **Monorepo:** Turborepo. Run tasks from the root; Turbo fans them out and caches results.
+- **API:** NestJS on Bun, in `apps/api`. Swagger UI at `/docs`.
+- **Web:** Next.js (App Router) + Tailwind CSS v4, in `apps/web`.
+- **Shared:** `packages/shared` (`@{{scope}}/shared`), for types and contracts used by both apps.
+- **Tests:** `bun test` for unit and integration tests, Playwright for e2e (`e2e/`).
+- **Git:** Husky hooks, commitlint (Conventional Commits), Commitizen, release-please.
+
+## Layout
+```
+apps/api/src/<feature>/   # one Nest module per feature: module, controller, service, dto, *.test.ts
+apps/web/app/             # Next.js App Router routes
+packages/shared/src/      # shared types; no runtime deps on either app
+e2e/                      # Playwright specs that run against the real api and web
+```
+
+## Commands
+| Task | Command |
+|---|---|
+| Dev servers (api :3001, web :3000) | `bun run dev` |
+| Type check (the static gate; no separate linter) | `bun run check` |
+| Unit tests | `bun run test` |
+| E2E tests (first run `bun run e2e:install`) | `bun run e2e` |
+| Production build | `bun run build` |
+| Commit with a guided prompt | `bun run commit` |
+| Add a dependency to one workspace | `bun add <pkg> --cwd apps/api` |
+
+## Rules
+1. **Conventional Commits are enforced.** Use `type(scope): subject`. Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, `style`, `revert`. Scopes: `api`, `web`, `shared`, `e2e`, `deps`, `ci`, `release`. The commit-msg hook rejects anything else. Never bypass hooks with `--no-verify`.
+2. **`bun run check` and `bun run test` must pass before committing.** The pre-commit hook runs both.
+3. **Do not edit `CHANGELOG.md` or bump versions by hand.** release-please does this from commit history. `feat` → minor, `fix` → patch, `feat!` / `BREAKING CHANGE:` → major.
+4. **Keep the API RESTful and documented.** Every endpoint gets Swagger decorators (`@ApiTags`, `@ApiOkResponse`, …) and DTOs validated with `class-validator`.
+5. **Layered clean architecture in the API.** Controllers handle HTTP only, services hold business logic, and data access stays behind a repository/provider. Don't put logic in controllers.
+6. **Shared contracts live in `packages/shared`.** If both apps need a type, define it there instead of duplicating it.
+7. **Test at the right level.** Unit-test services, integration-test modules with `@nestjs/testing`, and add a Playwright spec for every user-facing flow.
+8. **Small, focused changes.** One concern per PR/commit. Don't refactor unrelated code in passing.
+9. **No secrets in git.** Put new env vars in `.env.example` with a safe default.
+
+## Principles & references
+These are the Dahoo Labs engineering principles. Read them before making architectural decisions:
+- [ENGINEERING.md](https://github.com/dahoolabs/base/blob/main/ENGINEERING.md): API design, observability, resilience, scaling, architecture, testing
+- [BACKEND.md](https://github.com/dahoolabs/base/blob/main/BACKEND.md)
+- [FRONTEND.md](https://github.com/dahoolabs/base/blob/main/FRONTEND.md)
+- [AGENTIC_SWE.md](https://github.com/dahoolabs/base/blob/main/AGENTIC_SWE.md)

package/templates/bun-nest-next/README.md

@@ -0,0 +1,21 @@
+# {{projectName}}
+
+Scaffolded with [`@dahoolabs/create`](https://github.com/dahoolabs/base/tree/main/packages/create).
+
+## Getting started
+```sh
+bun install
+cp .env.example .env
+bun run e2e:install   # once, downloads Playwright browsers
+bun run dev           # api on :3001 (docs at /docs), web on :3000
+```
+
+## Scripts
+- `bun run dev`: start api and web in watch mode
+- `bun run check`: type check every workspace
+- `bun run test`: unit tests
+- `bun run e2e`: Playwright end-to-end tests
+- `bun run build`: production build
+- `bun run commit`: guided Conventional Commit
+
+See [AGENT.md](./AGENT.md) for conventions.

package/templates/bun-nest-next/_gitignore

@@ -0,0 +1,15 @@
+node_modules
+dist
+.next
+.turbo
+out
+coverage
+playwright-report
+test-results
+blob-report
+*.tsbuildinfo
+next-env.d.ts
+.env
+.env.*
+!.env.example
+.DS_Store

package/templates/bun-nest-next/apps/api/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@{{scope}}/api",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/main.ts",
+    "build": "bun build src/main.ts --target bun --packages external --outdir dist --sourcemap=linked",
+    "start": "bun dist/main.js",
+    "check": "bun check",
+    "test": "bun test ./src"
+  },
+  "dependencies": {
+    "@{{scope}}/shared": "workspace:*",
+    "@nestjs/common": "^12.2.0",
+    "@nestjs/core": "^12.2.0",
+    "@nestjs/platform-express": "^12.2.0",
+    "@nestjs/swagger": "^12.0.2",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@nestjs/testing": "^12.2.0",
+    "@types/bun": "^1.4.3",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/bun-nest-next/apps/api/src/app.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common";
+import { HealthModule } from "./health/health.module";
+
+@Module({
+  imports: [HealthModule],
+})
+export class AppModule {}

package/templates/bun-nest-next/apps/api/src/health/health.controller.test.ts

@@ -0,0 +1,19 @@
+import "reflect-metadata";
+import { beforeEach, describe, expect, test } from "bun:test";
+import { Test } from "@nestjs/testing";
+import { HealthController } from "./health.controller";
+
+describe("HealthController", () => {
+  let controller: HealthController;
+
+  beforeEach(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [HealthController],
+    }).compile();
+    controller = moduleRef.get(HealthController);
+  });
+
+  test("reports ok", () => {
+    expect(controller.check().status).toBe("ok");
+  });
+});

package/templates/bun-nest-next/apps/api/src/health/health.controller.ts

@@ -0,0 +1,17 @@
+import type { HealthResponse } from "@{{scope}}/shared";
+import { Controller, Get } from "@nestjs/common";
+import { ApiOkResponse, ApiTags } from "@nestjs/swagger";
+
+@ApiTags("health")
+@Controller("health")
+export class HealthController {
+  @Get()
+  @ApiOkResponse({ description: "Service is up" })
+  check(): HealthResponse {
+    return {
+      status: "ok",
+      uptime: process.uptime(),
+      timestamp: new Date().toISOString(),
+    };
+  }
+}

package/templates/bun-nest-next/apps/api/src/health/health.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common";
+import { HealthController } from "./health.controller";
+
+@Module({
+  controllers: [HealthController],
+})
+export class HealthModule {}

package/templates/bun-nest-next/apps/api/src/main.ts

@@ -0,0 +1,21 @@
+import "reflect-metadata";
+import { ValidationPipe } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import { AppModule } from "./app.module";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.enableCors({ origin: process.env.WEB_ORIGIN ?? "http://localhost:3000" });
+  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
+
+  const config = new DocumentBuilder().setTitle("{{projectName}} API").setVersion("0.0.0").build();
+  SwaggerModule.setup("docs", app, () => SwaggerModule.createDocument(app, config));
+
+  const port = Number(process.env.PORT ?? 3001);
+  await app.listen(port);
+  console.log(`API listening on http://localhost:${port} (docs at /docs)`);
+}
+
+bootstrap();

package/templates/bun-nest-next/apps/api/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strictPropertyInitialization": false,
+    "types": ["bun"]
+  },
+  "include": ["src"]
+}

package/templates/bun-nest-next/apps/web/app/globals.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/bun-nest-next/apps/web/app/layout.tsx

@@ -0,0 +1,17 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "{{projectName}}",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body className="min-h-screen bg-white text-neutral-900 antialiased dark:bg-neutral-950 dark:text-neutral-100">
+        {children}
+      </body>
+    </html>
+  );
+}

package/templates/bun-nest-next/apps/web/app/page.tsx

@@ -0,0 +1,25 @@
+import type { HealthResponse } from "@{{scope}}/shared";
+
+export const dynamic = "force-dynamic";
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+
+async function getHealth(): Promise<HealthResponse | null> {
+  try {
+    const res = await fetch(`${API_URL}/health`, { cache: "no-store" });
+    return res.ok ? ((await res.json()) as HealthResponse) : null;
+  } catch {
+    return null;
+  }
+}
+
+export default async function Home() {
+  const health = await getHealth();
+
+  return (
+    <main className="mx-auto flex max-w-xl flex-col gap-4 px-4 py-24">
+      <h1 className="text-3xl font-semibold">{{projectName}}</h1>
+      <p data-testid="api-status">API: {health ? health.status : "unreachable"}</p>
+    </main>
+  );
+}

package/templates/bun-nest-next/apps/web/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: ["@{{scope}}/shared"],
+};
+
+export default nextConfig;

package/templates/bun-nest-next/apps/web/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@{{scope}}/web",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --bun next dev --port 3000",
+    "build": "bun --bun next build",
+    "start": "bun --bun next start --port 3000",
+    "check": "bun check",
+    "test": "bun test ./app --pass-with-no-tests"
+  },
+  "dependencies": {
+    "@{{scope}}/shared": "workspace:*",
+    "next": "^16.4.2",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.3",
+    "@types/bun": "^1.4.3",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/bun-nest-next/apps/web/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};

package/templates/bun-nest-next/apps/web/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "jsx": "preserve",
+    "allowJs": true,
+    "incremental": true,
+    "types": ["bun"],
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules", ".next"]
+}

package/templates/bun-nest-next/commitlint.config.ts

@@ -0,0 +1,6 @@
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "scope-enum": [2, "always", ["api", "web", "shared", "e2e", "deps", "ci", "release"]],
+  },
+};

package/templates/bun-nest-next/e2e/api.spec.ts

@@ -0,0 +1,7 @@
+import { expect, test } from "@playwright/test";
+
+test("GET /health returns ok", async ({ request }) => {
+  const res = await request.get("http://localhost:3001/health");
+  expect(res.ok()).toBe(true);
+  expect(await res.json()).toMatchObject({ status: "ok" });
+});

package/templates/bun-nest-next/e2e/home.spec.ts

@@ -0,0 +1,6 @@
+import { expect, test } from "@playwright/test";
+
+test("home page shows the API is up", async ({ page }) => {
+  await page.goto("/");
+  await expect(page.getByTestId("api-status")).toHaveText("API: ok");
+});

package/templates/bun-nest-next/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "private": true,
+  "packageManager": "bun@1.4.3",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "dev": "turbo dev",
+    "build": "turbo build",
+    "start": "turbo start",
+    "check": "turbo check",
+    "test": "turbo test",
+    "e2e": "playwright test",
+    "e2e:install": "playwright install chromium",
+    "commit": "cz",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
+    "@commitlint/cz-commitlint": "^21.2.4",
+    "@playwright/test": "^1.64.1",
+    "@types/bun": "^1.4.3",
+    "commitizen": "^4.3.2",
+    "husky": "^9.1.7",
+    "inquirer": "^12.11.1",
+    "turbo": "^2.11.10",
+    "typescript": "^6.0.3"
+  },
+  "config": {
+    "commitizen": {
+      "path": "@commitlint/cz-commitlint"
+    }
+  }
+}

package/templates/bun-nest-next/packages/shared/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@{{scope}}/shared",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "check": "bun check",
+    "test": "bun test ./src --pass-with-no-tests"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.3",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/bun-nest-next/packages/shared/src/index.ts

@@ -0,0 +1,5 @@
+export interface HealthResponse {
+  status: "ok";
+  uptime: number;
+  timestamp: string;
+}

package/templates/bun-nest-next/packages/shared/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun"]
+  },
+  "include": ["src"]
+}

package/templates/bun-nest-next/playwright.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const CI = !!process.env.CI;
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  forbidOnly: CI,
+  retries: CI ? 2 : 0,
+  reporter: CI ? [["github"], ["html", { open: "never" }]] : "list",
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+  },
+  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
+  webServer: [
+    {
+      command: "bun run --filter=@{{scope}}/api dev",
+      url: "http://localhost:3001/health",
+      reuseExistingServer: !CI,
+    },
+    {
+      command: "bun run --filter=@{{scope}}/web dev",
+      url: "http://localhost:3000",
+      reuseExistingServer: !CI,
+    },
+  ],
+});

package/templates/bun-nest-next/release-please-config.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "node",
+  "include-component-in-tag": false,
+  "packages": {
+    ".": {
+      "changelog-path": "CHANGELOG.md"
+    }
+  }
+}

package/templates/bun-nest-next/tsconfig.base.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}

package/templates/bun-nest-next/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun"]
+  },
+  "include": ["playwright.config.ts", "commitlint.config.ts", "e2e"]
+}

package/templates/bun-nest-next/turbo.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "ui": "stream",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
+    },
+    "check": {
+      "dependsOn": ["^check"]
+    },
+    "test": {
+      "dependsOn": ["^build"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "start": {
+      "dependsOn": ["build"],
+      "cache": false,
+      "persistent": true
+    }
+  }
+}