Sådan bruger du Headless Kit

Vejledningen har to dele:

• Del 1, til udviklere: sæt sitet op, giv det et udseende, deploy det og hold det opdateret.
• Del 2, til redaktører: skriv og udgiv i WordPress i hverdagen. Den kan gives direkte videre til en kunde.

README.md er den tekniske reference: hvordan hver del virker, og alle filtre. Denne vejledning er gennemgangen.

Sådan hænger delene sammen

WordPress (cms.example.com)                     Next.js (example.com)
editors write here                              visitors see this

Headless Kit plugin ── content (REST API) ──▶   blocks → shadcn components
                    ── "this changed" ──────▶   /api/revalidate  refreshes those pages
                    ── Preview button ──────▶   /api/preview     opens one draft
                    ◀── style ──────────────    /api/theme       colors, fonts, editor CSS

• Redaktører rører aldrig kode. De skriver i blokeditoren, og sitet opdateres få sekunder efter, de udgiver.
• Udvikleren ejer udseendet. Et shadcn-preset i koden bestemmer farver, skrifttyper og komponenternes form. WordPress får den samme palet og en editor, der ligner sitet. Designændringer sker i koden; intet, du ændrer i WordPress' egne stilindstillinger, når ud på sitet.

Del 1: Til udviklere

1. Det får du

Du skal bruge:

• Node.js 22.13 eller nyere og pnpm (corepack enable sætter den version op, kittet beder om)
• WordPress 6.4 eller nyere på PHP 8.0 eller nyere, med et hvilket som helst tema

2. Kør det lokalt

WordPress

Vælg én:

• En WordPress til engangsbrug (kræver Docker). Kør npx @wordpress/env start fra kit-mappen. WordPress starter på http://localhost:8888 (log ind med admin / password) med pluginet aktiveret. ACF, Rank Math, SEOPress og Yoast er også installeret, så du kan prøve dem af. Aktivér ét SEO-plugin ad gangen.
• En WordPress, du allerede har (LocalWP, et staging-site…). Upload plugin-zippen, og aktivér den.

Derefter i WordPress:

1. Settings → Permalinks: vælg alt andet end "Plain".
2. Settings → Headless Kit: sæt Frontend URL til http://localhost:3000, og kopiér Shared secret.
3. Valgfrit: sæt hak i Projects for at få en portfoliosektion.

Next.js

cd web
cp .env.example .env.local

Sæt følgende i .env.local:

• WORDPRESS_URL=http://localhost:8888 (uden afsluttende skråstreg)
• HEADLESS_KIT_SECRET= den secret, du kopierede

Start det så:

pnpm install
pnpm dev

Åbn http://localhost:3000. Tilbage i Settings → Headless Kit skal linjen Connection sige, at frontenden har accepteret din secret. Gør den ikke det, så se Fejlfinding.

3. Tilføj noget indhold

• Forside: opret en side, der hedder "Home". Gå derefter til Settings → Reading → Your homepage displays → A static page, og vælg den. Dens blokke vises på /, efterfulgt af dine seneste projekter og indlæg.
• Blog: indlæg vises på /blog og /blog/<slug>, med sider for kategorier og tags. Vælger du en Posts page under Settings → Reading, omdirigerer den til /blog.
• Menuer: i Appearance → Menus tildeler du én menu til Header menu (Next.js) og én til Footer menu (Next.js). Pluginet tilføjer de placeringer, så menuskærmen findes selv med et bloktema. Indtil du har tildelt en headermenu, linker headeren til Blog (og til Projects, hvis de er slået til).
• Projects (hvis du har slået dem til): Projects → Add New.

Sæt en masse forskellige bloktyper på én testside: overskrifter, lister, citater, knapper, en gruppe med baggrundsfarve, en tabel og en details-blok. Det er den hurtigste måde at se, hvad kittet gør med hver af dem.

4. Vælg udseendet

Kittet kommer med tre udseender. Kør et af dem fra web/:

pnpm style studio      # minimal and neutral, Geist (the default)
pnpm style editorial   # warm stone and amber, Playfair Display headings
pnpm style bold        # zinc and violet, Space Grotesk, large radius
pnpm style             # list the looks

Eller design dit eget:

1. Design et på ui.shadcn.com/create.
2. Kopiér dets preset-kode, og kør pnpm style <code>.
3. Vil du bruge det ved navn, så tilføj det til web/presets.json.

Et preset bestemmer farverne (lyse og mørke), skrifttyperne, hjørneradius og formen på alle komponenter: knapper, kort, tabeller og accordions. Alt på sitet er bygget af de komponenter, blokindhold inklusive, så én kommando giver hele sitet nyt udseende.

WordPress følger med. Når du har deployet et nyt udseende, så klik på Sync style now under Settings → Headless Kit. Den synkroniserer også af sig selv hver 12. time. Editoren får så:

