npm - @balazsbarta/mp-skills - Versions diffs - 0.1.0 - Mend

@balazsbarta/mp-skills 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/.agents/skills/next-js/references/app-router.md ADDED Viewed

@@ -0,0 +1,206 @@
+# App Router
+Next.js App Router file conventions, layouts, pages, and special files.
+## When to use this reference
+- Creating pages and layouts with the App Router
+- Understanding file conventions (loading, error, not-found)
+- Working with dynamic routes and route groups
+## File conventions
+| File | Purpose | Required |
+| --- | --- | --- |
+| `layout.tsx` | Shared layout (persists across navigations) | Root only |
+| `page.tsx` | Unique page content | Yes (for routes) |
+| `loading.tsx` | Loading UI (Suspense boundary) | No |
+| `error.tsx` | Error boundary | No |
+| `not-found.tsx` | 404 page | No |
+| `template.tsx` | Re-renders on navigation (no persist) | No |
+| `default.tsx` | Parallel route fallback | No |
+## Pages
+```typescript
+// app/page.tsx — Home page at /
+export default function HomePage() {
+  return <h1>Home</h1>;
+}
+```
+### Server Component (default)
+Pages are Server Components by default — they can fetch data directly:
+```typescript
+// app/users/page.tsx
+async function getUsers() {
+  const res = await fetch('https://api.example.com/users');
+  return res.json();
+}
+export default async function UsersPage() {
+  const users = await getUsers();
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+## Layouts
+```typescript
+// app/layout.tsx — Root layout
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <nav>Navigation</nav>
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}
+```
+### Nested layouts
+```typescript
+// app/dashboard/layout.tsx — Dashboard layout
+export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex">
+      <aside>Sidebar</aside>
+      <section>{children}</section>
+    </div>
+  );
+}
+```
+## Dynamic routes
+```typescript
+// app/blog/[slug]/page.tsx
+export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  return <h1>Post: {slug}</h1>;
+}
+```
+### Catch-all routes
+```typescript
+// app/docs/[...slug]/page.tsx — matches /docs/a, /docs/a/b, etc.
+export default async function DocsPage({ params }: { params: Promise<{ slug: string[] }> }) {
+  const { slug } = await params;
+  return <h1>Docs: {slug.join('/')}</h1>;
+}
+```
+## Route groups
+Organize routes without affecting the URL:
+```
+app/
+├── (marketing)/
+│   ├── layout.tsx      # Marketing layout
+│   ├── page.tsx        # / (home)
+│   └── about/page.tsx  # /about
+├── (app)/
+│   ├── layout.tsx      # App layout (different from marketing)
+│   └── dashboard/page.tsx  # /dashboard
+```
+## Loading and error states
+### Loading
+```typescript
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return <div>Loading dashboard...</div>;
+}
+```
+### Error boundary
+```typescript
+// app/dashboard/error.tsx
+'use client'; // Error boundaries must be Client Components
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+### Not found
+```typescript
+// app/not-found.tsx
+export default function NotFound() {
+  return <h1>404 — Page Not Found</h1>;
+}
+```
+## Static generation with generateStaticParams
+```typescript
+// app/blog/[slug]/page.tsx
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+```
+## Parallel routes
+```
+app/
+├── @analytics/page.tsx
+├── @team/page.tsx
+└── layout.tsx
+```
+```typescript
+// app/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  team: React.ReactNode;
+}) {
+  return (
+    <>
+      {children}
+      {analytics}
+      {team}
+    </>
+  );
+}
+```
+## Troubleshooting
+### Page not rendering
+- Ensure file is named `page.tsx` (not `Page.tsx` or `index.tsx`)
+- Check that the directory structure matches the desired URL
+### Layout not applying
+- Layouts only apply to child routes, not sibling routes
+- Root layout must include `<html>` and `<body>` tags

package/.agents/skills/next-js/references/caching-revalidation.md ADDED Viewed

