npm - create-xani-agentic-app - Versions diffs - 1.0.0 - Mend

create-xani-agentic-app 1.0.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 (563) hide show

package/template/.agents/skills/nextjs/references/file-conventions.md ADDED Viewed

@@ -0,0 +1,140 @@
+# File Conventions
+Next.js App Router uses file-based routing with special file conventions.
+## Project Structure
+Reference: https://nextjs.org/docs/app/getting-started/project-structure
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home page (/)
+├── loading.tsx         # Loading UI
+├── error.tsx           # Error UI
+├── not-found.tsx       # 404 UI
+├── global-error.tsx    # Global error UI
+├── route.ts            # API endpoint
+├── template.tsx        # Re-rendered layout
+├── default.tsx         # Parallel route fallback
+├── blog/
+│   ├── page.tsx        # /blog
+│   └── [slug]/
+│       └── page.tsx    # /blog/:slug
+└── (group)/            # Route group (no URL impact)
+    └── page.tsx
+```
+## Special Files
+| File | Purpose |
+|------|---------|
+| `page.tsx` | UI for a route segment |
+| `layout.tsx` | Shared UI for segment and children |
+| `loading.tsx` | Loading UI (Suspense boundary) |
+| `error.tsx` | Error UI (Error boundary) |
+| `not-found.tsx` | 404 UI |
+| `route.ts` | API endpoint |
+| `template.tsx` | Like layout but re-renders on navigation |
+| `default.tsx` | Fallback for parallel routes |
+## Route Segments
+```
+app/
+├── blog/               # Static segment: /blog
+├── [slug]/             # Dynamic segment: /:slug
+├── [...slug]/          # Catch-all: /a/b/c
+├── [[...slug]]/        # Optional catch-all: / or /a/b/c
+└── (marketing)/        # Route group (ignored in URL)
+```
+## Parallel Routes
+```
+app/
+├── @analytics/
+│   └── page.tsx
+├── @sidebar/
+│   └── page.tsx
+└── layout.tsx          # Receives { analytics, sidebar } as props
+```
+## Intercepting Routes
+```
+app/
+├── feed/
+│   └── page.tsx
+├── @modal/
+│   └── (.)photo/[id]/  # Intercepts /photo/[id] from /feed
+│       └── page.tsx
+└── photo/[id]/
+    └── page.tsx
+```
+Conventions:
+- `(.)` - same level
+- `(..)` - one level up
+- `(..)(..)` - two levels up
+- `(...)` - from root
+## Private Folders
+```
+app/
+├── _components/        # Private folder (not a route)
+│   └── Button.tsx
+└── page.tsx
+```
+Prefix with `_` to exclude from routing.
+## Middleware / Proxy
+### Next.js 14-15: `middleware.ts`
+```ts
+// middleware.ts (root of project)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+export function middleware(request: NextRequest) {
+  // Auth, redirects, rewrites, etc.
+  return NextResponse.next();
+}
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+### Next.js 16+: `proxy.ts`
+Renamed for clarity - same capabilities, different names:
+```ts
+// proxy.ts (root of project)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+export function proxy(request: NextRequest) {
+  // Same logic as middleware
+  return NextResponse.next();
+}
+export const proxyConfig = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+| Version | File | Export | Config |
+|---------|------|--------|--------|
+| v14-15 | `middleware.ts` | `middleware()` | `config` |
+| v16+ | `proxy.ts` | `proxy()` | `proxyConfig` |
+**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
+## File Conventions Reference
+Reference: https://nextjs.org/docs/app/api-reference/file-conventions

package/template/.agents/skills/nextjs/references/font.md ADDED Viewed

@@ -0,0 +1,245 @@
+# Font Optimization
+Use `next/font` for automatic font optimization with zero layout shift.
+## Google Fonts
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] })
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={inter.className}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+## Multiple Fonts
+```tsx
+import { Inter, Roboto_Mono } from 'next/font/google'
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+})
+const robotoMono = Roboto_Mono({
+  subsets: ['latin'],
+  variable: '--font-roboto-mono',
+})
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+Use in CSS:
+```css
+body {
+  font-family: var(--font-inter);
+}
+code {
+  font-family: var(--font-roboto-mono);
+}
+```
+## Font Weights and Styles
+```tsx
+// Single weight
+const inter = Inter({
+  subsets: ['latin'],
+  weight: '400',
+})
+// Multiple weights
+const inter = Inter({
+  subsets: ['latin'],
+  weight: ['400', '500', '700'],
+})
+// Variable font (recommended) - includes all weights
+const inter = Inter({
+  subsets: ['latin'],
+  // No weight needed - variable fonts support all weights
+})
+// With italic
+const inter = Inter({
+  subsets: ['latin'],
+  style: ['normal', 'italic'],
+})
+```
+## Local Fonts
+```tsx
+import localFont from 'next/font/local'
+const myFont = localFont({
+  src: './fonts/MyFont.woff2',
+})
+// Multiple files for different weights
+const myFont = localFont({
+  src: [
+    {
+      path: './fonts/MyFont-Regular.woff2',
+      weight: '400',
+      style: 'normal',
+    },
+    {
+      path: './fonts/MyFont-Bold.woff2',
+      weight: '700',
+      style: 'normal',
+    },
+  ],
+})
+// Variable font
+const myFont = localFont({
+  src: './fonts/MyFont-Variable.woff2',
+  variable: '--font-my-font',
+})
+```
+## Tailwind CSS Integration
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+})
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={inter.variable}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+```js
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['var(--font-inter)'],
+      },
+    },
+  },
+}
+```
+## Preloading Subsets
+Only load needed character subsets:
+```tsx
+// Latin only (most common)
+const inter = Inter({ subsets: ['latin'] })
+// Multiple subsets
+const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] })
+```
+## Display Strategy
+Control font loading behavior:
+```tsx
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap', // Default - shows fallback, swaps when loaded
+})
+// Options:
+// 'auto' - browser decides
+// 'block' - short block period, then swap
+// 'swap' - immediate fallback, swap when ready (recommended)
+// 'fallback' - short block, short swap, then fallback
+// 'optional' - short block, no swap (use if font is optional)
+```
+## Don't Use Manual Font Links
+Always use `next/font` instead of `<link>` tags for Google Fonts.
+```tsx
+// Bad: Manual link tag (blocks rendering, no optimization)
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+// Bad: Missing display and preconnect
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+// Good: Use next/font (self-hosted, zero layout shift)
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] })
+```
+## Common Mistakes
+```tsx
+// Bad: Importing font in every component
+// components/Button.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
+// Good: Import once in layout, use CSS variable
+// app/layout.tsx
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+// Bad: Using @import in CSS (blocks rendering)
+/* globals.css */
+@import url('https://fonts.googleapis.com/css2?family=Inter');
+// Good: Use next/font (self-hosted, no network request)
+import { Inter } from 'next/font/google'
+// Bad: Loading all weights when only using a few
+const inter = Inter({ subsets: ['latin'] }) // Loads all weights
+// Good: Specify only needed weights (for non-variable fonts)
+const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
+// Bad: Missing subset - loads all characters
+const inter = Inter({})
+// Good: Always specify subset
+const inter = Inter({ subsets: ['latin'] })
+```
+## Font in Specific Components
+```tsx
+// For component-specific fonts, export from a shared file
+// lib/fonts.ts
+import { Inter, Playfair_Display } from 'next/font/google'
+export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' })
+// components/Heading.tsx
+import { playfair } from '@/lib/fonts'
+export function Heading({ children }) {
+  return <h1 className={playfair.className}>{children}</h1>
+}
+```

