Hashnode Headless CMS lets developers use Hashnode’s content management tools while fully customizing the frontend of their blogs or websites. With Hashnode’s editor and dashboard, you can manage content while delivering it through a unique, developer-built frontend using your preferred technologies.
To simplify this process, we provide a Blog Starter Kit, a ready-to-deploy solution using Next.js and Tailwind CSS. It works seamlessly with Hashnode Headless CMS, allowing you to create and deploy a fully customizable blog that can be hosted anywhere, including on a custom domain subpath.
Step 1: Deploy to Vercel
-
Start by forking the repository of the Hashnode Blog Starter Kit.
-
Create a New Project on Vercel and import the forked repository. Then choose "Next.js" as the framework preset
-
The repository is a monorepo, so select one of the following as the root directory during the Vercel project setup:
-
-
packages/blog-starter-kit/themes/enterprise
-
packages/blog-starter-kit/themes/hashnode
-
packages/blog-starter-kit/themes/personal
-
-
Live demos of the themes available from the starter kit
- Set the necessary environment variables as per your project requirements.
NEXT_PUBLIC_HASHNODE_GQL_ENDPOINT=https://gql.hashnode.com
NEXT_PUBLIC_HASHNODE_PUBLICATION_HOST=engineering.hashnode.com
NEXT_PUBLIC_BASE_URL=/blog
NEXT_PUBLIC_MODE=production
-
NEXT_PUBLIC_HASHNODE_GQL_ENDPOINT=https://gql.hashnode.com
: This variable specifies the GraphQL endpoint used to interact with Hashnode’s APIs. -
NEXT_PUBLIC_HASHNODE_PUBLICATION_HOST=engineering.hashnode.com
: This is the domain of your Hashnode blog; ensure the valueengineering.hashnode.com
is replaced with your blog URL. -
NEXT_PUBLIC_BASE_URL=/blog
(Optional): This value defines the root path of your blog on your website. For example, if you'd like your blog to be accessible at https://yourdomain.com/blog, this variable should be set to/blog
. -
NEXT_PUBLIC_MODE=production
: This variable indicates that the application is running in a production environment. It can be set to development during local development to enable debugging and other development-specific features.
-
Once deployed, visit the auto-generated Vercel domain to ensure everything is working correctly.
-
Add a Custom Domain or Subdomain to the project (optional).
Step 2: (Optional) Subpath Installation
If you'd like to host your headless blog under a specific subpath of an existing domain, such as your portfolio website (mywebsite.com/blog), rather than using a separate domain or subdomain, follow the steps below. This setup is optional and useful if you want to keep your blog within the structure of a larger site rather than on a separate domain or subdomain.
Note the environment variable is needed for this step: NEXT_PUBLIC_BASE_URL=/blog
Vercel Setup for Subpath Installation
-
If your main project (e.g. your portfolio Next.js app codebase) is deployed on Vercel, add the following rewrite rules to the
next.config.js
file of your main project:async rewrites() { return [ { source: "/blog", destination: "https://starter-kit-rose-seven.vercel.app/blog", -> Replace https://starter-kit-rose-seven.vercel.app with your own Vercel deployment URL from step 1 }, { source: "/blog/:path*", destination: "https://starter-kit-rose-seven.vercel.app/blog/:path*", -> Replace https://starter-kit-rose-seven.vercel.app with your own Vercel deployment URL from step 1 }, ]; },
Replace
https://starter-kit-rose-seven.vercel.app
with your actual Vercel deployment URL. -
Ensure these rewrites are added to the codebase of your main project (e.g.,
https://portfolio.com
if your blog will be athttps://portfolio.com/blog
).
Note:
-
If you are updating your environment variables in Vercel, make sure to manually redeploy to see the changes.
-
Your main project is the site where your blog subpath will be hosted. For example, if your blog is at
https://portfolio.com/blog
, your main project ishttps://portfolio.com
. The rewrites function should be added to the main project's codebase, not the starter kit codebase.
Cloudflare Setup for Subpath Installation
If you're using Cloudflare in proxy mode, follow these steps:
-
Deploy a Worker Script using the following script below:
const subpath = '/blog'; // Replace with your subpath const blogBaseUrl = 'https://blog-woad-six-17.vercel.app'; // Replace with your blog URL addEventListener('fetch', event => { event.respondWith(handleRequest(event.request)) }) /** * Respond to the request * @param {Request} request */ async function handleRequest(request) { const url = new URL(request.url) if (url.pathname.startsWith(subpath)) { // Proxy blog requests return proxyBlog(request) } else { // Passthrough everything else return fetch(request) } } /** * Proxy blog requests * @param {Request} request */ async function proxyBlog(request) { const path = new URL(request.url).pathname; return fetch(`${blogBaseUrl}${path}`, request) }
- Ensure you replace
subpath
andblogBaseUrl
in the script with your specific values.
- Ensure you replace
-
Add a Worker Route:
-
Go to Websites > Select your website > Worker Routes.
-
Add a new route like
https://yourdomain/*
and select the worker you created.
-
-
Access your blog from your domain and the subpath
https://yourdomain/yoursubpath
to view your blog.
If your main domain is hosted elsewhere, involve your engineering team in implementing the rewrites.
Step 3: Configure Hashnode as Headless CMS
-
Enable Headless Mode:
-
Go to your Hashnode blog dashboard and navigate to the Domain tab.
-
Select the "Hashnode headless CMS" tab and enable headless mode.
-
2. Save the Blog Base URL
Conclusion
By following these steps, you’ll have a fully customized blog using Hashnode’s Blog Starter Kit, whether you’re deploying to a custom domain, a subpath, or running it locally. Congrats 🎉! Hashnode will now treat your blog as a headless blog and send readers directly to the origin. Happy blogging!