@@ -0,0 +1,211 @@
+# Caching and Revalidation
+Next.js caching layers and revalidation strategies.
+## When to use this reference
+- Understanding how Next.js caches data and pages
+- Configuring revalidation (ISR, on-demand)
+- Debugging caching behavior
+- Opting out of caching
+## Caching layers
+| Layer | What | Where | Default |
+| --- | --- | --- | --- |
+| Request Memoization | `fetch` deduplication | Server (per request) | On |
+| Data Cache | `fetch` responses | Server (persistent) | Check version |
+| Full Route Cache | Rendered HTML + RSC payload | Server (persistent) | Static routes |
+| Router Cache | RSC payload | Client (session) | On |
+**Important:** Caching defaults changed in Next.js 15. Check your version.
+## fetch caching
+### Next.js 14 (cached by default)
+```typescript
+// Cached by default
+const res = await fetch('https://api.example.com/data');
+// Opt out of cache
+const res = await fetch('https://api.example.com/data', { cache: 'no-store' });
+```
+### Next.js 15+ (not cached by default)
+```typescript
+// NOT cached by default
+const res = await fetch('https://api.example.com/data');
+// Opt into cache
+const res = await fetch('https://api.example.com/data', { cache: 'force-cache' });
+```
+## Time-based revalidation (ISR)
+```typescript
+// Revalidate every 60 seconds
+const res = await fetch('https://api.example.com/data', {
+  next: { revalidate: 60 },
+});
+```
+### Page-level revalidation
+```typescript
+// app/blog/page.tsx
+export const revalidate = 60; // Revalidate this page every 60 seconds
+```
+## On-demand revalidation
+### By path
+```typescript
+// app/api/revalidate/route.ts
+import { revalidatePath } from 'next/cache';
+import { NextRequest, NextResponse } from 'next/server';
+export async function POST(request: NextRequest) {
+  const { path } = await request.json();
+  revalidatePath(path);
+  return NextResponse.json({ revalidated: true });
+}
+```
+### By tag
+```typescript
+// Fetch with tag
+const res = await fetch('https://api.example.com/posts', {
+  next: { tags: ['posts'] },
+});
+// Revalidate by tag
+import { revalidateTag } from 'next/cache';
+revalidateTag('posts');
+```
+## Route segment config
+```typescript
+// Force static (default for pages without dynamic data)
+export const dynamic = 'auto';
+// Force dynamic (disable caching)
+export const dynamic = 'force-dynamic';
+// Force static generation (error if dynamic features used)
+export const dynamic = 'force-static';
+// Error if dynamic features used
+export const dynamic = 'error';
+// Set revalidation period
+export const revalidate = 60; // seconds
+// Set runtime
+export const runtime = 'nodejs'; // or 'edge'
+```
+## `unstable_cache` (for non-fetch data)
+Cache data that doesn't come from `fetch`:
+```typescript
+import { unstable_cache } from 'next/cache';
+const getCachedUser = unstable_cache(
+  async (id: string) => {
+    return db.user.findUnique({ where: { id } });
+  },
+  ['user'], // cache key prefix
+  {
+    revalidate: 3600, // 1 hour
+    tags: ['user'],
+  }
+);
+```
+## `cache` function (request memoization)
+Deduplicate data fetching within a single request:
+```typescript
+import { cache } from 'react';
+export const getUser = cache(async (id: string) => {
+  const res = await fetch(`/api/users/${id}`);
+  return res.json();
+});
+// Call getUser(id) multiple times in different components —
+// only one fetch happens per request
+```
+## Debugging caching
+### Check build output
+```bash
+npx next build
+# Look for route types:
+# ○  Static
+# ●  SSG (ISR)
+# λ  Dynamic (server-rendered)
+```
+### Headers to check
+```typescript
+// Check cache status in response headers
+// x-nextjs-cache: HIT | MISS | STALE
+```
+### Disable all caching (development)
+```typescript
+// next.config.js
+module.exports = {
+  experimental: {
+    staleTimes: { dynamic: 0, static: 0 },
+  },
+};
+```
+## Common patterns
+### Static page with periodic revalidation (ISR)
+```typescript
+export const revalidate = 3600; // Revalidate every hour
+export default async function Page() {
+  const data = await fetch('https://api.example.com/data');
+  return <div>{/* render data */}</div>;
+}
+```
+### Dynamic page (no cache)
+```typescript
+export const dynamic = 'force-dynamic';
+export default async function Page() {
+  const data = await fetch('https://api.example.com/data');
+  return <div>{/* render data */}</div>;
+}
+```
+## Troubleshooting
+### Stale data after deploy
+- Use `revalidatePath` or `revalidateTag` for on-demand updates
+- Check if `revalidate` is set too high
+### Page always dynamic when you want static
+- Remove `cookies()`, `headers()`, or `searchParams` usage
+- These force dynamic rendering

package/.agents/skills/next-js/references/common-errors.md ADDED Viewed

