A Shadow Within - Next.js + Sanity + Shopify + Spotify

Development instructions for AI coding agents working on A Shadow Within — a Next.js 15 band/music website integrating Sanity CMS, Shopify Storefront API, Spotify/YouTube metadata, Klaviyo newsletters, and Gmail-based contact forms.

Project Architecture

This is a Next.js 15 app router site combining:

Directory Structure

Core Folders

- Entry points: `app/layout.tsx`, `app/page.tsx`

- `fetchSpotify/route.ts` — Spotify metadata fetcher

- `subscribe/route.ts` — Klaviyo newsletter signup

- `contact/route.ts` — Gmail contact form handler

- `youtube-subs/route.ts` — YouTube statistics fetcher

- `sanity/lib/*` — Client helpers, image utilities

- `sanity/plugins/SpotifyFetcherInput.tsx` — Custom Sanity plugin calling `/api/fetchSpotify`

- `spotify.ts`, `shopify.ts`, `sanity.ts`, `videoCover.ts`

Environment Variables

Public Variables (Client-Safe)

Prefixed with `NEXT_PUBLIC_` — exposed to browser:

Private Variables (Server-Only)

**Never** expose these client-side:

Development Patterns

1. Server-First Data Fetching

Prefer async server components for data fetching:

```typescript

// app/page.tsx

export default async function HomePage() {

const data = await fetchFromSanity();

return <div>{/* render */}</div>;

}

```

2. Client Components

Keep lightweight, use `"use client"` directive:

```typescript

// app/components/SignupForm.tsx

"use client";

export function SignupForm() {

// Client-side interactivity only

}

```

Place in `app/components/`. Fetch data via server-side API routes in `app/api/`.

3. Caching Strategy

4. Image Handling

- `cdn.sanity.io`

- `img.youtube.com`

- Shopify CDN domains

5. Sanity Integration

API Endpoint Patterns

Structure

```typescript

// app/api/example/route.ts

import { NextResponse } from 'next/server';

export async function GET(request: Request) {

try {

// Server-side logic with env vars

const data = await fetchExternal();

return NextResponse.json(data);

} catch (error) {

return NextResponse.json(

{ error: 'Failed' },

{ status: 500 }

);

}

}

```

Key Endpoints

**Spotify Metadata** (`/api/fetchSpotify`):

**Newsletter Signup** (`/api/subscribe`):

**Contact Form** (`/api/contact`):

**YouTube Stats** (`/api/youtube-subs`):

Common Tasks

Local Development

```bash

npm run dev

```

Production Build

```bash

npm run build

npm start

```

Type Checking

TypeScript strict mode enabled. Run editor type checking (no project-wide linter in repo root).

Critical Rules

1. Secret Management

2. API Contract Preservation

When modifying `/api/fetchSpotify`:

3. Rate Limiting

External APIs (Spotify, YouTube, Shopify) have rate limits:

4. Query Parameter Interfaces

When Sanity studio calls an endpoint (e.g., Spotify fetcher):

Example Workflows

Adding a New API Integration

1. Create route handler in `app/api/new-integration/route.ts`

2. Use `NextResponse.json()` for responses

3. Add server-only env vars (no `NEXT_PUBLIC_` prefix)

4. Cache with appropriate `revalidate` value

5. Document response shape if consumed by Sanity

Modifying Shopify Queries

Reference `app/lib/shopify.ts`:

Updating Sanity Schemas

After schema changes:

1. Update types in `sanity/lib/` if needed

2. Rebuild Sanity studio

3. Test studio preview/live modes

4. Verify `sanity/lib/client.ts` configurations

Error Handling

Server Routes

External API Failures

Migration Notes

When making breaking changes:

1. Document old vs new behavior in commit message

2. Update dependent code (Sanity plugins, client components)

3. Add migration steps if env vars change

4. Test across all integration points

Reference Files

Consult these when making related changes:

Questions & Expansion

If you need more detail on:

Request expansion for that specific area and reference documentation will be provided.