create-nexst-monorepo 0.1.0

package/template/apps/web/src/i18n/navigation.ts

@@ -0,0 +1,5 @@
+import { createNavigation } from "next-intl/navigation";
+import { routing } from "./routing";
+
+export const { Link, useRouter } = createNavigation(routing); // @if auth
+// export const { Link } = createNavigation(routing); // @if !auth

package/template/apps/web/src/i18n/request.ts

@@ -0,0 +1,21 @@
+import { hasLocale } from "next-intl";
+import { getRequestConfig } from "next-intl/server";
+import { notFound } from "next/navigation";
+import { locale as rootLocale } from "next/root-params";
+import { routing } from "./routing";
+
+export default getRequestConfig(async ({ locale }) => {
+  if (!locale) {
+    const paramValue = await rootLocale();
+    if (hasLocale(routing.locales, paramValue)) {
+      locale = paramValue;
+    } else {
+      notFound();
+    }
+  }
+
+  return {
+    locale,
+    messages: (await import(`../../messages/${locale}.json`)).default,
+  };
+});

package/template/apps/web/src/i18n/routing.ts

@@ -0,0 +1,6 @@
+import { defineRouting } from "next-intl/routing";
+
+export const routing = defineRouting({
+  defaultLocale: "en",
+  locales: ["en", "de"],
+});

package/template/apps/web/src/lib/auth-client.ts

@@ -0,0 +1,19 @@
+import { passkeyClient } from "@better-auth/passkey/client";
+import { createAuthClient } from "better-auth/client";
+import { oneTapClient } from "better-auth/client/plugins";
+import { env } from "@/env";
+
+/** Google sign-in is optional: without a client ID the button and One Tap stay hidden. */
+export const isGoogleEnabled = Boolean(env.NEXT_PUBLIC_GOOGLE_CLIENT_ID);
+
+export const authClient = createAuthClient({
+  baseURL: env.NEXT_PUBLIC_API_URL,
+  plugins: [oneTapClient({ clientId: env.NEXT_PUBLIC_GOOGLE_CLIENT_ID ?? "" }), passkeyClient()],
+});
+
+export type AuthError = {
+  code?: string;
+  message?: string;
+  status: number;
+  statusText: string;
+};

package/template/apps/web/src/lib/auth-server.ts

