@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/nextjs/architecture/references/fsd-structure.md

@@ -0,0 +1,77 @@
+# Feature-Sliced Design (FSD) Structure
+
+Adapted for Next.js App Router.
+
+## Directory Layout
+
+```text
+app/                 # App Layer (Routing & Layouts)
+  (app)/             # Public Pages
+    page.tsx
+  layout.tsx         # Root Provider Setup
+  globals.css        # Global Styles
+
+src/                 # Source Content
+  widgets/           # Compositional Layers (Header, Footer, Sidebar)
+    header/
+      ui/
+      index.ts
+
+  features/          # User Interactions (AddToCart, FilterList)
+    auth-login/
+      ui/            # LoginForm.tsx
+      model/         # Server Actions, Zod Schemas
+      index.ts
+
+  entities/          # Business Models (Product, User)
+    product/
+      ui/            # ProductCard.tsx (Presentation only)
+      model/         # types.ts, complex validation
+      index.ts
+
+  shared/            # Reusable, Business-Agnostic
+    ui/              # Buttons, Inputs (shadcn)
+    lib/             # Utils, Hooks
+    api/             # Base fetch wrappers & Simple CRUD
+      client.ts
+      endpoints/
+        orders.ts    # Simple API calls (keep out of entities)
+    auth/            # Auth Session/Tokens
+      index.ts
+    config/          # Env vars
+```
+
+## Segments (Inner Structure)
+
+Files inside slices (e.g., `features/login/*`) must follow these standard segment names:
+
+| Segment       | Purpose                      | Examples                                               |
+| :------------ | :--------------------------- | :----------------------------------------------------- |
+| **`ui/`**     | Visual components            | `LoginForm.tsx`, `ProductCard.tsx`                     |
+| **`model/`**  | Business logic, state, types | `actions.ts` (Server Actions), `store.ts`, `schema.ts` |
+| **`api/`**    | Remote data interactions     | `fetchProduct()`, `useProductQuery()`                  |
+| **`lib/`**    | Helper functions             | `formatCurrency.ts`, `dateUtils.ts`                    |
+| **`config/`** | Configuration & constants    | `env.ts`, `constants.ts`                               |
+
+**Note**: Do not use generic folder names like `components/`, `hooks/`, or `utils/` inside slices. Use the semantic segments above.
+
+## Anti-Patterns ("Excessive Entities")
+
+1. **Refactor Later**: Don't start with `entities/`. Put logic in `features/` or `pages/` (slices) first. Extract to `entities/` only when strictly reused.
+2. **Auth is Shared**: User session/tokens often belong in `shared/auth` or `shared/session`, not `entities/user`, because they are app-wide context distinct from the business entity "User".
+3. **CRUD in Shared**: Simple API endpoints (CRUD) without complex domain logic should go in `shared/api/endpoints/`. Don't create an entity just to wrap a fetch call.
+
+## Layer Responsibilities
+
+1. **App (`app/`)**:
+   - **Role**: Entry point. Contains _only_ Next.js routing files (`page.tsx`, `layout.tsx`).
+   - **Rule**: Files here should be thin wrappers that import widgets or features.
+2. **Widgets (`src/widgets/`)**:
+   - **Role**: Assemble features and entities into self-contained blocks (e.g., `Header`, `ProductList`).
+3. **Features (`src/features/`)**:
+   - **Role**: Handle user scenarios (e.g., `AuthByEmail`, `ToggleTheme`). Contains form logic & Server Actions.
+4. **Entities (`src/entities/`)**:
+   - **Role**: Business domain concepts. High reuse potential.
+   - **Warning**: Avoid "Anemic Domain Models". If it's just data types, put them in `shared/api`.
+5. **Shared (`src/shared/`)**:
+   - **Role**: UI Kit (Buttons), Utils, API Clients. No business logic.

package/rules/nextjs/authentication/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: Next.js Authentication
+description: Secure token storage (HttpOnly Cookies) and Middleware patterns.
+metadata:
+  labels: [nextjs, auth, security, cookies]
+  triggers:
+    files: ['middleware.ts', '**/auth.ts', '**/login/page.tsx']
+    keywords: [cookie, jwt, session, localstorage, auth]
+---
+
+# Authentication & Token Management
+
+## **Priority: P0 (CRITICAL)**
+
+Use **HttpOnly Cookies** for token storage. **Never** use LocalStorage.
+
+## Key Rules
+
+1. **Storage**: Use `cookies().set()` with `httpOnly: true`, `secure: true`, `sameSite: 'lax'`.
+   - _Reference_: [Auth Implementation](references/auth-implementation.md) (See "Setting Tokens").
+2. **Access**: Read tokens in Server Components via `cookies().get()`.
+   - _Reference_: [Auth Implementation](references/auth-implementation.md) (See "Reading Tokens").
+3. **Protection**: Guard routes in `middleware.ts` before rendering.
+   - _Reference_: [Auth Implementation](references/auth-implementation.md) (See "Middleware Protection").
+
+## Anti-Pattern: LocalStorage
+
+- **Security Risk**: Vulnerable to XSS.
+- **Performance Hit**: Incompatible with Server Components (RSC). Forces client hydration and causes layout shift.

package/rules/nextjs/authentication/references/auth-implementation.md