package/template/.agents/skills/nextjs/references/functions.md ADDED Viewed

@@ -0,0 +1,108 @@
+# Functions
+Next.js function APIs.
+Reference: https://nextjs.org/docs/app/api-reference/functions
+## Navigation Hooks (Client)
+| Hook | Purpose | Reference |
+|------|---------|-----------|
+| `useRouter` | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router) |
+| `usePathname` | Get current pathname | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname) |
+| `useSearchParams` | Read URL search parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params) |
+| `useParams` | Access dynamic route parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params) |
+| `useSelectedLayoutSegment` | Active child segment (one level) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment) |
+| `useSelectedLayoutSegments` | All active segments below layout | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) |
+| `useLinkStatus` | Check link prefetch status | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status) |
+| `useReportWebVitals` | Report Core Web Vitals metrics | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals) |
+## Server Functions
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `cookies` | Read/write cookies | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies) |
+| `headers` | Read request headers | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers) |
+| `draftMode` | Enable preview of unpublished CMS content | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) |
+| `after` | Run code after response finishes streaming | [Docs](https://nextjs.org/docs/app/api-reference/functions/after) |
+| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) |
+| `userAgent` | Parse User-Agent header | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent) |
+## Generate Functions
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `generateStaticParams` | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) |
+| `generateMetadata` | Dynamic metadata | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) |
+| `generateViewport` | Dynamic viewport config | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport) |
+| `generateSitemaps` | Multiple sitemaps for large sites | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps) |
+| `generateImageMetadata` | Multiple OG images per route | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) |
+## Request/Response
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `NextRequest` | Extended Request with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request) |
+| `NextResponse` | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response) |
+| `ImageResponse` | Generate OG images | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) |
+## Common Examples
+### Navigation
+Use `next/link` for internal navigation instead of `<a>` tags.
+```tsx
+// Bad: Plain anchor tag
+<a href="/about">About</a>
+// Good: Next.js Link
+import Link from 'next/link'
+<Link href="/about">About</Link>
+```
+Active link styling:
+```tsx
+'use client'
+import Link from 'next/link'
+import { usePathname } from 'next/navigation'
+export function NavLink({ href, children }) {
+  const pathname = usePathname()
+  return (
+    <Link href={href} className={pathname === href ? 'active' : ''}>
+      {children}
+    </Link>
+  )
+}
+```
+### Static Generation
+```tsx
+// app/blog/[slug]/page.tsx
+export async function generateStaticParams() {
+  const posts = await getPosts()
+  return posts.map((post) => ({ slug: post.slug }))
+}
+```
+### After Response
+```tsx
+import { after } from 'next/server'
+export async function POST(request: Request) {
+  const data = await processRequest(request)
+  after(async () => {
+    await logAnalytics(data)
+  })
+  return Response.json({ success: true })
+}
+```