@@ -0,0 +1,46 @@
+import type { User as BetterAuthUser, Session } from "better-auth";
+import { env } from "@/env";
+
+export type SessionResponse = null | {
+  session: SerializedSession;
+  user: SessionUser;
+};
+
+/** The Better Auth user plus the fields the API's `customSession` plugin adds. */
+type SessionUser = BetterAuthUser & {
+  role?: null | string[];
+};
+
+type SerializedSession = Omit<Session, "createdAt" | "expiresAt" | "updatedAt"> & {
+  createdAt?: string;
+  expiresAt?: string;
+  updatedAt?: string;
+};
+
+/**
+ * Resolves the session behind a `Cookie` header against the API.
+ *
+ * Only the cookie is forwarded on purpose: passing the incoming request's headers
+ * through would include its `Host`, which Bun's fetch sends as-is and thereby
+ * routes the call to the web host instead of the API.
+ */
+export async function fetchSession(cookie: null | string | undefined): Promise<SessionResponse> {
+  if (!cookie) {
+    return null;
+  }
+
+  try {
+    const response = await fetch(`${env.NEXT_PUBLIC_API_URL}/api/auth/get-session`, {
+      cache: "no-store",
+      headers: { cookie },
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return (await response.json()) as SessionResponse;
+  } catch {
+    return null;
+  }
+}

package/template/apps/web/src/lib/auth.ts

@@ -0,0 +1,8 @@
+import { headers } from "next/headers";
+import { fetchSession } from "@/lib/auth-server";
+
+/** The current session in a server component, route handler or action. */
+export async function getSession() {
+  const headerStore = await headers();
+  return fetchSession(headerStore.get("cookie"));
+}

package/template/apps/web/src/lib/codegen.ts

@@ -0,0 +1,30 @@
+import type { CodegenConfig } from "@graphql-codegen/cli";
+
+/**
+ * `bun run codegen` — introspects the running API (or `CODEGEN_SCHEMA`) and
+ * generates typed `graphql()` documents into src/generated/gql.
+ */
+const config: CodegenConfig = {
+  documents: ["src/**/*.{ts,tsx}", "!src/generated/**"],
+  generates: {
+    "./src/generated/gql/": {
+      config: {
+        enumValues: "./schema-types",
+        scalars: { DateTime: "string" },
+      },
+      preset: "client",
+    },
+    "./src/generated/gql/schema-types.ts": {
+      config: {
+        scalars: { DateTime: "string" },
+      },
+      plugins: ["typescript"],
+    },
+  },
+  ignoreNoDocuments: true,
+  schema:
+    process.env.CODEGEN_SCHEMA ??
+    `${process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001"}/graphql`,
+};
+
+export default config;

package/template/apps/web/src/lib/graphql-client.ts

@@ -0,0 +1,29 @@
+import type { TypedDocumentNode } from "@graphql-typed-document-node/core";
+import { GraphQLClient } from "graphql-request";
+import { env } from "@/env";
+import { toApiError } from "./graphql-utils";
+
+const client = new GraphQLClient(`${env.NEXT_PUBLIC_API_URL}/graphql`, {
+  credentials: "include",
+});
+
+/** Browser-side API client: sends the session cookie, throws `ApiError`s. */
+export const graphqlClient = {
+  async request<TData, TVars>(
+    doc: TypedDocumentNode<TData, TVars>,
+    variables?: TVars,
+  ): Promise<TData> {
+    try {
+      // @ts-expect-error -- graphql-request's overloads don't accept an optional variables arg
+      return await client.request<TData, TVars>(doc, variables);
+    } catch (error) {
+      const apiError = toApiError(error);
+      // @if auth
+      if (apiError.code === "UNAUTHORIZED" && typeof window !== "undefined") {
+        window.location.href = "/sign-in";
+      }
+      // @endif
+      throw apiError;
+    }
+  },
+};

package/template/apps/web/src/lib/graphql-server.ts

@@ -0,0 +1,28 @@
+import "server-only";
+import type { TypedDocumentNode } from "@graphql-typed-document-node/core";
+import { GraphQLClient } from "graphql-request";
+import { env } from "@/env";
+import type { ApiError } from "./graphql-utils";
+import { toApiError } from "./graphql-utils";
+
+const client = new GraphQLClient(`${env.NEXT_PUBLIC_API_URL}/graphql`);
+
+type APIResult<TData> = { data?: TData; error?: ApiError };
+
+/** Server-side API client: forward the incoming cookie to act as the user. */
+export async function APIClient<TData, TVars>(
+  doc: TypedDocumentNode<TData, TVars>,
+  { cookie, variables }: { cookie?: string; variables?: TVars } = {},
+): Promise<APIResult<TData>> {
+  try {
+    // @ts-expect-error -- graphql-request's overloads don't accept an optional variables arg
+    const data = await client.request<TData, TVars>(
+      doc,
+      variables,
+      cookie ? { cookie } : undefined,
+    );
+    return { data };
+  } catch (error: unknown) {
+    return { error: toApiError(error) };
+  }
+}

package/template/apps/web/src/lib/graphql-utils.test.ts

@@ -0,0 +1,32 @@
+import { ClientError } from "graphql-request";
+import { describe, expect, it } from "vitest";
+import { apiErrorMessage, toApiError } from "./graphql-utils";
+
+describe("toApiError", () => {
+  it("maps a dropped connection to NETWORK_ERROR", () => {
+    expect(toApiError(new TypeError("Failed to fetch")).code).toBe("NETWORK_ERROR");
+  });
+
+  it("reads the code and params from the first GraphQL error", () => {
+    const response = {
+      errors: [{ extensions: { code: "NOT_FOUND", params: { id: "1" } }, message: "NOT_FOUND" }],
+      status: 200,
+    } as unknown as ConstructorParameters<typeof ClientError>[0];
+    const error = new ClientError(response, { query: "query { x }" });
+
+    expect(toApiError(error)).toMatchObject({ code: "NOT_FOUND", params: { id: "1" } });
+  });
+});
+
+describe("apiErrorMessage", () => {
+  const t = (key: string) => `t:${key}`;
+
+  it("translates known codes", () => {
+    expect(apiErrorMessage(t, { code: "UNAUTHORIZED" })).toBe("t:UNAUTHORIZED");
+  });
+
+  it("falls back for unknown or missing codes", () => {
+    expect(apiErrorMessage(t, { code: "SOMETHING_NEW" })).toBe("t:defaultError");
+    expect(apiErrorMessage(t, null)).toBe("t:defaultError");
+  });
+});

package/template/apps/web/src/lib/graphql-utils.ts

@@ -0,0 +1,76 @@
+import { ClientError } from "graphql-request";
+import { isNetworkError } from "./network-error";
+
+export type ApiErrorParams = Record<string, unknown>;
+
+/**
+ * A backend failure, carrying the machine-readable `code` the API returns
+ * (never prose) plus any structured `params` for interpolation.
+ *
+ * `message` mirrors `code` so anything that still reads `.message` sees the
+ * code rather than blank text, but display code should go through
+ * `apiErrorMessage` (backed by the `ApiErrors` next-intl namespace) instead of
+ * showing `.message` directly.
+ */
+export class ApiError extends Error {
+  readonly code?: string;
+  readonly params?: ApiErrorParams;
+
+  constructor(code?: string, params?: ApiErrorParams) {
+    super(code ?? "UNKNOWN_ERROR");
+    this.name = "ApiError";
+    this.code = code;
+    this.params = params;
+  }
+}
+
+/**
+ * Builds the `ApiError` a `graphql-request` failure carries. A request that
+ * never reached the API gets the client-side `NETWORK_ERROR` code; anything
+ * else without a response error is codeless.
+ */
+export function toApiError(error: unknown): ApiError {
+  if (isNetworkError(error)) return new ApiError("NETWORK_ERROR");
+
+  const first = error instanceof ClientError ? error.response.errors?.[0] : undefined;
+  const code = first?.extensions?.code as string | undefined;
+  const params = first?.extensions?.params as ApiErrorParams | undefined;
+  return new ApiError(code, params);
+}
+
+/**
+ * The API's `ErrorCode` values (plus the client-side `NETWORK_ERROR`) that have
+ * their own copy in the `ApiErrors` namespace of `messages/*.json`. Anything else
+ * falls back to `ApiErrors.defaultError`, so an unmapped code never shows a raw
+ * translation key on screen.
+ */
+const TRANSLATED_ERROR_CODES = new Set([
+  "BAD_REQUEST",
+  "CONFLICT",
+  "EMAIL_NOT_VERIFIED",
+  "FORBIDDEN",
+  "INSUFFICIENT_ROLE",
+  "INTERNAL_SERVER_ERROR",
+  "NETWORK_ERROR",
+  "NOT_FOUND",
+  "SERVICE_UNAVAILABLE",
+  "TOO_MANY_REQUESTS",
+  "UNAUTHORIZED",
+  "UNPROCESSABLE_ENTITY",
+  "VALIDATION_FAILED",
+]);
+
+/**
+ * Translates an API error's `code` through the `ApiErrors` next-intl namespace,
+ * falling back to `ApiErrors.defaultError`.
+ *
+ * @param t - `useTranslations("ApiErrors")` from the calling component
+ * @param error - The error a mutation/query's `onError`/`error` carries
+ */
+export function apiErrorMessage(
+  t: (key: string) => string,
+  error: null | undefined | { code?: string },
+): string {
+  const code = error?.code;
+  return code && TRANSLATED_ERROR_CODES.has(code) ? t(code) : t("defaultError");
+}

package/template/apps/web/src/lib/hooks/use-media-query.ts

@@ -0,0 +1,21 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+export function useMediaQuery(query: string) {
+  const subscribe = (callback: () => void) => {
+    const media = window.matchMedia(query);
+    media.addEventListener("change", callback);
+    return () => media.removeEventListener("change", callback);
+  };
+
+  const getSnapshot = () => {
+    return window.matchMedia(query).matches;
+  };
+
+  const getServerSnapshot = () => {
+    return false;
+  };
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/template/apps/web/src/lib/metadata.ts

@@ -0,0 +1,17 @@
+import type { Metadata } from "next";
+import { siteConfig } from "@/config/site";
+
+export function constructMetadata(): Metadata {
+  return {
+    description: siteConfig.description,
+    metadataBase: new URL(siteConfig.url),
+    openGraph: {
+      description: siteConfig.description,
+      title: siteConfig.name,
+    },
+    title: {
+      default: siteConfig.name,
+      template: `%s | ${siteConfig.name}`,
+    },
+  };
+}

package/template/apps/web/src/lib/network-error.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { isNetworkError } from "./network-error";
+
+describe("isNetworkError", () => {
+  it.each([
+    ["Firefox", "NetworkError when attempting to fetch resource."],
+    ["Chromium", "Failed to fetch"],
+    ["Safari", "Load failed"],
+    ["Node", "fetch failed"],
+  ])("recognises the %s wording of a failed fetch", (_engine, message) => {
+    expect(isNetworkError(new TypeError(message))).toBe(true);
+  });
+
+  it("ignores a TypeError that is not a failed request", () => {
+    expect(
+      isNetworkError(new TypeError("Cannot read properties of undefined (reading 'id')")),
+    ).toBe(false);
+  });
+
+  it("ignores an error that merely carries the same text", () => {
+    expect(isNetworkError(new Error("Failed to fetch"))).toBe(false);
+    expect(isNetworkError({ message: "Failed to fetch" })).toBe(false);
+  });
+
+  it("ignores values that are not errors at all", () => {
+    expect(isNetworkError(null)).toBe(false);
+    expect(isNetworkError(undefined)).toBe(false);
+    expect(isNetworkError("Failed to fetch")).toBe(false);
+  });
+});

package/template/apps/web/src/lib/network-error.ts

@@ -0,0 +1,17 @@
+/**
+ * Wording each engine puts on the `TypeError` `fetch` rejects with when the
+ * request never got an HTTP response (offline, DNS, refused connection, CORS
+ * block): Firefox, Chromium, Safari, and Node's undici for server-side calls.
+ */
+const FETCH_FAILURE_MESSAGE =
+  /^(?:networkerror when attempting to fetch resource|failed to fetch|load failed|fetch failed|network request failed)/i;
+
+/**
+ * Whether `error` is a request that never reached the API, as opposed to one
+ * the API answered with an error. The browser's wording for it (e.g. "NetworkError
+ * when attempting to fetch resource.") is meaningless to a user, so callers
+ * show translated copy instead of `error.message`.
+ */
+export function isNetworkError(error: unknown): boolean {
+  return error instanceof TypeError && FETCH_FAILURE_MESSAGE.test(error.message);
+}

package/template/apps/web/src/lib/proxy-utils.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from "next/server";
+import { generateCspHeader } from "@/config/csp";
+
+/**
+ * Generates a per-request nonce + CSP and returns the request to hand to the
+ * next middleware (so Next.js nonces its own scripts) plus a helper that stamps
+ * the same header on the response.
+ */
+export function createCspContext(request: NextRequest) {
+  const nonce = crypto.randomUUID().replaceAll("-", "");
+  const cspHeader = generateCspHeader({ nonce });
+  const requestHeaders = new Headers(request.headers);
+  requestHeaders.set("Content-Security-Policy", cspHeader);
+  requestHeaders.set("x-nonce", nonce);
+
+  return {
+    applyTo(response: NextResponse) {
+      response.headers.set("Content-Security-Policy", cspHeader);
+      return response;
+    },
+    request: new NextRequest(request, { headers: requestHeaders }),
+  };
+}
+// @if auth
+
+/** Sends the user to sign-in, remembering where they wanted to go. */
+export function redirectToSignIn(
+  request: NextRequest,
+  pathname: string,
+  locale: string,
+): NextResponse {
+  const signInUrl = new URL(`/${locale}/sign-in`, request.url);
+
+  const requestedPath =
+    (locale ? pathname.slice(locale.length + 1) : pathname) + request.nextUrl.search;
+  if (requestedPath && requestedPath !== "/" && !requestedPath.startsWith("/sign-in")) {
+    signInUrl.searchParams.set("returnTo", requestedPath);
+  }
+
+  return NextResponse.redirect(signInUrl);
+}
+// @endif

package/template/apps/web/src/lib/query-client.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import { isServer, QueryClient } from "@tanstack/react-query";
+
+function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      mutations: {
+        onError: (error) => {
+          console.error("Query mutation failed:", error);
+        },
+      },
+      queries: {
+        staleTime: 60 * 1000,
+      },
+    },
+  });
+}
+
+let browserQueryClient: QueryClient | undefined;
+
+export function getQueryClient() {
+  if (isServer) {
+    return makeQueryClient();
+  } else {
+    browserQueryClient ??= makeQueryClient();
+    return browserQueryClient;
+  }
+}