@@ -0,0 +1,73 @@
+# Authentication Implementation
+
+## 1. Setting Tokens (Server Action)
+
+```typescript
+'use server';
+import { cookies } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export async function login(formData: FormData) {
+  // 1. Backend Call
+  // const result = await api.login(formData);
+  // Simulated result:
+  const result = { accessToken: 'fake_enc_token' };
+
+  // 2. Save Token Securely
+  (await cookies()).set('session', result.accessToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 60 * 60 * 24 * 7, // 1 week
+    path: '/',
+    sameSite: 'lax',
+  });
+
+  redirect('/dashboard');
+}
+
+export async function logout() {
+  (await cookies()).delete('session');
+  redirect('/login');
+}
+```
+
+## 2. Reading Tokens (DAL)
+
+```typescript
+// lib/auth.ts
+import 'server-only';
+import { cookies } from 'next/headers';
+
+export async function getSession() {
+  const cookieStore = await cookies();
+  const session = cookieStore.get('session')?.value;
+  if (!session) return null;
+  // return verifyJwt(session);
+  return { user: 'simulated' };
+}
+```
+
+## 3. Middleware Protection
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const currentUser = request.cookies.get('session')?.value;
+  const isLoginPage = request.nextUrl.pathname.startsWith('/login');
+
+  if (!currentUser && !isLoginPage) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  if (currentUser && isLoginPage) {
+    return NextResponse.redirect(new URL('/dashboard', request.url));
+  }
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'], // Exclude static files
+};
+```

package/rules/nextjs/caching/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: Next.js Caching Architecture
+description: The 4 layers of caching (Memoization, Data Cache, Full Route, Router Cache).
+metadata:
+  labels: [nextjs, caching, isr, revalidation]
+  triggers:
+    files: ['**/page.tsx', '**/layout.tsx', '**/action.ts']
+    keywords: [unstable_cache, revalidateTag, Router Cache, Data Cache]
+---
+
+# Caching Architecture
+
+## **Priority: P1 (HIGH)**
+
+Next.js has 4 distinct caching layers. Understanding them prevents stale data bugs.
+
+## The 4 Layers
+
+| Layer                      | Where  | Duration       | Purpose                                              | Control            |
+| :------------------------- | :----- | :------------- | :--------------------------------------------------- | :----------------- |
+| **1. Request Memoization** | Server | Per Request    | Deduplicate same `fetch()` calls in one render pass. | `AbortController`  |
+| **2. Data Cache**          | Server | Persistent     | Store data across user requests.                     | `revalidateTag`    |
+| **3. Full Route Cache**    | Server | Persistent     | Store HTML/RSC payload. (Static Rendering).          | `revalidatePath`   |
+| **4. Router Cache**        | Client | Session (< 5m) | Navigating back/forward without server hit.          | `router.refresh()` |
+
+## 1. Request Memoization
+
+- **Behavior**: Calling `getUser(1)` in `layout`, `page`, and `component` only triggers 1 network call.
+- **Key**: Matches URL and Options exactly.
+- **Non-Fetch**: For DB calls/Prisma, use React `cache()` manually.
+
+  ```tsx
+  import { cache } from 'react';
+  const getItem = cache(async (id) => db.item.findUnique({ id }));
+  ```
+
+## 2. Data Cache (The "Server Persistence")
+
+- **Default**: `fetch` tracks cache indefinitely (`force-cache`).
+- **Scaling**:
+  - **Vercel**: Shared globally via KV/Blob.
+  - **Self-Hosted**: Stored in filesystem (Pod ephemeral storage). **Critical**: Must configure a shared `cacheHandler` (Redis) for multi-pod Kubernetes setups, otherwise pods have desynchronized caches.
+- **Granular Control**: Use `unstable_cache` for DB queries caching.
+
+  ```tsx
+  import { unstable_cache } from 'next/cache';
+  const getCachedUser = unstable_cache(
+    async (id) => db.user.find(id),
+    ['users-key'],
+    { tags: ['users'], revalidate: 60 },
+  );
+  ```
+
+## 3. Router Cache (The "Client Stale")
+
+- **Problem**: User updates a listing, navigates back, and sees old data.
+- **Cause**: Client-side Router Cache holds payload for 30s (dynamic) or 5m (static).
+- **Fix**: Call `router.refresh()` in a Client Component or `revalidatePath()` in a Server Action (which automatically invalidates Router Cache).
+
+## Strategies
+
+- **Opt-Out (Real-Time)**:
+  - Data: `fetch(..., { cache: 'no-store' })`
+  - Route: `export const dynamic = 'force-dynamic'`
+- **On-Demand (CMS/Admin)**:
+  - Use `revalidateTag('collection')` for surgical updates. Better than `revalidatePath` (which nukes the whole URL).

package/rules/nextjs/caching/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Next.js Caching References
+
+## References
+
+- [**Cache Strategies**](cache-strategies.md) - Full Route, Data, Request
+
+## Quick Checks
+
+- [ ] Understand cache hierarchy
+- [ ] Use revalidation strategies appropriately
+- [ ] Tags for granular cache invalidation
+- [ ] unstable_cache for DB queries
+- [ ] Opt-out with force-dynamic when needed

package/rules/nextjs/caching/references/cache-strategies.md

@@ -0,0 +1,168 @@
+# Next.js Cache Strategies
+
+## Cache Hierarchy
+
+```
+1. Request Memoization (React cache)
+   - Same request deduped during render
+   
+2. Data Cache (Next.js)
+   - Persisted across requests
+   - Controlled by fetch options
+   
+3. Full Route Cache
+   - Static HTML/RSC payload
+   - Invalidated by revalidation
+   
+4. Router Cache (Client)
+   - Prefetched routes
+   - Session-based
+```
+
+## Data Cache Controls
+
+```tsx
+// Default - cached indefinitely
+fetch('https://api.example.com/data');
+
+// No caching
+fetch('https://api.example.com/data', { cache: 'no-store' });
+
+// Time-based revalidation
+fetch('https://api.example.com/data', { 
+  next: { revalidate: 3600 } // 1 hour
+});
+
+// Tag-based revalidation
+fetch('https://api.example.com/posts', { 
+  next: { tags: ['posts'] }
+});
+
+// Revalidate by tag
+import { revalidateTag } from 'next/cache';
+revalidateTag('posts');
+
+// Revalidate by path
+import { revalidatePath } from 'next/cache';
+revalidatePath('/blog');
+revalidatePath('/blog', 'layout'); // Include layouts
+```
+
+## Route Segment Config
+
+```tsx
+// app/page.tsx
+
+// Force dynamic rendering
+export const dynamic = 'force-dynamic';
+
+// Force static (error if dynamic features used)
+export const dynamic = 'force-static';
+
+// Default - auto detect
+export const dynamic = 'auto';
+
+// Time-based revalidation for entire route
+export const revalidate = 3600; // 1 hour
+
+// Disable caching
+export const revalidate = 0;
+
+// Runtime
+export const runtime = 'nodejs'; // or 'edge'
+```
+
+## Database Query Caching
+
+```tsx
+import { unstable_cache } from 'next/cache';
+
+const getCachedPosts = unstable_cache(
+  async () => {
+    return db.post.findMany();
+  },
+  ['posts'], // cache key
+  {
+    revalidate: 3600,
+    tags: ['posts'],
+  }
+);
+
+// Usage
+async function BlogPage() {
+  const posts = await getCachedPosts();
+  return <PostList posts={posts} />;
+}
+
+// Invalidate
+'use server';
+export async function createPost(data: PostData) {
+  await db.post.create({ data });
+  revalidateTag('posts');
+}
+```
+
+## Request Memoization
+
+```tsx
+import { cache } from 'react';
+
+// Deduped during single render pass
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } });
+});
+
+// Both components share same request
+async function UserName({ id }: { id: string }) {
+  const user = await getUser(id);
+  return <span>{user.name}</span>;
+}
+
+async function UserAvatar({ id }: { id: string }) {
+  const user = await getUser(id);
+  return <img src={user.avatar} />;
+}
+```
+
+## Opting Out of Caching
+
+```tsx
+// Dynamic functions opt out automatically
+import { cookies, headers } from 'next/headers';
+
+async function Page() {
+  const cookieStore = await cookies(); // Dynamic
+  const headersList = await headers(); // Dynamic
+  // Route becomes dynamic
+}
+
+// searchParams make page dynamic
+async function Page({ 
+  searchParams 
+}: { 
+  searchParams: Promise<{ q: string }> 
+}) {
+  const { q } = await searchParams; // Dynamic
+}
+```
+
+## Cache Best Practices
+
+```tsx
+// ✅ Good - cache expensive operations
+const getExpensiveData = unstable_cache(
+  async () => heavyComputation(),
+  ['expensive-data'],
+  { revalidate: 3600 }
+);
+
+// ✅ Good - granular cache invalidation
+fetch('/api/posts', { next: { tags: ['posts'] } });
+fetch(`/api/posts/${id}`, { next: { tags: ['posts', `post-${id}`] } });
+
+// After update
+revalidateTag(`post-${id}`); // Only invalidates specific post
+
+// ❌ Avoid - overly broad invalidation
+revalidatePath('/'); // Invalidates everything
+```

package/rules/nextjs/data-access-layer/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: Next.js Data Access Layer
+description: Secure, reusable data access patterns with DTOs and Taint checks.
+metadata:
+  labels: [nextjs, dal, architecture, security]
+  triggers:
+    files: ['**/lib/data.ts', '**/services/*.ts', '**/dal/**']
+    keywords: [DAL, Data Access Layer, server-only, DTO]
+---
+
+# Data Access Layer (DAL)
+
+## **Priority: P1 (HIGH)**
+
+Centralize all data access (Database & External APIs) to ensure consistent security, authorization, and caching.
+
+## Principles
+
+1. **Server-Only**: Must include `import 'server-only'` to prevent Client bundling.
+2. **Auth Co-location**: Auth checks (`session.role`) must be **inside** the DAL function.
+3. **DTO Transformation**: Return plain objects (DTOs), never raw ORM instances.
+4. **No Internal Fetch**: Call DAL functions directly. Do not `fetch('localhost/api')`.
+
+## Implementation
+
+| Approach              | When to use                                      | Reference                           |
+| :-------------------- | :----------------------------------------------- | :---------------------------------- |
+| **API Gateway (BFF)** | Enterprise apps with separated Backend (NestJS). | [Pattern A](references/patterns.md) |
+| **Direct DB**         | Fullstack apps or Admin Panels.                  | [Pattern B](references/patterns.md) |
+
+## Limitations
+
+- **Client Components**: Cannot import DAL files. Must use Server Actions or Route Handlers as bridges.

package/rules/nextjs/data-access-layer/references/patterns.md

@@ -0,0 +1,66 @@
+# Data Access Layer Patterns
+
+## Pattern A: API Gateway / BFF (Recommended)
+
+Use when Next.js is a generic frontend for a separate backend (NestJS/Go).
+
+```typescript
+import 'server-only';
+import { cache } from 'react';
+import { getToken } from '@/lib/auth';
+
+const API_URL = process.env.API_GATEWAY_URL;
+
+export const getProjectDetails = cache(async (id: string) => {
+  // 1. Forward Auth Headers
+  const token = await getToken();
+
+  // 2. Upstream Fetch with Next.js Cache tags
+  const res = await fetch(`${API_URL}/projects/${id}`, {
+    headers: { Authorization: `Bearer ${token}` },
+    next: { tags: [`project-${id}`] },
+  });
+
+  if (!res.ok) {
+    if (res.status === 404) return null;
+    throw new Error('Upstream API Failed');
+  }
+
+  const data = await res.json();
+
+  // 3. UI-Specific DTO Mapping
+  return {
+    title: data.attributes.title,
+    isActive: data.status === 'published',
+  };
+});
+```
+
+## Pattern B: Direct Database
+
+Use when Next.js owns the data (Fullstack).
+
+```typescript
+import 'server-only';
+import { cache } from 'react';
+import { verifySession } from '@/lib/auth';
+import { db } from '@/lib/prisma';
+
+export const getSafeUserProfile = cache(async (slug: string) => {
+  const session = await verifySession();
+
+  // Auth Co-location
+  const canView = session.role === 'admin' || session.slug === slug;
+  if (!canView) throw new Error('Unauthorized');
+
+  const data = await db.user.findUnique({ where: { slug } });
+  if (!data) return null;
+
+  // DTO Transformation
+  return {
+    id: data.id,
+    name: data.name,
+    avatar: data.avatarUrl,
+  };
+});
+```

package/rules/nextjs/data-fetching/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: Next.js Data Fetching
+description: Fetch API, Caching, and Revalidation strategies.
+metadata:
+  labels: [nextjs, data-fetching, caching]
+  triggers:
+    files: ['**/*.tsx', '**/service.ts']
+    keywords: [fetch, revalidate, no-store, force-cache]
+---
+
+# Data Fetching (App Router)
+
+## **Priority: P0 (CRITICAL)**
+
+Fetch data directly in Server Components using `async/await`.
+
+## Fetch API Extensions
+
+Next.js extends the native `fetch` API for granular caching control.
+
+- **Static (Default)**: `fetch('https://api.com')` -> `cache: 'force-cache'`. Built at build time.
+- **Dynamic**: `fetch('...', { cache: 'no-store' })`. Fetched on every request.
+- **Revalidated (ISR)**: `fetch('...', { next: { revalidate: 60 } })`. Cached for 60s.
+
+## Patterns
+
+- **Colocation**: Fetch data where it's used. Next.js automatically deduplicates requests for the same URL in the same render pass.
+- **Parallel**: Use `Promise.all()` to prevent waterfalls.
+
+  ```tsx
+  const [user, posts] = await Promise.all([getUser(), getPosts()]);
+  ```
+
+- **Blocking**: To prevent UI blocking, wrap the component in `<Suspense>` and stream the result.
+
+## Revalidation
+
+- **Path**: `revalidatePath('/blog/[slug]')` - Purges cache for specific route.
+- **Tag**: `revalidateTag('collection')` - Purges all fetches tagged with `next: { tags: ['collection'] }`.
+
+## Client-Side Fetching (Live Data)
+
+Server Components are the default, but for live/user-specific data that doesn't need SEO:
+
+- **SWR / TanStack Query**: PREFERRED over `useEffect`. Handles caching, polling, and deduplication automatically.
+
+  ```tsx
+  'use client';
+  import useSWR from 'swr';
+
+  // Good: "Stale-While-Revalidate" - Fast UI, then updates
+  const { data } = useSWR('/api/user', fetcher);
+  ```
+
+- **Anti-Pattern**: Do not use `useEffect` to fetch data if you can avoid it. It causes "Flash of Loading Content" and waterfalls.
+
+## Anti-Patterns
+
+- **API Routes**: Don't fetch your own API Routes (`/api/...`) from Server Components. Call the DB/Service function directly.

package/rules/nextjs/data-fetching/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# Next.js Data Fetching References
+
+## References
+
+- [**Fetch Patterns**](fetch-patterns.md) - Server fetch, caching, revalidation
+
+## Quick Checks
+
+- [ ] Fetch in Server Components
+- [ ] Use cache() for deduplication
+- [ ] Configure revalidation strategy
+- [ ] Parallel fetching when possible
+- [ ] Handle loading and error states