Official Next.js App Router starter that reads collection items from Externa’s headless /api/v1 API. List + detail pages, env-based config, server-side fetches only.

Public CMS API · Public CMS API types · GraphQL · Quick Start · Installation · Repo: qiick-io/externa-next-starter

What you get

Piece	Notes
`/`	Lists items for one collection slug
`/items/[id]`	Shows field values for one item
`lib/externa.ts`	Thin `fetch` helper (Bearer optional)
`.env.example`	`EXTERNA_API_URL`, `EXTERNA_API_KEY`, `EXTERNA_COLLECTION`

Not included: marketing theme, Kitchen Sink seed, OpenAPI codegen client (see Public CMS API types and core #25).

1. Run Externa

Follow Quick Start or Installation until the admin is up (e.g. http://externa-core.test).

Create a collection (slug posts is the starter default) and at least one item.

Grant Read on that collection for the public role (or create an API key whose role has Read) — Public CMS API quick start.

2. Clone and configure the starter

git clone https://github.com/qiick-io/externa-next-starter.git
cd externa-next-starter
cp .env.example .env.local

Edit .env.local:

EXTERNA_API_URL=http://externa-core.test
# optional — omit to use the public role
EXTERNA_API_KEY=
EXTERNA_COLLECTION=posts

npm install
npm run dev

Open http://localhost:3002.

API key stays on the server

EXTERNA_API_KEY is read only in Server Components / server fetch. Do not prefix it with NEXT_PUBLIC_.

3. Verify the API without Next

curl -sS 'http://externa-core.test/api/v1/collections/posts/items?page=1&per_page=5' \
  -H 'Accept: application/json'
# optional: -H "Authorization: Bearer ek_YOUR_SECRET"

Ready-made requests: externa-bruno.

GraphQL

The starter uses REST. The same Collection access rules apply at /api/graphql — GraphQL.

Rebuild when content changes

Point Externa outbound webhooks at your host’s deploy hook (or a Make/n8n scenario) so publishes trigger a rebuild.