package/template/.agents/skills/nextjs/references/hydration-error.md ADDED Viewed

@@ -0,0 +1,91 @@
+# Hydration Errors
+Diagnose and fix React hydration mismatch errors.
+## Error Signs
+- "Hydration failed because the initial UI does not match"
+- "Text content does not match server-rendered HTML"
+## Debugging
+In development, click the hydration error to see the server/client diff.
+## Common Causes and Fixes
+### Browser-only APIs
+```tsx
+// Bad: Causes mismatch - window doesn't exist on server
+<div>{window.innerWidth}</div>
+// Good: Use client component with mounted check
+'use client'
+import { useState, useEffect } from 'react'
+export function ClientOnly({ children }: { children: React.ReactNode }) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  return mounted ? children : null
+}
+```
+### Date/Time Rendering
+Server and client may be in different timezones:
+```tsx
+// Bad: Causes mismatch
+<span>{new Date().toLocaleString()}</span>
+// Good: Render on client only
+'use client'
+const [time, setTime] = useState<string>()
+useEffect(() => setTime(new Date().toLocaleString()), [])
+```
+### Random Values or IDs
+```tsx
+// Bad: Random values differ between server and client
+<div id={Math.random().toString()}>
+// Good: Use useId hook
+import { useId } from 'react'
+function Input() {
+  const id = useId()
+  return <input id={id} />
+}
+```
+### Invalid HTML Nesting
+```tsx
+// Bad: Invalid - div inside p
+<p><div>Content</div></p>
+// Bad: Invalid - p inside p
+<p><p>Nested</p></p>
+// Good: Valid nesting
+<div><p>Content</p></div>
+```
+### Third-party Scripts
+Scripts that modify DOM during hydration.
+```tsx
+// Good: Use next/script with afterInteractive
+import Script from 'next/script'
+export default function Page() {
+  return (
+    <Script
+      src="https://example.com/script.js"
+      strategy="afterInteractive"
+    />
+  )
+}
+```