create-next-style-guide 0.0.0-stage → 0.1.2

package/template/AGENTS.md

@@ -0,0 +1,38 @@
+# Agents (__PROJECT_NAME__)
+
+Generated from [next-style-guide](https://github.com/alidanial7/next-style-guide).
+
+## Maintenance
+
+Stack-wide → here. Feature detail → `.cursor/rules/*.mdc` (glob-scoped — only load when editing matching files). Don't re-read this file mid-task.
+
+## Stack
+
+App Router · TS strict · Zod/Yup env (`src/lib/env.ts`) · __PACKAGE_MANAGER__.
+Optional features (Query, store, endpoints, i18n, SEO, tests, Docker, CI, …) exist only when enabled at scaffold.
+
+## Do
+
+- Thin `page.tsx` / `layout.tsx` — UI in folder-per-component `_components/`.
+- Route-only → `src/app/<route>/_components/<name>/index.tsx`.
+- Layout / home → `src/app/_components/<name>/`.
+- Shared (≥2 routes) → `src/components/` (`ui/` flat for shadcn).
+- Infra → `src/lib/`; API helpers → `src/utils/`; client state → `src/stores/` (when present).
+- Named exports `function Foo()`; default only for Next route files.
+- Prefer Server Components; `"use client"` only when needed.
+- Single `<main>` in root layout — never nest `<main>` in pages/components.
+
+## Don't
+
+- Park single-route UI in `src/components/`.
+- Flat files in `_components/` (use `<name>/index.tsx`).
+- Invent a second folder convention without updating this file + `docs/style-guide/`.
+- Auto `git commit` / `git push` — leave that to the developer.
+
+## Read when needed
+
+| Task | Open |
+|------|------|
+| Conventions | `docs/style-guide/README.md` |
+| Architecture | `docs/style-guide/overview/architecture.md` |
+| Cursor rules | `.cursor/rules/` (glob-scoped) |

package/template/README.md

@@ -0,0 +1,28 @@
+# __PROJECT_NAME__
+
+Next.js App Router app generated with [next-style-guide](https://github.com/alidanial7/next-style-guide).
+
+## Docs
+
+| Audience | Start |
+|----------|--------|
+| Coding agents | [`AGENTS.md`](AGENTS.md) → [`.cursor/rules/`](.cursor/rules/) |
+| Humans | [`docs/style-guide/`](docs/style-guide/) |
+
+## Stack
+
+- Next.js 16 · React 19 · TypeScript
+- Env validation via Zod or Yup
+- App Router under `src/app/`
+- Route-colocated UI under `_components/` (folder-per-component)
+- Package manager: __PACKAGE_MANAGER__
+
+## Setup
+
+```bash
+cp .env.example .env
+__PACKAGE_MANAGER__ install
+__PACKAGE_MANAGER__ dev
+```
+
+App: [http://localhost:3000](http://localhost:3000)

package/template/docs/style-guide/README.md

@@ -0,0 +1,11 @@
+# Style guide — __PROJECT_NAME__
+
+Living conventions for this app. Open one page at a time.
+
+| Page | Topic |
+|------|--------|
+| [Architecture](overview/architecture.md) | Layers: app / components / lib / utils |
+| [Project structure](overview/project-structure.md) | Folder map |
+| [HTTP client](http/client.md) | `apiFetch` helper |
+
+Coding agents: start at [`AGENTS.md`](../../AGENTS.md) → [`.cursor/rules/`](../../.cursor/rules/).

package/template/docs/style-guide/http/client.md

@@ -0,0 +1,9 @@
+# HTTP client
+
+Base helper: `src/lib/http.ts` → `apiFetch`.
+
+- Builds URLs from `NEXT_PUBLIC_API_URL`
+- Expects JSON
+- Throws on non-OK responses
+
+When **endpoints** / axios helpers are enabled, prefer generated clients and `unwrapApiResult` for `{ result, status, success, messages }` responses so route UI never parses envelopes by hand.

package/template/docs/style-guide/overview/architecture.md

@@ -0,0 +1,21 @@
+# Architecture
+
+```text
+src/app/                      → routes + layouts (thin)
+src/app/_components/          → layout / homepage UI only
+src/app/<route>/_components/  → route-only UI
+src/components/               → shared UI (≥2 routes) + ui/ primitives
+src/lib/                      → env, http, shared helpers
+src/utils/                    → API client helpers (when enabled)
+src/providers/                → client providers (Query, theme, Redux, …)
+src/stores/                   → client global state (Zustand / Redux, when enabled)
+src/hooks/ · types/ · constants/
+```
+
+## Rules of thumb
+
+1. **Routes orchestrate** — load data, compose colocated `_components`.
+2. **Colocate by usage** — one route → that route's `_components/`; two+ routes → `src/components/`.
+3. **Server first** — prefer RSC; `"use client"` only at the leaves that need interactivity.
+4. **One HTTP doorway** — `src/lib/http.ts` and/or generated `src/endpoints/*` (when enabled). Avoid ad-hoc `fetch` in UI.
+5. **Split server cache vs UI state** — TanStack Query for server/async cache; Zustand/Redux for client UI/session state only.

package/template/docs/style-guide/overview/project-structure.md

@@ -0,0 +1,36 @@
+# Project structure
+
+Lean App Router layout. Installers only add folders they need (e.g. `stores/`, `endpoints/`).
+
+```text
+__PROJECT_SLUG__/
+├── src/
+│   ├── app/                      # routes + layouts (thin)
+│   │   ├── _components/          # layout / homepage UI
+│   │   └── <route>/_components/  # route-only UI (folder-per-component)
+│   ├── components/               # shared UI (≥2 routes); ui/ for primitives
+│   ├── lib/                      # env, http, cn, seo, …
+│   ├── utils/                    # API helpers (axios, errors, tokens, …)
+│   ├── providers/                # client providers (Query, theme, Redux, …)
+│   ├── stores/                   # client store slices (Zustand / Redux) — when enabled
+│   ├── hooks/                    # shared hooks
+│   ├── types/                    # shared types
+│   └── constants/                # shared constants
+├── docs/style-guide/             # conventions that match enabled options
+├── AGENTS.md
+├── .cursor/rules/                # glob-scoped agent rules
+├── .env.example
+└── package.json
+```
+
+## Placement rules
+
+| What | Where |
+|------|--------|
+| One route only | `src/app/<route>/_components/<name>/index.tsx` |
+| Layout / home chrome | `src/app/_components/<name>/` |
+| Shared across ≥2 routes | `src/components/` |
+| Env / pure helpers | `src/lib/` |
+| HTTP / API adapters | `src/utils/` (or generated `src/endpoints/`) |
+| Client global state | `src/stores/` |
+| Client providers | `src/providers/` |

package/template/eslint.config.mjs

@@ -0,0 +1,13 @@
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+/** Minimal Next flat config. Replaced when the enhanced ESLint option is on. */
+const eslintConfig = [
+  ...nextVitals,
+  ...nextTs,
+  {
+    ignores: [".next/**", "out/**", "build/**", "next-env.d.ts", "node_modules/**"],
+  },
+];
+
+export default eslintConfig;

package/template/gitignore

@@ -0,0 +1,39 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+*.tsbuildinfo
+next-env.d.ts
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env
+.env
+.env*.local
+!.env.example
+
+# vercel
+.vercel

package/template/next-env.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited — see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/template/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;

package/template/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__PROJECT_SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "pnpm@9.15.0",
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "16.4.5",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "eslint": "^9.17.0",
+    "eslint-config-next": "16.4.5",
+    "typescript": "^5.7.2"
+  }
+}

package/template/src/app/_components/welcome-card/index.tsx

@@ -0,0 +1,24 @@
+/** Homepage sample — replace when you add real route UI. */
+export function WelcomeCard() {
+  return (
+    <div className="card">
+      <h2>App layout</h2>
+      <ul>
+        <li>
+          Route-only UI →{" "}
+          <code>src/app/&lt;route&gt;/_components/&lt;name&gt;/index.tsx</code>
+        </li>
+        <li>
+          Layout / homepage UI → <code>src/app/_components/</code>
+        </li>
+        <li>
+          Shared across 2+ routes → <code>src/components/</code>
+        </li>
+        <li>
+          HTTP / env → <code>src/lib/</code> · API helpers →{" "}
+          <code>src/utils/</code>
+        </li>
+      </ul>
+    </div>
+  );
+}

package/template/src/app/globals.css

@@ -0,0 +1,84 @@
+:root {
+  color-scheme: light;
+  --bg: #f6f4ef;
+  --fg: #14201b;
+  --muted: #5b6b63;
+  --accent: #0b5fff;
+  --card: #ffffff;
+  --border: #d9e0db;
+  --font: "Segoe UI", system-ui, sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  min-height: 100%;
+  background: radial-gradient(circle at top left, #eef3ff, transparent 40%),
+    var(--bg);
+  color: var(--fg);
+  font-family: var(--font);
+}
+
+a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+main {
+  width: min(720px, calc(100% - 2rem));
+  margin: 0 auto;
+  padding: 4rem 0 3rem;
+}
+
+.hero {
+  display: grid;
+  gap: 1rem;
+}
+
+.hero h1 {
+  margin: 0;
+  font-size: clamp(2rem, 5vw, 3rem);
+  letter-spacing: -0.03em;
+}
+
+.hero p {
+  margin: 0;
+  color: var(--muted);
+  line-height: 1.6;
+  max-width: 40rem;
+}
+
+.card {
+  margin-top: 2rem;
+  padding: 1.25rem 1.5rem;
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+}
+
+.card h2 {
+  margin: 0 0 0.5rem;
+  font-size: 1rem;
+}
+
+.card ul {
+  margin: 0;
+  padding-left: 1.1rem;
+  color: var(--muted);
+  line-height: 1.7;
+}
+
+.meta {
+  margin-top: 2rem;
+  font-size: 0.875rem;
+  color: var(--muted);
+}

package/template/src/app/layout.tsx

@@ -0,0 +1,22 @@
+import type { Metadata } from "next";
+
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "__PROJECT_NAME__",
+  description: "Generated with next-style-guide",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}

package/template/src/app/page.tsx

@@ -0,0 +1,25 @@
+import { WelcomeCard } from "@/app/_components/welcome-card";
+
+export default function HomePage() {
+  return (
+    <>
+      <section className="hero">
+        <h1>__PROJECT_NAME__</h1>
+        <p>
+          Next.js App Router scaffold from{" "}
+          <strong>next-style-guide</strong>. Route UI lives under{" "}
+          <code>src/app/_components/</code> (or a route&apos;s{" "}
+          <code>_components/</code>); shared primitives under{" "}
+          <code>src/components/</code>; HTTP helpers under <code>src/lib/</code>.
+        </p>
+      </section>
+
+      <WelcomeCard />
+
+      <p className="meta">
+        Read <code>AGENTS.md</code> and <code>docs/style-guide/</code> before
+        adding routes.
+      </p>
+    </>
+  );
+}

package/template/src/lib/env.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+/**
+ * Validated public env. Import from Client Components only for NEXT_PUBLIC_*.
+ * Server-only secrets stay out of this schema until needed.
+ */
+const publicEnvSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url().default("http://localhost:3000"),
+  NEXT_PUBLIC_API_URL: z.string().url().default("http://localhost:8000"),
+});
+
+export type PublicEnv = z.infer<typeof publicEnvSchema>;
+
+export const env: PublicEnv = publicEnvSchema.parse({
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
+});

package/template/src/lib/http.ts

@@ -0,0 +1,28 @@
+import { env } from "@/lib/env";
+
+/**
+ * Minimal JSON fetch helper.
+ * Prefer generated endpoints / axios helpers when that option is enabled.
+ */
+export async function apiFetch<T>(
+  path: string,
+  init?: RequestInit,
+): Promise<T> {
+  const url = path.startsWith("http")
+    ? path
+    : `${env.NEXT_PUBLIC_API_URL.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      Accept: "application/json",
+      ...(init?.headers ?? {}),
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`API ${response.status}: ${response.statusText}`);
+  }
+
+  return response.json() as Promise<T>;
+}

package/template/src/lib/utils.ts

@@ -0,0 +1,6 @@
+/** Lightweight class join — swap for clsx + tailwind-merge when shadcn lands. */
+export function cn(
+  ...parts: Array<string | false | null | undefined>
+): string {
+  return parts.filter(Boolean).join(" ");
+}

package/template/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.