Next.js / Wordpress Starter

An opinionated boilerplate for decoupled (headless) websites that are both performant (Next.js) and easy to edit (WordPress with Gutenberg block editor) — focused on accelerating custom blocks development.

Features

Highlights

• Create new blocks quickly via a CLI
• Iterate efficiently on your blocks — Gutenberg and frontend code in the same folder
• Easy data fetching through GraphQL
• Save time with pre-built blocks and hooks

Next.js

• Next.js 14 with App Router and React Server Components
• Next.js Preview Mode
• Next.js Cache Revalidation (via WordPress Plugin)

The basics

• Typing with TypeScript
• Styling with CSS (PostCSS) why?
• Dynamic styleguide with Storybook
• Dockerized
• Multilang (coming soon)

Supported WordPress plugins

• Yoast SEO
• Redirection
• ACF
• Polylang Pro (coming soon)

Dependencies

Name	Version	Download
Nvm	>= 0.38	nvm
Node	>= 20.x	node
Docker	>= 23	docker
Docker Compose	>= 1.29	docker-compose
Mutagen	>= 0.17	mutagen

📄 Scripts Cheatsheet

WordPress

(inside /wordpress folder)

• npm run start:wp - start WP server
• npm run stop:wp - stop WP server
• npm run build:assets - build Webpack for the assets on WP
• npm run start:assets - start Webpack for the assets on WP (watch + hot reload)

Open http://localhost/wp-admin/ on your browser to access to the admin. (login: superstack, password: superstack)

Next.js

• npm run dev - start Next.js in development mode (watch + hot reload)
• npm run build - build Next.js in production mode
• npm run start - start a Next.js production server to test the production mode on local

Open http://localhost:3000 with your browser to see the result.

Storybook

• npm run storybook - start Storybook

Open http://localhost:4000 with your browser to access to Storybook.

Additional commands

• npm run generate:block - create a new block (interactive prompt)

🏗 Project setup

• Getting Started
• Add favicon
• Add fonts
• Create a Custom Post Type
• WP Guides
• Deploy

🛠 Create a block

• How to create blocks
• How to make a block editable
• How to fetch data
• How to use and extend Core blocks

🗝 Key features / How it works

• Preview
• Styling
• Cache Revalidation
• Aliases
• Helpers
• Blocks Whitelisting
• Forms
• Multilang (TODO)

📚 Resources

• List of blocks
• List of hooks

Learning path

• Learn Next.js in depth https://nextjs.org/learn
• Learn about WPGraphQL https://wpengine.com/builders/everything-you-need-to-know-about-wpgraphql/#schema-and-types
• Follow the logic we built for routing & data fetching, from ./src/app/[[...uri]]/page.tsx

Sources of inspiration

• https://github.com/Automattic/vip-go-nextjs-skeleton
• https://github.com/colbyfayock/next-wordpress-starter

Contact

For bugs or feature requests, open an issue.
For other communication, contact the maintainers at tech@superhuit.ch