@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/nextjs/rules/middleware.md

@@ -0,0 +1,303 @@
+---
+paths:
+  - "middleware.ts"
+  - "src/middleware.ts"
+---
+
+# Next.js Middleware
+
+## Basic Structure
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  // Runs on every matched request
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    // Match all paths except static files
+    '/((?!_next/static|_next/image|favicon.ico).*)',
+  ],
+};
+```
+
+## Common Patterns
+
+### Authentication
+
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { getToken } from 'next-auth/jwt';
+
+export async function middleware(request: NextRequest) {
+  const token = await getToken({ req: request });
+  const { pathname } = request.nextUrl;
+
+  // Public paths
+  const publicPaths = ['/login', '/register', '/api/auth'];
+  if (publicPaths.some(path => pathname.startsWith(path))) {
+    return NextResponse.next();
+  }
+
+  // Protected paths
+  if (!token) {
+    const loginUrl = new URL('/login', request.url);
+    loginUrl.searchParams.set('callbackUrl', pathname);
+    return NextResponse.redirect(loginUrl);
+  }
+
+  return NextResponse.next();
+}
+```
+
+### Role-Based Access
+
+```typescript
+export async function middleware(request: NextRequest) {
+  const token = await getToken({ req: request });
+  const { pathname } = request.nextUrl;
+
+  // Admin routes
+  if (pathname.startsWith('/admin')) {
+    if (token?.role !== 'admin') {
+      return NextResponse.redirect(new URL('/forbidden', request.url));
+    }
+  }
+
+  // API admin routes
+  if (pathname.startsWith('/api/admin')) {
+    if (token?.role !== 'admin') {
+      return NextResponse.json(
+        { error: 'Forbidden' },
+        { status: 403 }
+      );
+    }
+  }
+
+  return NextResponse.next();
+}
+```
+
+### Internationalization (i18n)
+
+```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', 'fr', 'de'];
+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 pathname has locale
+  const pathnameHasLocale = locales.some(
+    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
+  );
+
+  if (pathnameHasLocale) return NextResponse.next();
+
+  // Redirect to locale
+  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).*)'],
+};
+```
+
+### Rate Limiting
+
+```typescript
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'),
+});
+
+export async function middleware(request: NextRequest) {
+  if (request.nextUrl.pathname.startsWith('/api')) {
+    const ip = request.ip ?? '127.0.0.1';
+    const { success, limit, remaining, reset } = await ratelimit.limit(ip);
+
+    if (!success) {
+      return NextResponse.json(
+        { error: 'Too many requests' },
+        {
+          status: 429,
+          headers: {
+            'X-RateLimit-Limit': limit.toString(),
+            'X-RateLimit-Remaining': remaining.toString(),
+            'X-RateLimit-Reset': reset.toString(),
+          },
+        }
+      );
+    }
+  }
+
+  return NextResponse.next();
+}
+```
+
+### Geolocation Redirect
+
+```typescript
+export function middleware(request: NextRequest) {
+  const country = request.geo?.country || 'US';
+
+  // Redirect EU users to EU subdomain
+  const euCountries = ['DE', 'FR', 'IT', 'ES', 'NL'];
+  if (euCountries.includes(country) && !request.nextUrl.hostname.includes('eu.')) {
+    return NextResponse.redirect(
+      new URL(request.nextUrl.pathname, 'https://eu.example.com')
+    );
+  }
+
+  return NextResponse.next();
+}
+```
+
+### Security Headers
+
+```typescript
+export function middleware(request: NextRequest) {
+  const response = NextResponse.next();
+
+  // Security headers
+  response.headers.set('X-Frame-Options', 'DENY');
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  response.headers.set(
+    'Content-Security-Policy',
+    "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline';"
+  );
+  response.headers.set(
+    'Permissions-Policy',
+    'camera=(), microphone=(), geolocation=()'
+  );
+
+  return response;
+}
+```
+
+### Request/Response Modification
+
+```typescript
+export function middleware(request: NextRequest) {
+  // Add custom header to request
+  const requestHeaders = new Headers(request.headers);
+  requestHeaders.set('x-request-id', crypto.randomUUID());
+
+  // Rewrite URL
+  if (request.nextUrl.pathname === '/old-path') {
+    return NextResponse.rewrite(new URL('/new-path', request.url));
+  }
+
+  // Pass headers to server components
+  const response = NextResponse.next({
+    request: {
+      headers: requestHeaders,
+    },
+  });
+
+  // Add header to response
+  response.headers.set('x-request-id', requestHeaders.get('x-request-id')!);
+
+  return response;
+}
+```
+
+### A/B Testing
+
+```typescript
+export function middleware(request: NextRequest) {
+  const bucket = request.cookies.get('ab-bucket')?.value;
+
+  if (!bucket) {
+    // Assign to bucket
+    const newBucket = Math.random() > 0.5 ? 'a' : 'b';
+    const response = NextResponse.next();
+    response.cookies.set('ab-bucket', newBucket, {
+      httpOnly: true,
+      maxAge: 60 * 60 * 24 * 30, // 30 days
+    });
+    return response;
+  }
+
+  // Rewrite based on bucket
+  if (request.nextUrl.pathname === '/landing') {
+    return NextResponse.rewrite(
+      new URL(`/landing-${bucket}`, request.url)
+    );
+  }
+
+  return NextResponse.next();
+}
+```
+
+## Matcher Patterns
+
+```typescript
+export const config = {
+  matcher: [
+    // Match all paths except static
+    '/((?!_next/static|_next/image|favicon.ico).*)',
+
+    // Match specific paths
+    '/dashboard/:path*',
+    '/api/:path*',
+
+    // Match with regex
+    '/(api|admin)/:path*',
+
+    // Exclude specific paths
+    '/((?!api/public)api/:path*)',
+  ],
+};
+```
+
+## Anti-patterns
+
+```typescript
+// BAD: Heavy computation in middleware (runs on every request)
+export async function middleware(request: NextRequest) {
+  await heavyDatabaseQuery(); // Blocks all requests!
+}
+
+// GOOD: Keep middleware lightweight
+export async function middleware(request: NextRequest) {
+  // Only quick checks, use Edge-compatible code
+}
+
+// BAD: Using Node.js APIs (middleware runs on Edge)
+import fs from 'fs'; // Won't work!
+
+// GOOD: Use Edge-compatible APIs
+import { Redis } from '@upstash/redis'; // Edge-compatible
+
+// BAD: Modifying response body
+return new Response('Modified body'); // Loses Next.js features
+
+// GOOD: Use rewrite or redirect
+return NextResponse.rewrite(new URL('/new-path', request.url));
+```

