Development guide for a Next.js 15 band/music site with Sanity CMS, Shopify merch integration, Spotify/YouTube APIs, and email handling via Gmail OAuth2.
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.
This is a Next.js 15 app router site combining:
- 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`
Prefixed with `NEXT_PUBLIC_` — exposed to browser:
**Never** expose these client-side:
Prefer async server components for data fetching:
```typescript
// app/page.tsx
export default async function HomePage() {
const data = await fetchFromSanity();
return <div>{/* render */}</div>;
}
```
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/`.
- `cdn.sanity.io`
- `img.youtube.com`
- Shopify CDN domains
```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 }
);
}
}
```
**Spotify Metadata** (`/api/fetchSpotify`):
**Newsletter Signup** (`/api/subscribe`):
**Contact Form** (`/api/contact`):
**YouTube Stats** (`/api/youtube-subs`):
```bash
npm run dev
```
```bash
npm run build
npm start
```
TypeScript strict mode enabled. Run editor type checking (no project-wide linter in repo root).
When modifying `/api/fetchSpotify`:
External APIs (Spotify, YouTube, Shopify) have rate limits:
When Sanity studio calls an endpoint (e.g., Spotify fetcher):
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
Reference `app/lib/shopify.ts`:
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
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
Consult these when making related changes:
If you need more detail on:
Request expansion for that specific area and reference documentation will be provided.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/a-shadow-within-nextjs-sanity-shopify-spotify/raw