package/template/apps/web/src/lib/utils.ts

@@ -0,0 +1,5 @@
+import type { ClassValue } from "clsx";
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs));

package/template/apps/web/src/proxy.ts

@@ -0,0 +1,57 @@
+import createMiddleware from "next-intl/middleware";
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server"; // @if auth
+import { guestOnlyRoutes, publicPaths } from "./config/routes"; // @if auth
+import { routing } from "./i18n/routing";
+import { fetchSession } from "./lib/auth-server"; // @if auth
+import { createCspContext, redirectToSignIn } from "./lib/proxy-utils"; // @if auth
+// import { createCspContext } from "./lib/proxy-utils"; // @if !auth
+
+const i18nMiddleware = createMiddleware(routing);
+
+export async function proxy(request: NextRequest) {
+  const csp = createCspContext(request);
+  const response = await handleRequest(request, csp.request);
+  return csp.applyTo(response);
+}
+
+// @if auth
+async function handleRequest(request: NextRequest, requestWithCsp: NextRequest) {
+  const i18nResponse = i18nMiddleware(requestWithCsp);
+  if (i18nResponse.status >= 300 && i18nResponse.status < 400) {
+    return i18nResponse;
+  }
+
+  const { pathname } = request.nextUrl;
+  const locale = pathname.match(/^\/([^/]+)/)?.[1] ?? routing.defaultLocale;
+  const route = pathname.slice(locale.length + 1) || "/";
+  const session = await fetchSession(request.headers.get("cookie"));
+
+  if (!session && !publicPaths.has(pathname)) {
+    return redirectToSignIn(request, pathname, locale);
+  }
+
+  if (session && guestOnlyRoutes.includes(route)) {
+    return NextResponse.redirect(new URL(`/${locale}/dashboard`, request.url));
+  }
+
+  return i18nResponse;
+}
+// @endif
+// @if !auth
+// function handleRequest(_request: NextRequest, requestWithCsp: NextRequest) {
+//   return i18nMiddleware(requestWithCsp);
+// }
+// @endif
+
+export const config = {
+  matcher: [
+    {
+      missing: [
+        { key: "next-router-prefetch", type: "header" },
+        { key: "purpose", type: "header", value: "prefetch" },
+      ],
+      source: "/((?!api|_next|.*\\.[\\w]+$).*)",
+    },
+  ],
+};

