@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/nextjs/data-fetching/references/fetch-patterns.md

@@ -0,0 +1,160 @@
+# Next.js Fetch Patterns
+
+## Basic Fetching
+
+```tsx
+// Server Component - direct fetch
+async function UserProfile({ id }: { id: string }) {
+  const user = await fetch(`https://api.example.com/users/${id}`);
+  const data = await user.json();
+  return <div>{data.name}</div>;
+}
+
+// With error handling
+async function getData() {
+  const res = await fetch('https://api.example.com/data');
+  if (!res.ok) {
+    throw new Error('Failed to fetch');
+  }
+  return res.json();
+}
+```
+
+## Caching & Revalidation
+
+```tsx
+// Cache forever (default)
+fetch('https://api.example.com/data');
+
+// No cache
+fetch('https://api.example.com/data', { cache: 'no-store' });
+
+// Revalidate after 60 seconds
+fetch('https://api.example.com/data', { next: { revalidate: 60 } });
+
+// Revalidate on demand with tags
+fetch('https://api.example.com/posts', { next: { tags: ['posts'] } });
+
+// Trigger revalidation (Server Action or Route Handler)
+import { revalidateTag, revalidatePath } from 'next/cache';
+revalidateTag('posts');
+revalidatePath('/blog');
+```
+
+## Page-Level Caching
+
+```tsx
+// Force dynamic rendering
+export const dynamic = 'force-dynamic';
+
+// Force static rendering
+export const dynamic = 'force-static';
+
+// Revalidate every 60 seconds
+export const revalidate = 60;
+
+// Disable caching
+export const revalidate = 0;
+```
+
+## Parallel Fetching
+
+```tsx
+// ✅ Good - parallel fetches
+async function Dashboard() {
+  const [user, posts, analytics] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getAnalytics(),
+  ]);
+  
+  return (
+    <div>
+      <UserCard user={user} />
+      <PostsList posts={posts} />
+      <Analytics data={analytics} />
+    </div>
+  );
+}
+
+// ❌ Bad - sequential (waterfall)
+async function Dashboard() {
+  const user = await getUser();
+  const posts = await getPosts();
+  const analytics = await getAnalytics();
+  // ...
+}
+```
+
+## Request Deduplication
+
+```tsx
+import { cache } from 'react';
+
+// Deduplicated across components in same request
+export const getUser = cache(async (id: string) => {
+  const res = await fetch(`https://api.example.com/users/${id}`);
+  return res.json();
+});
+
+// Multiple components can call getUser(id)
+// Only one request is made
+async function UserName({ id }: { id: string }) {
+  const user = await getUser(id);
+  return <span>{user.name}</span>;
+}
+
+async function UserEmail({ id }: { id: string }) {
+  const user = await getUser(id);
+  return <span>{user.email}</span>;
+}
+```
+
+## Database Queries
+
+```tsx
+import { unstable_cache } from 'next/cache';
+
+// Cache database queries
+const getCachedUser = unstable_cache(
+  async (id: string) => {
+    return db.user.findUnique({ where: { id } });
+  },
+  ['user-cache'],
+  { revalidate: 3600, tags: ['users'] }
+);
+
+// Usage
+async function UserProfile({ id }: { id: string }) {
+  const user = await getCachedUser(id);
+  return <Profile user={user} />;
+}
+```
+
+## Streaming
+
+```tsx
+import { Suspense } from 'react';
+
+// Stream slow data
+async function Page() {
+  // Fast data renders immediately
+  const quickData = await getQuickData();
+  
+  return (
+    <div>
+      <h1>{quickData.title}</h1>
+      
+      {/* Slow data streams in */}
+      <Suspense fallback={<Loading />}>
+        <SlowComponent />
+      </Suspense>
+    </div>
+  );
+}
+
+async function SlowComponent() {
+  const slowData = await getSlowData();
+  return <div>{slowData.content}</div>;
+}
+```

package/rules/nextjs/internationalization/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: Next.js Internationalization (i18n)
+description: Best practices for multi-language handling, locale routing, and detection middleware.
+metadata:
+  labels: [nextjs, i18n, middleware, routing]
+  triggers:
+    files: ['middleware.ts', 'app/[lang]/**', 'messages/*.json']
+    keywords: [i18n, locale, translation, next-intl, redirect]
+---
+
+# Internationalization (i18n)
+
+## **Priority: P2 (MEDIUM)**
+
+Use Sub-path Routing (`/en`, `/de`) and Server Components for translations.
+
+## Principles
+
+1. **Sub-path Routing**: Use URL segments (e.g., `app/[lang]/page.tsx`) to manage locales.
+   - _Why_: SEO friendly, sharable, and cacheable.
+2. **Server-Side Translation**: Load dictionary files (`en.json`) in Server Components.
+   - _Why_: Reduces client bundle size. No huge JSON blobs sent to browser.
+3. **Middleware Detection**: Use `middleware.ts` to detect `Accept-Language` headers and redirect users to their preferred locale.
+4. **Type Safety**: Use robust typing for translation keys to prevent broken text UI.
+
+## Implementation Pattern
+
+### 1. Directory Structure
+
+```text
+app/
+├── [lang]/             # Dynamic Locale Segment
+│   ├── layout.tsx      # <html lang={params.lang}>
+│   └── page.tsx
+└── api/
+messages/               # Translation Dictionaries
+├── en.json
+└── es.json
+middleware.ts           # Locale Redirection
+```
+
+### 2. Middleware (`middleware.ts`)
+
+Redirect root traffic (`/`) to localized traffic (`/en`).
+
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { match } from '@formatjs/intl-localematcher';
+import Negotiator from 'negotiator';
+
+const LOCALES = ['en', 'es', 'fr'];
+const DEFAULT = 'en';
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // 1. Check if path already has locale
+  const pathnameHasLocale = LOCALES.some(
+    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`,
+  );
+  if (pathnameHasLocale) return;
+
+  // 2. Detect locale (Header matching)
+  const headers = {
+    'accept-language': request.headers.get('accept-language') || '',
+  };
+  const languages = new Negotiator({ headers }).languages();
+  const locale = match(languages, LOCALES, DEFAULT);
+
+  // 3. Redirect
+  request.nextUrl.pathname = `/${locale}${pathname}`;
+  return NextResponse.redirect(request.nextUrl);
+}
+
+export const config = {
+  matcher: ['/((?!_next|api|static|favicon.ico).*)'],
+};
+```
+
+### 3. Server Component Usage
+
+```typescript
+// app/[lang]/page.tsx
+
+// 1. Dynamic Params ensure static generation works for each language
+export async function generateStaticParams() {
+  return [{ lang: 'en' }, { lang: 'es' }];
+}
+
+export default async function Page({ params: { lang } }) {
+  // 2. Load Dictionary On Demand
+  const dict = await getDictionary(lang);
+
+  return <h1>{dict.home.title}</h1>;
+}
+```
+
+## Redirect Handling Strategy
+
+When handling redirects (Authentication, Legacy URLs) in an i18n app:
+
+- **Always preserve locale**: Use `redirect(`/${lang}/login`)` instead of just `/login`.
+- **Server Actions**: Return `redirect(...)` from actions.
+- **Next Config**: Use `next.config.js` for legacy SEO 301s (e.g., old-site `/about-us` -> `/en/about`).

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

@@ -0,0 +1,13 @@
+# Next.js Internationalization References
+
+## References
+
+- [**i18n Patterns**](i18n-patterns.md) - Routing, translations, locale detection
+
+## Quick Checks
+
+- [ ] Configure supported locales in next.config
+- [ ] Use dynamic route segments for locale
+- [ ] Implement locale detection middleware
+- [ ] Load translations efficiently
+- [ ] Handle RTL languages properly

package/rules/nextjs/internationalization/references/i18n-patterns.md

@@ -0,0 +1,180 @@
+# Next.js Internationalization Patterns
+
+## App Router i18n Setup
+
+```typescript
+// middleware.ts
+import { NextRequest, NextResponse } from 'next/server';
+import Negotiator from 'negotiator';
+import { match } from '@formatjs/intl-localematcher';
+
+const locales = ['en', 'vi', 'ja'];
+const defaultLocale = 'en';
+
+function getLocale(request: NextRequest): string {
+  const headers = { 'accept-language': request.headers.get('accept-language') || '' };
+  const languages = new Negotiator({ headers }).languages();
+  return match(languages, locales, defaultLocale);
+}
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Check if locale is in pathname
+  const pathnameHasLocale = locales.some(
+    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
+  );
+
+  if (pathnameHasLocale) return;
+
+  // Redirect to locale path
+  const locale = getLocale(request);
+  request.nextUrl.pathname = `/${locale}${pathname}`;
+  return NextResponse.redirect(request.nextUrl);
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
+```
+
+## Directory Structure
+
+```
+app/
+├── [locale]/
+│   ├── layout.tsx
+│   ├── page.tsx
+│   └── about/
+│       └── page.tsx
+└── dictionaries/
+    ├── en.json
+    ├── vi.json
+    └── ja.json
+```
+
+## Dictionary Loading
+
+```typescript
+// dictionaries.ts
+const dictionaries = {
+  en: () => import('./dictionaries/en.json').then((m) => m.default),
+  vi: () => import('./dictionaries/vi.json').then((m) => m.default),
+  ja: () => import('./dictionaries/ja.json').then((m) => m.default),
+};
+
+export const getDictionary = async (locale: string) => {
+  return dictionaries[locale]?.() ?? dictionaries.en();
+};
+
+// app/[locale]/page.tsx
+export default async function Page({ params: { locale } }) {
+  const dict = await getDictionary(locale);
+
+  return (
+    <main>
+      <h1>{dict.home.title}</h1>
+      <p>{dict.home.description}</p>
+    </main>
+  );
+}
+```
+
+## Dictionary File
+
+```json
+// dictionaries/en.json
+{
+  "home": {
+    "title": "Welcome",
+    "description": "This is the home page"
+  },
+  "nav": {
+    "about": "About",
+    "contact": "Contact"
+  },
+  "common": {
+    "loading": "Loading...",
+    "error": "Something went wrong"
+  }
+}
+```
+
+## Layout with Locale
+
+```typescript
+// app/[locale]/layout.tsx
+import { getDictionary } from '../dictionaries';
+
+export async function generateStaticParams() {
+  return [{ locale: 'en' }, { locale: 'vi' }, { locale: 'ja' }];
+}
+
+export default async function LocaleLayout({
+  children,
+  params: { locale },
+}: {
+  children: React.ReactNode;
+  params: { locale: string };
+}) {
+  const dict = await getDictionary(locale);
+
+  return (
+    <html lang={locale} dir={locale === 'ar' ? 'rtl' : 'ltr'}>
+      <body>
+        <nav>
+          <a href={`/${locale}`}>{dict.nav.home}</a>
+          <a href={`/${locale}/about`}>{dict.nav.about}</a>
+          <LocaleSwitcher locale={locale} />
+        </nav>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+## Locale Switcher
+
+```typescript
+'use client';
+
+import { usePathname, useRouter } from 'next/navigation';
+
+export function LocaleSwitcher({ locale }: { locale: string }) {
+  const pathname = usePathname();
+  const router = useRouter();
+
+  const switchLocale = (newLocale: string) => {
+    const newPath = pathname.replace(`/${locale}`, `/${newLocale}`);
+    router.push(newPath);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => switchLocale(e.target.value)}>
+      <option value="en">English</option>
+      <option value="vi">Tiếng Việt</option>
+      <option value="ja">日本語</option>
+    </select>
+  );
+}
+```
+
+## next-intl Integration
+
+```typescript
+// For more advanced i18n, use next-intl
+import { useTranslations } from 'next-intl';
+
+export default function HomePage() {
+  const t = useTranslations('home');
+
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      <p>{t('greeting', { name: 'World' })}</p>
+      <p>{t('items', { count: 5 })}</p>
+    </div>
+  );
+}
+```

package/rules/nextjs/optimization/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: Next.js Optimization
+description: Image, Font, Script, and Metadata optimization strategies.
+metadata:
+  labels: [nextjs, optimization, seo, performance]
+  triggers:
+    files: ['**/layout.tsx', '**/page.tsx']
+    keywords: [next/image, next/font, metadata, generateMetadata]
+---
+
+# Optimization
+
+## **Priority: P1 (HIGH)**
+
+Core optimization primitives provided by Next.js. **Monitor First, Optimize Later.**
+
+## Monitoring (Core Web Vitals)
+
+Before applying optimizations, identify bottlenecks using:
+
+- **LCP (Largest Contentful Paint)**: Initial load speed. Target < 2.5s.
+- **CLS (Cumulative Layout Shift)**: Visual stability. Target < 0.1.
+- **INP (Interaction to Next Paint)**: Responsiveness. Target < 200ms.
+- **Tools**: Chrome DevTools "Performance" tab, `next/speed-insights`, or `React Profiler`.
+
+## Images (`next/image`)
+
+- **Component**: `<Image src="..." alt="..." width={500} height={300} />`.
+- **Features**: Automatic resizing, lazy loading, format conversion (WebP/AVIF), and CLS prevention (placeholder sizing).
+- **Remote**: Must configure `images.remotePatterns` in `next.config.js` for external URLs.
+
+## Fonts (`next/font`)
+
+- **Local**: `localFont({ src: ... })`.
+- **Google**: `Inter({ subsets: ['latin'] })`.
+- **Why**: Self-hosts fonts at build time. Zero Layout Shift.
+
+## Metadata (SEO)
+
+- **Static**: Export `metadata` object from `layout.tsx` or `page.tsx`.
+
+  ```tsx
+  export const metadata: Metadata = {
+    title: 'Dashboard',
+    description: '...',
+  };
+  ```
+
+- **Dynamic**: Export `generateMetadata({ params })` function.
+
+  ```tsx
+  export async function generateMetadata({ params }) {
+    const product = await getProduct(params.id);
+    return { title: product.name };
+  }
+  ```
+
+- **Open Graph**: Use `openGraph` key for social cards.
+
+## Scripts (`next/script`)
+
+- **Loading Strategy**: Control when 3rd party scripts load.
+  - `strategy="afterInteractive"` (Default): Google Analytics.
+  - `strategy="lazyOnload"`: Chat widgets, low priority.

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

@@ -0,0 +1,13 @@
+# Next.js Optimization References
+
+## References
+
+- [**Optimization Patterns**](optimization-patterns.md) - Images, fonts, scripts, bundle
+
+## Quick Checks
+
+- [ ] Use next/image for automatic optimization
+- [ ] Use next/font for font optimization
+- [ ] Use next/script for third-party scripts
+- [ ] Implement code splitting
+- [ ] Analyze bundle with @next/bundle-analyzer