This headless starter kit is based on the Kirby Headless Starter and provides a ready-to-use headless Kirby setup for the Cacao Kit frontend. Demo content is included to showcase the starter's features.
With this Kirby project setup, every page-related component is a block. By default, the frontend fetches the same page query for every page and renders the blocks or layouts accordingly. This way, the backend defines the content structure while the routing doesn't have to be re-implemented in the frontend.
Of course, you can also use custom Kirby fields in your blueprint and create Nuxt pages in the frontend with custom queries. See the about page for an example.
If the block-first architecture doesn't fit your needs, you can still build upon this starter and use Kirby's built-in blocks. See the cookbook for more information.
- PHP 8.0+
Kirby is not a free software. You can try it for free on your local machine but in order to run Kirby on a public server you must purchase a valid license.
Kirby-related dependencies are managed via Composer and located in the vendor
directory. To install them, run:
composer install
Duplicate the .env.development.example
as .env
:
cp .env.development.example .env
It's recommended to secure your API with a token. To do so, set the environment variable KIRBY_HEADLESS_API_TOKEN
to a token string of your choice.
Also, to enable the preview button in the frontend, set the environment variable KIRBY_HEADLESS_FRONTEND_URL
to the URL of your frontend deployment:
📖 Read the Kirby Headless Starter documentation, from which this starter is based on.
By default, every page-related component is a block. The blocks
field blueprint defines the blocks that are available for each page. It contains page-building blocks like a notes grid, but also the prose
block, which is used to render WYSIWYG content (it's another blocks' field under the hood).
If you don't want to nest blocks, you can add Kirby's built-in block fieldsets
to the blocks
field blueprint.
If you prefer to use a block-first approach, you can add new blocks to your Kirby project by following these steps:
- Create a new blueprint in the
site/blueprints/blocks
directory. - Add the new block to the
blocks
field blueprint. - Finally, follow the block guide in the Cacao Kit frontend.
ℹ️ If the new block contains a
files
field, make sure to follow thetoResolvedBlocks()
field method guide if you want to resolve image UUIDs to file objects on the server.
ℹ️ See ploi-deploy.sh for exemplary deployment instructions.
ℹ️ Some hosting environments require uncommenting
RewriteBase /
in.htaccess
to make site links work.
MIT License © 2023-present Johann Schopplich