• presettets farver som farvepalet (Primary, Secondary, Muted, Accent, Card…)
• presettets skrifttyper
• et editor-lærred, der ligner sitet: overskrifter, knapper, kort og tabeller ser ud, som de vil gøre, når de er udgivet
• Preview dark mode i editorens ⋮-menu

5. Tilpas

Skift en bloks udseende. Blokkomponenterne ligger i web/src/components/blocks/, og deres klasser i blocks/styles.ts. Ret klasserne i styles.ts, ikke inline i komponenterne. pnpm theme bygger editorens stylesheet ud fra den fil, så editoren bliver ved med at ligne sitet; dev, build og style kører den alle sammen. Styler du en blok, editoren ikke kender endnu, så tilføj en linje for den i blockMap() i web/scripts/editor-style.mjs.

Tilføj en blok. Skriv en komponent, der tager { block, children }, og registrér den i defaultComponents i block-renderer.tsx:

"acme/testimonial": Testimonial,

En blok uden komponent falder tilbage til WordPress' egen HTML, stylet så den passer ind. Under udvikling viser konsollen, hvilke blokke der bruger denne fallback.

Custom post types og taksonomier. Registrér dem med public og show_in_rest slået til, via CPT UI, ACF eller kode. Hver post type vises på /<rewrite slug>/<post> med en oversigtsside, og dens taksonomier får term-sider. Du behøver ingen route-filer. Tilføj kun en route-mappe, fx app/events/[slug]/page.tsx, når en type skal have sit eget layout.

ACF-felter. Slå Show in REST API til for en feltgruppe, og læs så felterne i en server component:

import { acf, type AcfImage } from "@/lib/wordpress/acf"

const hero = acf<AcfImage | null>(post, "hero")

SEO. Når Rank Math, SEOPress eller Yoast er aktivt, havner titler, beskrivelser, canonical URLs, noindex og sociale billeder automatisk i sidens metadata.

Dark mode. Det er slået til som standard, med en knap i headeren. Vil du have et site kun i lyst tema, så fjern ThemeToggle fra headeren.

README.md lister alle pluginets filtre til at forme data, URLs og styles.

6. Test

Fra web/:

pnpm typecheck   # TypeScript
pnpm lint        # Biome: lint and formatting
pnpm test        # unit tests: preview tickets, cache tags, data parsing, the API routes
pnpm test:e2e    # builds the site against a fake WordPress and checks preview links end to end

pnpm test:e2e erstatter dit build i .next med et, der peger på den falske WordPress. Kør pnpm build igen, før du deployer fra den mappe.

Testene renderer ikke dine sider, så tjek dem også i en browser mod en WordPress med rigtigt indhold. Et manglende indlæg kan returnere HTTP 200 med en "not found"-side, så en statuskode alene beviser ikke, at en side virker.

7. Deploy

Det typiske setup er WordPress på et subdomæne (cms.example.com) og Next.js på hoveddomænet.

Vercel

1. Importér repoet, og sæt root directory til web/.
2. Sæt tre miljøvariabler:
   • WORDPRESS_URL
   • HEADLESS_KIT_SECRET
   • NEXT_PUBLIC_SITE_URL: dit sites offentlige adresse
3. Deploy, og peg så dit domæne på det.

Din egen server

web/ bygger en selvstændig Node.js-server:

cd web
pnpm build
cp -r public .next/standalone/                  # Next.js doesn't copy these two for you
cp -r .next/static .next/standalone/.next/
cd .next/standalone && HOSTNAME=127.0.0.1 PORT=3000 node server.js

Sæt en reverse proxy som Caddy eller nginx foran. Byg på samme styresystem og CPU-arkitektur som serveren, fordi nogle afhængigheder (billedoptimering) kommer med native binære filer.

Buildet henter rigtigt indhold, så WORDPRESS_URL skal kunne nås, når du bygger.

Derefter i WordPress

1. Settings → Headless Kit: sæt Frontend URL til det live site, og tjek, at Connection-linjen er grøn.
2. Sæt hak i Frontend redirect. Besøgende på det gamle WordPress-site bliver så sendt videre til Next.js-sitet, mens wp-admin, login og REST API'et bliver ved med at virke.
3. Klik på Sync style now.

8. Opdatér til en ny version

Kittet og pluginet deler versionsnummer, så opdatér dem sammen. CHANGELOG.md viser, hvad der er ændret i hver version.

1. Plugin: upload den nye plugin-zip under Plugins → Add New → Upload. WordPress erstatter den gamle version.
2. Site:
   1. Kopiér den nye web/ hen over din egen på en ny git-branch.
   2. Gennemgå diffen, så dine egne ændringer i blokke og komponenter bliver bevaret.
   3. Kør pnpm install, tjekkene fra Test og pnpm build.
