@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/nextjs/rules/seo.md

@@ -0,0 +1,350 @@
+---
+paths:
+  - "**/layout.tsx"
+  - "**/page.tsx"
+  - "app/sitemap.ts"
+  - "app/robots.ts"
+---
+
+# Next.js SEO
+
+## Metadata API
+
+### Static Metadata
+
+```typescript
+// app/page.tsx
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'Home | My App',
+  description: 'Welcome to my application',
+  keywords: ['next.js', 'react', 'web development'],
+  authors: [{ name: 'John Doe' }],
+  openGraph: {
+    title: 'Home | My App',
+    description: 'Welcome to my application',
+    url: 'https://example.com',
+    siteName: 'My App',
+    images: [
+      {
+        url: 'https://example.com/og-image.png',
+        width: 1200,
+        height: 630,
+        alt: 'My App',
+      },
+    ],
+    locale: 'en_US',
+    type: 'website',
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'Home | My App',
+    description: 'Welcome to my application',
+    images: ['https://example.com/og-image.png'],
+  },
+  robots: {
+    index: true,
+    follow: true,
+  },
+};
+```
+
+### Dynamic Metadata
+
+```typescript
+// app/blog/[slug]/page.tsx
+import type { Metadata } from 'next';
+
+type Props = {
+  params: Promise<{ slug: string }>;
+};
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await getPost(slug);
+
+  return {
+    title: `${post.title} | Blog`,
+    description: post.excerpt,
+    openGraph: {
+      title: post.title,
+      description: post.excerpt,
+      type: 'article',
+      publishedTime: post.publishedAt,
+      authors: [post.author.name],
+      images: [
+        {
+          url: post.featuredImage,
+          width: 1200,
+          height: 630,
+          alt: post.title,
+        },
+      ],
+    },
+  };
+}
+```
+
+### Layout Metadata (Template)
+
+```typescript
+// app/layout.tsx
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  metadataBase: new URL('https://example.com'),
+  title: {
+    template: '%s | My App',
+    default: 'My App',
+  },
+  description: 'My application description',
+};
+
+// Child page: title: 'Blog' → renders as 'Blog | My App'
+```
+
+## Sitemap
+
+```typescript
+// app/sitemap.ts
+import type { MetadataRoute } from 'next';
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const baseUrl = 'https://example.com';
+
+  // Static pages
+  const staticPages = [
+    { url: baseUrl, lastModified: new Date(), changeFrequency: 'daily' as const, priority: 1 },
+    { url: `${baseUrl}/about`, lastModified: new Date(), changeFrequency: 'monthly' as const, priority: 0.8 },
+    { url: `${baseUrl}/contact`, lastModified: new Date(), changeFrequency: 'monthly' as const, priority: 0.5 },
+  ];
+
+  // Dynamic pages
+  const posts = await db.post.findMany({
+    select: { slug: true, updatedAt: true },
+  });
+
+  const postPages = posts.map(post => ({
+    url: `${baseUrl}/blog/${post.slug}`,
+    lastModified: post.updatedAt,
+    changeFrequency: 'weekly' as const,
+    priority: 0.7,
+  }));
+
+  return [...staticPages, ...postPages];
+}
+```
+
+### Large Sitemap (Multiple Files)
+
+```typescript
+// app/sitemap/[id]/route.ts
+import { getPostsBatch } from '@/lib/posts';
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const posts = await getPostsBatch(parseInt(id));
+
+  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
+    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+      ${posts.map(post => `
+        <url>
+          <loc>https://example.com/blog/${post.slug}</loc>
+          <lastmod>${post.updatedAt.toISOString()}</lastmod>
+        </url>
+      `).join('')}
+    </urlset>`;
+
+  return new Response(sitemap, {
+    headers: { 'Content-Type': 'application/xml' },
+  });
+}
+```
+
+## Robots.txt
+
+```typescript
+// app/robots.ts
+import type { MetadataRoute } from 'next';
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      {
+        userAgent: '*',
+        allow: '/',
+        disallow: ['/admin/', '/api/', '/private/'],
+      },
+      {
+        userAgent: 'Googlebot',
+        allow: '/',
+      },
+    ],
+    sitemap: 'https://example.com/sitemap.xml',
+  };
+}
+```
+
+## JSON-LD Structured Data
+
+```typescript
+// components/structured-data.tsx
+export function ArticleJsonLd({
+  title,
+  description,
+  publishedTime,
+  author,
+  image,
+  url,
+}: ArticleJsonLdProps) {
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'Article',
+    headline: title,
+    description,
+    image,
+    datePublished: publishedTime,
+    author: {
+      '@type': 'Person',
+      name: author,
+    },
+    publisher: {
+      '@type': 'Organization',
+      name: 'My App',
+      logo: {
+        '@type': 'ImageObject',
+        url: 'https://example.com/logo.png',
+      },
+    },
+    mainEntityOfPage: url,
+  };
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+    />
+  );
+}
+
+// Usage in page
+export default function BlogPost({ post }) {
+  return (
+    <>
+      <ArticleJsonLd
+        title={post.title}
+        description={post.excerpt}
+        publishedTime={post.publishedAt}
+        author={post.author.name}
+        image={post.featuredImage}
+        url={`https://example.com/blog/${post.slug}`}
+      />
+      <article>...</article>
+    </>
+  );
+}
+```
+
+### Organization Schema
+
+```typescript
+export function OrganizationJsonLd() {
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    name: 'My Company',
+    url: 'https://example.com',
+    logo: 'https://example.com/logo.png',
+    sameAs: [
+      'https://twitter.com/mycompany',
+      'https://linkedin.com/company/mycompany',
+    ],
+    contactPoint: {
+      '@type': 'ContactPoint',
+      telephone: '+1-800-555-1234',
+      contactType: 'customer service',
+    },
+  };
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+    />
+  );
+}
+```
+
+## Canonical URLs
+
+```typescript
+export const metadata: Metadata = {
+  alternates: {
+    canonical: 'https://example.com/page',
+    languages: {
+      'en-US': 'https://example.com/en-US/page',
+      'fr-FR': 'https://example.com/fr-FR/page',
+    },
+  },
+};
+```
+
+## Performance (Core Web Vitals)
+
+```typescript
+// next.config.js
+module.exports = {
+  images: {
+    formats: ['image/avif', 'image/webp'],
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+  },
+  experimental: {
+    optimizeCss: true,
+  },
+};
+
+// Image component
+import Image from 'next/image';
+
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={630}
+  priority // For LCP images
+  placeholder="blur"
+  blurDataURL="data:image/jpeg;base64,..."
+/>
+```
+
+## Anti-patterns
+
+```typescript
+// BAD: Missing metadata
+export default function Page() {
+  return <div>Content</div>;
+}
+
+// GOOD: Always include metadata
+export const metadata: Metadata = {
+  title: 'Page Title',
+  description: 'Page description',
+};
+
+// BAD: Duplicate content without canonical
+// page-1 and page-2 have same content
+
+// GOOD: Set canonical
+export const metadata: Metadata = {
+  alternates: { canonical: '/page-1' },
+};
+
+// BAD: Blocking indexing of important pages
+export const metadata: Metadata = {
+  robots: { index: false }, // Accidentally blocking!
+};
+```

package/configs/nextjs/rules/server-actions.md

@@ -0,0 +1,353 @@
+---
+paths:
+  - "apps/**/app/**/*.tsx"
+  - "apps/**/app/**/*.ts"
+  - "app/**/*.tsx"
+  - "app/**/*.ts"
+  - "**/actions.ts"
+  - "**/actions/*.ts"
+---
+
+# Next.js Server Actions
+
+## Basic Server Action
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+  const content = formData.get('content') as string;
+
+  await db.post.create({ data: { title, content } });
+
+  revalidatePath('/posts');
+}
+```
+
+## With Validation (Zod)
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const CreatePostSchema = z.object({
+  title: z.string().min(1).max(100),
+  content: z.string().min(1),
+});
+
+export async function createPost(formData: FormData) {
+  const parsed = CreatePostSchema.safeParse({
+    title: formData.get('title'),
+    content: formData.get('content'),
+  });
+
+  if (!parsed.success) {
+    return { error: parsed.error.flatten().fieldErrors };
+  }
+
+  await db.post.create({ data: parsed.data });
+  revalidatePath('/posts');
+
+  return { success: true };
+}
+```
+
+## Return Type Pattern
+
+```typescript
+// Type-safe action results
+type ActionResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string; fieldErrors?: Record<string, string[]> };
+
+export async function createUser(formData: FormData): Promise<ActionResult<User>> {
+  const parsed = UserSchema.safeParse(Object.fromEntries(formData));
+
+  if (!parsed.success) {
+    return {
+      success: false,
+      error: 'Validation failed',
+      fieldErrors: parsed.error.flatten().fieldErrors,
+    };
+  }
+
+  try {
+    const user = await db.user.create({ data: parsed.data });
+    revalidatePath('/users');
+    return { success: true, data: user };
+  } catch (error) {
+    return { success: false, error: 'Failed to create user' };
+  }
+}
+```
+
+## useActionState (React 19)
+
+```tsx
+'use client';
+
+import { useActionState } from 'react';
+import { createPost } from './actions';
+
+export function PostForm() {
+  const [state, formAction, isPending] = useActionState(createPost, null);
+
+  return (
+    <form action={formAction}>
+      <input name="title" disabled={isPending} />
+      {state?.fieldErrors?.title && (
+        <span className="error">{state.fieldErrors.title}</span>
+      )}
+
+      <textarea name="content" disabled={isPending} />
+      {state?.fieldErrors?.content && (
+        <span className="error">{state.fieldErrors.content}</span>
+      )}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Post'}
+      </button>
+
+      {state?.error && <div className="error">{state.error}</div>}
+    </form>
+  );
+}
+```
+
+## useOptimistic
+
+```tsx
+'use client';
+
+import { useOptimistic } from 'react';
+import { toggleLike } from './actions';
+
+interface Post {
+  id: string;
+  likes: number;
+  isLiked: boolean;
+}
+
+export function LikeButton({ post }: { post: Post }) {
+  const [optimisticPost, addOptimistic] = useOptimistic(
+    post,
+    (state, newLiked: boolean) => ({
+      ...state,
+      isLiked: newLiked,
+      likes: newLiked ? state.likes + 1 : state.likes - 1,
+    })
+  );
+
+  async function handleClick() {
+    addOptimistic(!optimisticPost.isLiked);
+    await toggleLike(post.id);
+  }
+
+  return (
+    <button onClick={handleClick}>
+      {optimisticPost.isLiked ? '❤️' : '🤍'} {optimisticPost.likes}
+    </button>
+  );
+}
+```
+
+## Revalidation Strategies
+
+```typescript
+'use server';
+
+import { revalidatePath, revalidateTag } from 'next/cache';
+
+export async function createPost(data: PostData) {
+  await db.post.create({ data });
+
+  // Revalidate specific path
+  revalidatePath('/posts');
+
+  // Revalidate dynamic path
+  revalidatePath(`/posts/${data.slug}`);
+
+  // Revalidate layout (all child pages)
+  revalidatePath('/posts', 'layout');
+
+  // Revalidate by cache tag
+  revalidateTag('posts');
+}
+
+// In data fetching, use tags
+async function getPosts() {
+  return fetch('/api/posts', {
+    next: { tags: ['posts'] },
+  });
+}
+```
+
+## Redirect After Action
+
+```typescript
+'use server';
+
+import { redirect } from 'next/navigation';
+
+export async function createPost(formData: FormData) {
+  const post = await db.post.create({
+    data: {
+      title: formData.get('title') as string,
+      content: formData.get('content') as string,
+    },
+  });
+
+  redirect(`/posts/${post.slug}`);
+}
+```
+
+## With Authentication
+
+```typescript
+'use server';
+
+import { auth } from '@/lib/auth';
+import { redirect } from 'next/navigation';
+
+export async function createPost(formData: FormData) {
+  const session = await auth();
+
+  if (!session?.user) {
+    redirect('/login');
+  }
+
+  await db.post.create({
+    data: {
+      title: formData.get('title') as string,
+      content: formData.get('content') as string,
+      authorId: session.user.id,
+    },
+  });
+
+  revalidatePath('/posts');
+}
+```
+
+## File Upload
+
+```typescript
+'use server';
+
+export async function uploadFile(formData: FormData) {
+  const file = formData.get('file') as File;
+
+  if (!file || file.size === 0) {
+    return { error: 'No file provided' };
+  }
+
+  // Validate file type
+  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
+  if (!allowedTypes.includes(file.type)) {
+    return { error: 'Invalid file type' };
+  }
+
+  // Validate file size (5MB)
+  if (file.size > 5 * 1024 * 1024) {
+    return { error: 'File too large' };
+  }
+
+  const bytes = await file.arrayBuffer();
+  const buffer = Buffer.from(bytes);
+
+  // Save to storage (S3, local, etc.)
+  const url = await uploadToStorage(buffer, file.name);
+
+  return { success: true, url };
+}
+```
+
+## Progressive Enhancement
+
+```tsx
+// Works without JavaScript (form submits normally)
+// Enhanced with JavaScript (no page reload)
+
+export function ContactForm() {
+  return (
+    <form action={sendMessage}>
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+## Error Handling
+
+```typescript
+'use server';
+
+export async function riskyAction(formData: FormData) {
+  try {
+    await someRiskyOperation();
+    return { success: true };
+  } catch (error) {
+    // Log server-side
+    console.error('Action failed:', error);
+
+    // Return safe error to client
+    if (error instanceof KnownError) {
+      return { success: false, error: error.message };
+    }
+
+    return { success: false, error: 'An unexpected error occurred' };
+  }
+}
+```
+
+## Binding Arguments
+
+```tsx
+// Pass additional data to action
+import { updatePost } from './actions';
+
+export function EditButton({ postId }: { postId: string }) {
+  const updateWithId = updatePost.bind(null, postId);
+
+  return (
+    <form action={updateWithId}>
+      <input name="title" />
+      <button type="submit">Update</button>
+    </form>
+  );
+}
+
+// actions.ts
+'use server';
+
+export async function updatePost(postId: string, formData: FormData) {
+  const title = formData.get('title') as string;
+  await db.post.update({ where: { id: postId }, data: { title } });
+}
+```
+
+## Non-Form Usage
+
+```tsx
+'use client';
+
+import { deletePost } from './actions';
+
+export function DeleteButton({ postId }: { postId: string }) {
+  async function handleDelete() {
+    if (confirm('Are you sure?')) {
+      await deletePost(postId);
+    }
+  }
+
+  return <button onClick={handleDelete}>Delete</button>;
+}
+```