This is a fully featured template for building performant and scalable content-driven websites with Payload CMS and Astro.
This template is built for multi-language websites and includes SEO metadata, path generation, breadcrumbs, alternate language paths, redirects, media hosting, live preview, Plausible Analytics, robots.txt, and automatic sitemap generation.
Note
This template is still under active development. Features may change, and some functionality may not be fully stable or documented. I welcome feedback and suggestions for improvements.
Follow these steps to set up the project for local development:
-
Clone the repository:
git clone https://github.com/jhb-software/payload-astro-template.git
-
Open two terminals in a split view. One for the Astro website and one for the Payload CMS.
-
In both terminals install the dependencies using
pnpm i. -
Create a
.envfile in both thecmsandwebfolders. You can use the.env.examplefiles as a reference in both folders which contain descriptions for each varialbe. -
Generate and set a secure secret key for the CMS:
- Visit https://payloadsecret.io/ to generate a random 32-byte secret
- Set this as your
PAYLOAD_SECRETin the CMS.envfile
-
Set up MongoDB (if using MongoDB adapter):
- Download and install MongoDB Community Server
- Optional but recommended: Install MongoDB Compass for database management
-
Now you can start the development servers with
pnpm devin both terminals. Start with the CMS and then the website.
The CMS comes with a seed script to populate the database with some example data. To run it, uncomment the code inside the onInit function of your payload.config.ts file.
When adapting this template for your project, consider the following steps:
-
Update the CMS base configuration:
- Update the
websiteName,csrfandresendconfiguration information inpayload.config.tsto match your project details
- Update the
-
Update the website base configuration:
- Update the
websiteConfiginweb/src/config.tswith your project details - Place your logo, favicon and other assets in the
web/publicdirectory
- Update the
-
Customize the CMS:
- Review and modify the collections in
cms/src/collectionsto match your content needs - Add or remove blocks in
cms/src/blocksto match your content needs - Add or remove plugins based on your requirements
- Review and modify the collections in
-
Adapt the website:
- Implement templates for your CMS collections in
web/src/layout/collections - Add Astro components for your CMS blocks in
web/src/components/blocks - Update the files which generate structured data in
web/src/schema.ts
- Implement templates for your CMS collections in
Need help deploying the system or going live? Contact me via email or X to discuss your project requirements and get expert assistance.
This section outlines the key architectural decisions made when building this template. While the template suggests specific approaches for building and hosting the system, you can adapt these to your specific needs.
To improve performance and SEO, this template uses a static Astro website. All pages are pre-rendered at build time and served as static files. To enable previewing changes made in the CMS (Payload Live Preview), this template includes a special preview route that server-side renders (SSR) the pages. More information on the Live Preview feature can be found in the Live Preview section section of this README.
The Astro app could be configured to server-side render all pages on demand with some modifications. To optimize performance, I recommend using Vercel Incremental Static Regeneration (ISR) to benefit from caching and automatically regenerate specific pages when content is added or updated in the CMS.
The template is designed to deploy the website and CMS as separate projects on Vercel. Since Payload runs on Next.js, this provides the simplest and best developer experience for deployment. The Astro app uses the Vercel adapter for deployment.
You can modify the setup to deploy both projects on another provider or self-host them if desired.
Since the website and CMS are deployed as separate projects, I recommend hosting your CMS on a subdomain of your website (e.g., cms.mywebsite.com). This creates a clean separation between the projects and maintains a clear URL structure.
The template uses the Payload MongoDB adapter, but you can use any other database adapter supported by Payload. For database hosting, MongoDB Atlas offers a simple and scalable solution.
The template uses Hetzner S3 Object Storage for media files, providing a cost-effective solution for small to medium-sized websites. For projects with larger budgets, I recommend using an image service with CDN and transformation capabilities like Cloudinary. Plugins are available for integrating Cloudinary with Payload.
The template integrates Plausible Analytics for website analytics. Plausible is a privacy-friendly analytics tool that doesn't track users across websites. You can easily modify or remove this to use a different analytics solution.
The template is designed with cost-effectiveness and scalability in mind. The static website ensures minimal hosting costs and excellent scalability. The CMS deployment on Vercel is cost efficient and scalable, as is MongoDB Atlas for database hosting. Since the site is static, database load occurs only during CMS updates or website builds, not during regular site visits.
Most components can be deployed using free tiers to get started.
Here's an overview of typical costs for a small to medium-sized website:
- Vercel Pro Plan: ≈20 USD/month per seat (see usage and pricing), note that you can host multiple websites on one account
- MongoDB Atlas Flex Tier: ≈8 USD/month per cluster (see usage and pricing)
- Hetzner S3 Object Storage: ≈5 USD/month (see usage and pricing)
For reference, the jhb.software website operates on exactly this setup at these costs.
The CMS is configured to contain all basic features you need for a website.
The official SEO plugin is used to add metadata fields to all pages, including title, description, and social media metadata.
The Payload pages plugin is used to automatically generate paths, breadcrumbs, and alternate language paths for all pages. Documents from multiple collections can be nested to create hierarchical page structures.
A dedicated collection for managing redirects, allowing you to handle old paths and maintain SEO when restructuring your site.
The Astro website is fully static, so the CMS includes a convenient redeploy button that allows content editors to trigger a fresh build of the website with updated CMS data with a single click.
Real-time preview functionality allows content editors to see changes before publishing, improving the content creation workflow.
Comprehensive SEO optimization including meta tags, Open Graph tags, Twitter Cards, and canonical URLs.
Automatic generation of JSON-LD structured data to help search engines understand your content better.
Privacy-friendly analytics integration with Plausible for tracking website performance without compromising user privacy.
Dynamic sitemap generation that updates automatically as you add or modify content, helping search engines discover your pages.
Automatically generated robots.txt file to control search engine crawling behavior.
Server-side redirects handled through the Vercel adapter for fast, SEO-friendly URL redirections.
Automatic generation of alternate language paths for multi-language support, ensuring proper hreflang implementation for international SEO.
If you want to contribute to this project, feel free to fork the repository and create a pull request. I am happy to receive feedback and suggestions for improvements.
If you need assistance with setting up this tech stack or Payload and Astro in general, feel free to contact me via email or X.
If you find this project helpful and would like to support its continued development, consider supporting me via the link below. Your support helps maintain and improve this and my other open-source projects:
