pikkujs/pikku-deploy-nextjs

Pikku Next.js Deployment

Agent Operating Procedure

Use this skill as an execution checklist, not reference material.

1. Discover before editing. Prefer OpenCode tools such as pikku-meta when available; otherwise run the relevant pikku meta ... --json command and inspect only the focused output you need.
2. Identify the source files that own the behavior. Do not start by reading generated output, .pikku, node_modules, vendored packages, or broad build artifacts.
3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
4. Validate with the narrowest relevant command first, then run pikku-verify or pikku all when functions, wirings, schemas, or generated clients may have changed.
5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.

yarn add @pikku/next

API Route Handler

The CLI generates a typed wrapper. Use it in a catch-all route:

// app/api/[...route]/route.ts
import { pikkuAPIRequest } from '@/pikku-nextjs.gen.js'

export const GET = pikkuAPIRequest
export const POST = pikkuAPIRequest
export const PUT = pikkuAPIRequest
export const PATCH = pikkuAPIRequest
export const DELETE = pikkuAPIRequest

Server-Side Data Fetching

Use the generated pikku() helper in Server Components or Server Actions:

import { pikku } from '@/pikku-nextjs.gen.js'

const { get, post, del, rpc, staticGet, staticPost, staticRPC } = pikku()

// Dynamic (reads headers/cookies — requires request context)
const todos = await get('/todos')
const created = await post('/todos', { title: 'Buy milk' })

// Static (no request context — suitable for precompile/ISR)
const config = await staticGet('/config')

// RPC calls
const result = await rpc('calculateTax', { amount: 100, region: 'US' })

Dynamic vs Static:

• get, post, del, rpc — access headers/cookies, use in dynamic Server Components
• staticGet, staticPost, staticRPC — no request context, safe for precompile/ISR

How It Works

PikkuNextJS lazy-initializes on first request:

import { PikkuNextJS } from '@pikku/next'

const pikku = new PikkuNextJS(createConfig, createSingletonServices)

Constructor: new PikkuNextJS(createConfig?, createSingletonServices)

The generated pikku-nextjs.gen.ts wraps this with full type safety from your route definitions.