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

package/addons/ci/.cursor/rules/ci.mdc

@@ -0,0 +1,11 @@
+---
+description: GitHub Actions CI workflow
+globs: .github/workflows/**
+alwaysApply: false
+---
+
+# CI
+
+- Workflow: `.github/workflows/ci.yml` — install → typecheck → lint/format (if enabled) → build.
+- Keep jobs green before merge. Don't skip checks with unrelated workflow edits.
+- New required scripts must be reflected in the workflow steps.

package/addons/ci/docs/style-guide/ops/ci.md

@@ -0,0 +1,7 @@
+# CI / CD
+
+GitHub Actions: `.github/workflows/ci.yml`.
+
+Typical steps: checkout → pnpm → install → `typecheck` → `lint` / Prettier check (when enabled) → `build`.
+
+Push to `main`/`master` and pull requests trigger the workflow.

package/addons/docker/.cursor/rules/docker.mdc

@@ -0,0 +1,12 @@
+---
+description: Docker / standalone Next production image
+globs: docker/**,.dockerignore,next.config.ts,Dockerfile*
+alwaysApply: false
+---
+
+# Docker
+
+- Image: `docker/production.Dockerfile` (multi-stage, Next `output: "standalone"`).
+- Build args: `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_API_URL` (inlined at build).
+- `HUSKY=0` in builder. Healthcheck hits `/` on port 3000.
+- Changing env/build args/ports → call out infra/deploy follow-ups in the final response.

package/addons/docker/.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+.next
+.git
+.cursor
+.env*
+!.env.example
+*.tsbuildinfo
+coverage
+out
+README.md
+AGENTS.md
+_gen_smoke

package/addons/docker/docker/production.Dockerfile

@@ -0,0 +1,53 @@
+# ---------------------------------------------------------------------------- #
+#                        Stage 1: Base & Dependencies                          #
+# ---------------------------------------------------------------------------- #
+FROM node:22-alpine AS builder
+
+RUN apk add --no-cache libc6-compat
+RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
+
+WORKDIR /app
+
+ENV HUSKY=0 \
+    NEXT_TELEMETRY_DISABLED=1
+
+ARG NEXT_PUBLIC_APP_URL=http://localhost:3000
+ARG NEXT_PUBLIC_API_URL=http://localhost:8000
+
+ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL \
+    NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
+
+COPY package.json pnpm-lock.yaml .npmrc* ./
+RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
+    pnpm install --frozen-lockfile
+
+COPY . /app/
+
+RUN pnpm build
+
+# ---------------------------------------------------------------------------- #
+#                        Stage 2: Production Runner                            #
+# ---------------------------------------------------------------------------- #
+FROM node:22-alpine AS runner
+
+RUN apk add --no-cache curl
+
+WORKDIR /app
+
+ENV NODE_ENV=production \
+    NEXT_TELEMETRY_DISABLED=1 \
+    HOSTNAME=0.0.0.0 \
+    PORT=3000
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=node:node /app/.next/standalone ./
+COPY --from=builder --chown=node:node /app/.next/static ./.next/static
+
+USER node
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
+    CMD curl -fsS http://127.0.0.1:3000/ || exit 1
+
+CMD ["node", "server.js"]

package/addons/docker/docs/style-guide/ops/docker.md

@@ -0,0 +1,14 @@
+# Docker
+
+Production image: `docker/production.Dockerfile`.
+
+Requires `output: "standalone"` in `next.config.ts` (set by the Docker installer).
+
+```bash
+docker build -f docker/production.Dockerfile \
+  --build-arg NEXT_PUBLIC_APP_URL=https://example.com \
+  --build-arg NEXT_PUBLIC_API_URL=https://api.example.com \
+  -t __PROJECT_SLUG__ .
+```
+
+Runner exposes `3000`. See `.dockerignore`.

package/addons/docs/data/tanstack-query.md

@@ -0,0 +1,7 @@
+# TanStack Query
+
+`QueryProvider` wraps the root layout (`src/providers/query-provider.tsx`).
+
+- Use `useQuery` / `useMutation` for client data.
+- Prefer generated endpoint modules + query-key factories when OpenAPI codegen is enabled.
+- Keep Server Components for RSC-friendly fetches when you do not need client cache.

package/addons/docs/examples/api-app-crud.md

@@ -0,0 +1,94 @@
+# Example: tiny CRUD + login flow (`api-app`)
+
+This walkthrough matches the **`api-app`** preset (Tailwind · shadcn · JWT · TanStack Query · Zustand · endpoints · envelope).
+
+## 1. Scaffold
+
+```bash
+npx create-next-style-guide@latest inventory --yes --preset api-app
+cd inventory
+cp .env.example .env
+# NEXT_PUBLIC_API_URL=http://localhost:8000
+docker compose up -d   # stub API on :8000 — swap for your real backend
+```
+
+## 2. Generate endpoints
+
+Point `scripts/endpoints.codegen.json` at your OpenAPI schema, then:
+
+```bash
+pnpm endpoints:generate
+```
+
+You get typed clients under `src/endpoints/` plus axios helpers that unwrap envelopes.
+
+## 3. Login (JWT)
+
+Store tokens with `src/utils/token-storage.ts`. After your API login:
+
+```ts
+import { setTokens } from "@/utils/token-storage";
+
+await setTokens({
+  accessToken: result.access,
+  refreshToken: result.refresh,
+});
+```
+
+Axios (`src/utils/axios-instance.ts`) attaches `Authorization` and refreshes on `401`.
+
+## 4. List + create (Query)
+
+```tsx
+"use client";
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { getItems, postItems } from "@/endpoints"; // names depend on your schema
+
+export function ItemsPanel() {
+  const qc = useQueryClient();
+  const { data, isLoading } = useQuery({
+    queryKey: ["items"],
+    queryFn: () => getItems(),
+  });
+  const create = useMutation({
+    mutationFn: (body: { name: string }) => postItems(body),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["items"] }),
+  });
+
+  if (isLoading) return <p>Loading…</p>;
+  return (
+    <div>
+      <ul>{data?.map((item) => <li key={item.id}>{item.name}</li>)}</ul>
+      <button
+        type="button"
+        onClick={() => create.mutate({ name: "New item" })}
+      >
+        Add
+      </button>
+    </div>
+  );
+}
+```
+
+Colocate the panel under `src/app/(app)/items/_components/items-panel/`.
+
+## 5. UI state (Zustand)
+
+Keep server lists in Query; use the store for UI-only flags:
+
+```ts
+import { useAppStore } from "@/stores/app-store";
+
+const hydrated = useAppStore((s) => s.hydrated);
+```
+
+## Conventions checklist
+
+| Concern | Place |
+|---------|--------|
+| Route UI | `src/app/<route>/_components/<name>/` |
+| Shared UI | `src/components/` |
+| HTTP | generated `src/endpoints/*` / `apiFetch` |
+| Providers | `src/providers/app-providers.tsx` |
+| Agent rules | `AGENTS.md` + `.cursor/rules/` |

package/addons/docs/ui/icons.md

@@ -0,0 +1,5 @@
+# Icons
+
+Icon package was selected at scaffold time. Follow `.cursor/rules/icons.mdc`.
+
+Do not mix Lucide and Tabler in the same app.

package/addons/endpoints/.cursor/rules/endpoints.mdc

@@ -0,0 +1,17 @@
+---
+description: OpenAPI codegen + API helpers
+globs: src/endpoints/**,scripts/generate-endpoints.ts,scripts/endpoints.codegen.json,src/utils/api-error.ts,src/utils/api-result.ts,src/utils/form-data.ts,src/utils/search-params.ts,src/utils/axios-instance.ts
+alwaysApply: false
+---
+
+# Endpoints
+
+`pnpm endpoints:generate` refreshes `src/endpoints/*` from OpenAPI (`scripts/endpoints.codegen.json`). Generated files are AUTO-GENERATED — don't edit (keep `Types.ts`). No Zod in codegen.
+
+- Shape: `*Body` request; `*Call` `{ request: { path?, params?, body? } }`; unwrap with `unwrapApiResult`.
+- Calls via `api` (`@/utils/axios-instance`) only — not from UI components directly.
+- Uploads: `toApiBody` · queries: `toSearchParams`.
+- Errors: `getApiErrorMessage` / `extractApiFieldErrors` / field helpers (`@/utils/api-error`).
+- Query keys: always `get<EndpointName>QueryKey(...)` from generated modules — never ad-hoc `["resource"]` strings.
+- Params: use exported `*DefaultParams`; don't hardcode page sizes in UI.
+- Enums: reuse `src/endpoints/enums.ts` types + `AS_CONST` arrays for selects/Zod.

package/addons/endpoints/docs/style-guide/http/endpoints.md

@@ -0,0 +1,21 @@
+# OpenAPI endpoints
+
+Generate typed clients from your Django (or any) OpenAPI schema:
+
+```bash
+pnpm endpoints:generate
+# optional override:
+pnpm endpoints:generate --url=http://localhost:8000/api/docs/schema/?format=json
+```
+
+Config: `scripts/endpoints.codegen.json`
+
+| Path | Role |
+|------|------|
+| `src/endpoints/` | Generated modules (+ hand-written `Types.ts`) |
+| `src/utils/axios-instance.ts` | Shared `api` client |
+| `src/utils/api-result.ts` | Envelope unwrap |
+| `src/utils/api-error.ts` | Error helpers |
+| `src/utils/search-params.ts` / `form-data.ts` | Codegen helpers |
+
+Do not call `api` from UI — import generated endpoint functions (and wire them through TanStack Query when enabled).

package/addons/endpoints/scripts/endpoints.codegen.json

@@ -0,0 +1,7 @@
+{
+  "schemaUrl": "http://localhost:8000/api/docs/schema/?format=json",
+  "basePath": "/api/v1",
+  "outDir": "src/endpoints",
+  "preserve": ["Types.ts", ".generated-manifest.json"],
+  "header": "/* AUTO-GENERATED by `pnpm endpoints:generate` — DO NOT EDIT. */"
+}