package/configs/nextjs/rules/routing.md

@@ -0,0 +1,324 @@
+---
+paths:
+  - "apps/**/app/**/*.tsx"
+  - "app/**/*.tsx"
+---
+
+# Next.js App Router Patterns
+
+## Route Structure
+
+```
+app/
+├── page.tsx                    # / (home)
+├── layout.tsx                  # Root layout
+├── loading.tsx                 # Root loading
+├── error.tsx                   # Root error boundary
+├── not-found.tsx               # 404 page
+│
+├── (marketing)/                # Route group (not in URL)
+│   ├── layout.tsx              # Shared marketing layout
+│   ├── about/page.tsx          # /about
+│   └── pricing/page.tsx        # /pricing
+│
+├── (app)/                      # Route group for app
+│   ├── layout.tsx              # App layout (with auth)
+│   ├── dashboard/page.tsx      # /dashboard
+│   └── settings/page.tsx       # /settings
+│
+├── blog/
+│   ├── page.tsx                # /blog
+│   └── [slug]/                 # Dynamic segment
+│       ├── page.tsx            # /blog/my-post
+│       └── opengraph-image.tsx # OG image generation
+│
+├── docs/
+│   └── [...slug]/              # Catch-all segment
+│       └── page.tsx            # /docs/a/b/c
+│
+└── api/                        # API routes
+    └── webhooks/
+        └── stripe/route.ts     # /api/webhooks/stripe
+```
+
+## Dynamic Routes
+
+```tsx
+// app/blog/[slug]/page.tsx
+interface Props {
+  params: Promise<{ slug: string }>;
+}
+
+export default async function BlogPost({ params }: Props) {
+  const { slug } = await params;
+  const post = await getPost(slug);
+
+  if (!post) {
+    notFound();
+  }
+
+  return <article>{post.content}</article>;
+}
+
+// Generate static params for SSG
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+```
+
+## Catch-All Routes
+
+```tsx
+// app/docs/[...slug]/page.tsx
+interface Props {
+  params: Promise<{ slug: string[] }>;
+}
+
+export default async function DocsPage({ params }: Props) {
+  const { slug } = await params;
+  // slug = ['guide', 'getting-started'] for /docs/guide/getting-started
+
+  const path = slug.join('/');
+  const doc = await getDoc(path);
+
+  return <DocContent doc={doc} />;
+}
+```
+
+## Route Groups
+
+```tsx
+// (marketing) and (app) don't appear in URL
+// but allow different layouts
+
+// app/(marketing)/layout.tsx
+export default function MarketingLayout({ children }) {
+  return (
+    <>
+      <MarketingNav />
+      <main>{children}</main>
+      <Footer />
+    </>
+  );
+}
+
+// app/(app)/layout.tsx
+export default function AppLayout({ children }) {
+  return (
+    <>
+      <Sidebar />
+      <main>{children}</main>
+    </>
+  );
+}
+```
+
+## Parallel Routes
+
+```tsx
+// app/layout.tsx with slots
+export default function Layout({
+  children,
+  modal,     // @modal slot
+  analytics, // @analytics slot
+}: {
+  children: React.ReactNode;
+  modal: React.ReactNode;
+  analytics: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        {children}
+        {modal}
+        {analytics}
+      </body>
+    </html>
+  );
+}
+
+// app/@modal/login/page.tsx - Intercepted modal
+// app/@analytics/page.tsx - Analytics slot
+```
+
+## Intercepting Routes
+
+```tsx
+// Intercept /photo/123 when navigating from gallery
+// app/gallery/@modal/(.)photo/[id]/page.tsx
+
+// (.) - Same level
+// (..) - One level up
+// (..)(..) - Two levels up
+// (...) - Root
+
+export default function PhotoModal({ params }: { params: Promise<{ id: string }> }) {
+  return (
+    <Modal>
+      <Photo id={(await params).id} />
+    </Modal>
+  );
+}
+```
+
+## Navigation
+
+```tsx
+import Link from 'next/link';
+import { useRouter, usePathname, useSearchParams } from 'next/navigation';
+
+// Declarative navigation
+<Link href="/blog/my-post">Read Post</Link>
+<Link href={{ pathname: '/blog', query: { sort: 'date' } }}>Blog</Link>
+
+// Prefetch on hover (default)
+<Link href="/dashboard" prefetch={true}>Dashboard</Link>
+
+// No prefetch
+<Link href="/admin" prefetch={false}>Admin</Link>
+
+// Programmatic navigation
+function NavigationExample() {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  function navigate() {
+    router.push('/dashboard');
+    router.replace('/login');  // No history entry
+    router.back();
+    router.forward();
+    router.refresh();          // Re-fetch server components
+  }
+
+  // Current URL info
+  console.log(pathname);                    // /blog
+  console.log(searchParams.get('page'));    // 1
+}
+```
+
+## Middleware
+
+```typescript
+// middleware.ts (root level)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Auth check
+  const token = request.cookies.get('token');
+  if (pathname.startsWith('/dashboard') && !token) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  // Rewrite
+  if (pathname.startsWith('/api/v1')) {
+    return NextResponse.rewrite(new URL('/api/v2' + pathname.slice(7), request.url));
+  }
+
+  // Add headers
+  const response = NextResponse.next();
+  response.headers.set('x-custom-header', 'value');
+  return response;
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+## Metadata
+
+```tsx
+// Static metadata
+export const metadata = {
+  title: 'My Blog',
+  description: 'A blog about things',
+};
+
+// Dynamic metadata
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await getPost(slug);
+
+  return {
+    title: post.title,
+    description: post.excerpt,
+    openGraph: {
+      title: post.title,
+      images: [post.image],
+    },
+  };
+}
+```
+
+## Route Handlers (API)
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const page = searchParams.get('page') || '1';
+
+  const users = await getUsers({ page: parseInt(page) });
+  return NextResponse.json(users);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const user = await createUser(body);
+  return NextResponse.json(user, { status: 201 });
+}
+
+// app/api/users/[id]/route.ts
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const user = await getUser(id);
+
+  if (!user) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+
+  return NextResponse.json(user);
+}
+```
+
+## Loading & Error Boundaries
+
+```tsx
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return <DashboardSkeleton />;
+}
+
+// app/dashboard/error.tsx
+'use client';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+
+// app/dashboard/not-found.tsx
+export default function NotFound() {
+  return <div>Dashboard not found</div>;
+}
+```