@@ -0,0 +1,251 @@
+# Next.js Common Errors
+Solutions for frequently encountered Next.js errors.
+## When to use this reference
+- Debugging build or runtime errors
+- Fixing hydration mismatches
+- Resolving Server/Client Component issues
+## Server/Client Component errors
+### "useState is not a function" / "Hooks can only be called inside a component"
+**Symptoms:**
+```
+Error: useState is not a function
+Error: (0, react__WEBPACK_IMPORTED_MODULE_0__.createContext) is not a function
+```
+**Causes:**
+- Using React hooks in a Server Component
+**Solutions:**
+Add `'use client'` directive at the top of the file:
+```typescript
+'use client';
+import { useState } from 'react';
+export default function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+### "Event handlers cannot be passed to Client Component props"
+**Symptoms:**
+```
+Error: Event handlers cannot be passed to Client Component props
+```
+**Causes:**
+- Passing `onClick` or other handlers from Server to Client Component
+**Solutions:**
+Create a Client Component wrapper:
+```typescript
+// ClientButton.tsx
+'use client';
+export function ClientButton({ label }: { label: string }) {
+  return <button onClick={() => console.log('clicked')}>{label}</button>;
+}
+```
+## Hydration errors
+### "Hydration failed because the server rendered HTML didn't match the client"
+**Symptoms:**
+```
+Error: Hydration failed because the server rendered HTML didn't match the client
+```
+**Causes:**
+- Browser-only code in Server Component render
+- Date/time rendering (server time vs client time)
+- Browser extensions modifying DOM
+- Conditional rendering based on `typeof window`
+**Solutions:**
+```typescript
+'use client';
+import { useState, useEffect } from 'react';
+export function ClientDate() {
+  const [date, setDate] = useState<string>('');
+  useEffect(() => {
+    setDate(new Date().toLocaleDateString());
+  }, []);
+  return <span>{date}</span>;
+}
+```
+Or use `suppressHydrationWarning`:
+```tsx
+<time suppressHydrationWarning>{new Date().toLocaleDateString()}</time>
+```
+## Build errors
+### "Dynamic server usage" errors
+**Symptoms:**
+```
+Error: Dynamic server usage: cookies
+Error: Dynamic server usage: headers
+```
+**Causes:**
+- Using `cookies()`, `headers()`, or `searchParams` in a statically generated page
+**Solutions:**
+```typescript
+// Option 1: Mark as dynamic
+export const dynamic = 'force-dynamic';
+// Option 2: Use Suspense boundary
+import { Suspense } from 'react';
+export default function Page() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <DynamicContent />
+    </Suspense>
+  );
+}
+```
+### "Module not found: Can't resolve 'fs'"
+**Symptoms:**
+```
+Module not found: Can't resolve 'fs'
+Module not found: Can't resolve 'path'
+```
+**Causes:**
+- Using Node.js modules in Client Component or shared code
+**Solutions:**
+- Move server-only code to Server Components or Route Handlers
+- Use `server-only` package to prevent accidental client imports:
+```bash
+npm install server-only
+```
+```typescript
+import 'server-only';
+// This file can only be imported in Server Components
+```
+## Runtime errors
+### "Cannot read properties of null (reading 'useContext')"
+**Symptoms:**
+```
+TypeError: Cannot read properties of null (reading 'useContext')
+```
+**Causes:**
+- Multiple React versions
+- Provider not wrapping the component tree
+**Solutions:**
+Check for duplicate React:
+```bash
+npm ls react
+```
+Ensure providers are in a Client Component layout:
+```typescript
+// app/providers.tsx
+'use client';
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>;
+}
+```
+### "NEXT_REDIRECT" error in try/catch
+**Symptoms:**
+```
+Error: NEXT_REDIRECT
+```
+**Causes:**
+- `redirect()` throws an error internally — catching it prevents the redirect
+**Solutions:**
+Don't wrap `redirect()` in try/catch, or re-throw:
+```typescript
+import { redirect } from 'next/navigation';
+import { isRedirectError } from 'next/dist/client/components/redirect';
+try {
+  // some logic
+  redirect('/dashboard');
+} catch (error) {
+  if (isRedirectError(error)) throw error;
+  // handle other errors
+}
+```
+## Caching issues
+### Data not updating after mutation
+- Use `revalidatePath()` or `revalidateTag()` after mutations
+- Check if `dynamic = 'force-dynamic'` is needed
+- See `caching-revalidation.md` for details
+### Page shows stale content
+```typescript
+// Force fresh data
+export const dynamic = 'force-dynamic';
+export const revalidate = 0;
+```
+## Debugging
+```bash
+# Verbose build output
+NEXT_DEBUG_LOGGING=1 npx next build
+# Check bundle sizes
+npx next build --debug
+# Analyze bundle
+npm install @next/bundle-analyzer
+ANALYZE=true npx next build
+```

package/.agents/skills/next-js/references/embedded-docs.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Embedded Docs Reference
+Use local project sources first to match the installed Next.js version and app configuration.
+## Why local-first
+- Next.js behavior changes across major releases.
+- Repository config (`next.config.*`, app structure, runtime settings) is authoritative.
+## Lookup workflow
+1. Check installed version and environment:
+   ```bash
+   npx next --version
+   cat node_modules/next/package.json | rg '"version"'
+   ```
+2. Inspect local config and scripts:
+   ```bash
+   ls next.config.* 2>/dev/null
+   cat package.json | rg -n '"next"|\"dev\"|\"build\"|\"start\"' -n
+   ```
+3. Inspect app router structure and route files:
+   ```bash
+   rg --files app | head -n 50
+   ```
+4. Validate runtime/build behavior:
+   ```bash
+   npx next info
+   npx next build
+   ```
+## Use this when
+- Caching, dynamic rendering, or route behavior is unclear
+- Build output does not match expectations
+- Team-level conventions diverge from generic docs examples