Hashnode Headless CMS: Starter-kit

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 value engineering.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 at https://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 is https://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 and blogBaseUrl in the script with your specific values.

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!