odyssey: Skill for Claude Code

React & Next.js 15 Patterns for Odyssey

This Is Next.js 15

Odyssey uses Next.js 15 with App Router. Key differences from 14:

• params and searchParams are Promises — always await them
• cache and next on fetch are mutually exclusive — passing both silently breaks
• Server Components are the default — no directive needed

Route Structure

app/
├── (general)/       Dashboard, explore, feed, admin, settings, friends
├── (droplets)/      /d/[slug] — droplet viewing
├── (playlists)/     /p/[slug] — playlist viewing
├── (creation)/      /new/ — content creation
├── (editing)/       /draft/ — draft editing
├── (groups)/        /g/[slug] — group pages
└── api/auth/[...nextauth]/  — NextAuth (only API route)

Route groups (parenthesized) share layouts without affecting URL paths.

Server vs. Client Component Decision Tree

Does this component need...
├── useState, useEffect, useRef, event handlers, Zustand?
│   └── YES → "use client" (Client Component)
├── fetchAPI() or direct data fetching?
│   └── YES → Server Component (default, no directive)
├── Browser APIs (window, document, localStorage)?
│   └── YES → "use client"
├── Only rendering props/children with Tailwind?
│   └── YES → Server Component (default)
└── Mixed? (parent fetches, child is interactive)
    └── Keep parent as Server Component, wrap child as Client Component

Component Boundaries

The #1 mistake: Making a parent component "use client" because a child needs interactivity.

// BAD — entire tree becomes client, loses SSR data fetching
"use client";
export default function DropletPage({ params }) {
  const [isOpen, setIsOpen] = useState(false);
  const droplet = useDroplet(params.slug); // now needs client-side fetch
  return <div>...</div>;
}

// GOOD — server parent, client child
export default async function DropletPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params; // Next.js 15: params is a Promise
  const droplet = await getDropletBySlug(slug); // server fetch

  if (!droplet) notFound();

  return (
    <div>
      <DropletHeader droplet={droplet} />
      <InteractivePanel defaultOpen={false} /> {/* "use client" */}
    </div>
  );
}