package/template/apps/web/test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}

package/template/apps/web/tests/auth.spec.ts

@@ -0,0 +1,17 @@
+import { expect, test } from "@playwright/test";
+
+test.describe("auth", () => {
+  test("sends anonymous visitors of a protected page to sign-in", async ({ page }) => {
+    await page.goto("/en/dashboard");
+
+    await expect(page).toHaveURL(/\/en\/sign-in\?returnTo=%2Fdashboard$/);
+  });
+
+  test("validates the sign-in form before calling the API", async ({ page }) => {
+    await page.goto("/en/sign-in");
+
+    await page.getByRole("button", { name: "Sign in" }).click();
+
+    await expect(page.getByText("Enter a valid email address.")).toBeVisible();
+  });
+});

package/template/apps/web/tests/csp-theme-script.spec.ts

@@ -0,0 +1,37 @@
+import { expect, test } from "@playwright/test";
+
+/**
+ * Guards the hash allowlist in src/config/csp.ts: next-themes' theme-init
+ * <script> (see src/features/shared/provider.tsx) gets no per-request nonce,
+ * so it only runs if its exact rendered bytes match one of the checked-in
+ * sha256 hashes. Turbopack renders it differently in dev vs. `next build`, so
+ * a next-themes/Turbopack upgrade can silently drift the hash and get the
+ * script CSP-blocked (theme flash, no thrown error) without this failing.
+ */
+test.describe("CSP: theme init script", () => {
+  test("next-themes inline script runs without a CSP violation", async ({ page }) => {
+    await page.addInitScript(() => {
+      (window as unknown as { __cspViolations: string[] }).__cspViolations = [];
+      window.addEventListener("securitypolicyviolation", (event) => {
+        (window as unknown as { __cspViolations: string[] }).__cspViolations.push(
+          `${event.violatedDirective}: ${event.blockedURI}`,
+        );
+      });
+    });
+
+    await page.goto("http://localhost:3000/en");
+    await page.waitForLoadState("domcontentloaded");
+
+    const appliedThemeClass = await page.evaluate(
+      () =>
+        document.documentElement.classList.contains("light") ||
+        document.documentElement.classList.contains("dark"),
+    );
+    expect(appliedThemeClass, "next-themes should apply light/dark before hydration").toBe(true);
+
+    const violations = await page.evaluate(
+      () => (window as unknown as { __cspViolations: string[] }).__cspViolations,
+    );
+    expect(violations, "a hash in src/config/csp.ts is stale — see the comment there").toEqual([]);
+  });
+});

package/template/apps/web/tests/home.spec.ts

@@ -0,0 +1,25 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+test.describe("home", () => {
+  test("renders the hero without accessibility violations", async ({ page }) => {
+    await page.goto("/en");
+
+    await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+
+    const results = await new AxeBuilder({ page }).analyze();
+    expect(results.violations).toEqual([]);
+  });
+
+  test("redirects the bare root to the default locale", async ({ page }) => {
+    await page.goto("/");
+
+    await expect(page).toHaveURL(/\/en$/);
+  });
+
+  test("serves the German locale", async ({ page }) => {
+    await page.goto("/de");
+
+    await expect(page.locator("html")).toHaveAttribute("lang", "de");
+  });
+});

package/template/apps/web/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", ".storybook", "**/*.stories.ts", "**/*.stories.tsx"]
+}

package/template/apps/web/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "extends": "@nexst/tsconfig/base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "paths": {
+      "@/*": ["./src/*"],
+      "~sb/*": ["./.storybook/*"]
+    },
+    "allowJs": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".storybook/**/*.ts",
+    ".storybook/**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ]
+}