3. Deploy sitet, og klik så på Sync style now.

Nogle releases ændrer begge sider af en funktion (fx sikkerhedsrettelser til previews). Deploy både det nye site og det nye plugin, også selvom din egen kode ikke er ændret.

9. Tjekliste før lancering

• ☐ pnpm typecheck, pnpm lint, pnpm test og pnpm build går igennem
• ☐ Connection-linjen er grøn med den live frontend-URL
• ☐ Når du udgiver et indlæg, ændres det live site inden for få sekunder
• ☐ Preview på en kladde åbner den på det live site
• ☐ Header- og footermenuer er tildelt
• ☐ Sync style now er kørt, og et indlæg i editoren ligner sitet
• ☐ Frontend redirect er slået til
• ☐ Permalinks er ikke sat til "Plain"

Del 2: Til redaktører

Du skriver i WordPress, som du plejer. Forskellen er, at de besøgende ser et separat, hurtigere website, der bygges ud fra det, du skriver. Alt, hvad du udgiver, dukker op der inden for få sekunder.

1. Skriv og udgiv

Opret indlæg under Posts og sider under Pages med blokeditoren som altid. Når du klikker på Publish eller Update, opdateres websitet med det samme. Du skal ikke gøre andet.

Editoren ligner det rigtige site meget, med de samme skrifttyper, farver, overskrifter, knapper, kort og tabeller. Den er ikke helt præcis, fordi WordPress tilføjer sin egen luft og sine egne rammer. Brug Preview til det endelige tjek.

2. Se en kladde i preview

1. Gem kladden. Preview viser den senest gemte version.
2. Klik på Preview i editoren (øverst til højre). Kladden åbner på det rigtige website, som de besøgende vil se den.
3. Når du har lavet flere ændringer, så gem igen, og genindlæs preview-fanen.
4. Klik på Exit preview i banneret øverst, når du er færdig.

Godt at vide:

• Et preview viser ét indlæg. Du kan ikke åbne en anden kladde på sitet; klik i stedet på Preview på den kladde i WordPress. Du kan godt have flere previews åbne på én gang.
• Et preview er åbent i en time. Derefter, eller hvis linket er gammelt, skriver sitet This preview has expired. Klik på Preview i WordPress igen.
• Et Preview-link virker én gang. Åbner du det igen, fra browserhistorikken eller en besked, får du at vide, at linket er ugyldigt. Skal du vise en kladde til nogen, skal de have deres eget WordPress-login og bruge Preview-knappen.

3. Brug de rigtige blokke

De fleste blokke bliver til en tilsvarende del af sitets design:

Andre blokke vises stadig, bare i WordPress' egen styling.

Farver. Farvevælgeren tilbyder sitets egne farver: Primary, Secondary, Muted, Accent, Card og så videre. Brug dem frem for brugerdefinerede farver, for de tilpasser sig dark mode og følger med fremtidige designændringer. En gruppe farvet Primary forbliver brandfarven, også hvis brandfarven ændres senere.

Udvalgte billeder. Et udvalgt billede vises øverst i sit indlæg eller sin side, på kortene i blog- og projektlisterne og i linkpreviews, når nogen deler siden. Vil du kun bruge det på kort og i linkpreviews, så fjern hakket i Show on the page under billedet i sidepanelet. Det er praktisk, når siden allerede starter med et billede eller en video.

Dark mode. De besøgende kan skifte sitet til dark mode. Vil du se dit indhold i dark mode, mens du redigerer, så åbn ⋮-menuen (øverst til højre), og vælg Preview dark mode. Vælg den igen for at skifte tilbage. Det ændrer kun din egen visning.

4. Forside, projekter og menuer

• Forside: en helt almindelig side, ofte kaldet "Home". Redigér den som alle andre sider; dine seneste projekter og indlæg bliver automatisk tilføjet nedenunder.
• Projects (hvis dit site har dem): Projects → Add New. Udfyld boksen Project details (kunde, år, rolle og live-URL). Tilføj et udvalgt billede, et uddrag (vises som intro) og projekt-tags. Feltet Order under Page Attributes bestemmer projekternes rækkefølge.
• Menuer: Appearance → Menus. De menuer, der er tildelt Header menu (Next.js) og Footer menu (Next.js), er sitets navigation. Ændringer vises, så snart du gemmer.

5. SEO

Bruger dit site Yoast, Rank Math eller SEOPress, så udfyld SEO-boksen under hvert indlæg og hver side som altid. Websitet bruger titlen, beskrivelsen og det sociale billede derfra. Uden et SEO-plugin bliver uddraget til beskrivelsen og det udvalgte billede til det sociale billede. Previews viser de senest gemte SEO-værdier.

6. Hvis noget ser forkert ud

Fejlfinding

Til udviklere.