Next.js — App Router

Welcome! This guide will help you connect your Next.js website to Blogree. We highly recommend this setup for modern Next.js projects (version 13.4 and newer) that use the app/ folder structure.

Estimated setup time: 8 minutes

1. Install the Adapter

First, we need to add the official Blogree toolkit to your project. Open your computer's terminal (or the terminal panel built into VS Code), make sure you are inside your project folder, and run this command:

npm install @blogree/nextjs-adapter

2. Setup Your Secret Passwords (Environment Variables)

Your website needs secure keys to talk to Blogree. We store these in a hidden file so they don't accidentally get shared.

1. Go to the very main folder of your project (the root directory) and create a new file named exactly .env.local.
2. Next, go to your Blogree dashboard by visiting app.blogree.com.
3. Navigate to Sites, click on your site, and go to the Settings tab to find your API keys.
4. Copy those keys and paste them into your new .env.local file like this:

BLOGREE_API_KEY=bk_live_xxxxxxxxxxxxxxxxxxxx
BLOGREE_API_URL=https://api.blogree.com
BLOGREE_WEBHOOK_SECRET=whs_xxxxxxxxxxxxxxxxxxxx

3. Create the Webhook (The Auto-Updater)

A "webhook" is like a secret phone line between Blogree and your website. When you click "Publish" in Blogree, it calls this file to tell your website to update instantly—without you having to rebuild your site!

Let's build that phone line. In your code editor:

• Open the app folder.
• Inside it, create a new folder called api.
• Inside api, create a folder called blogree.
• Finally, inside blogree, create a file named route.ts.

Paste this exact code into that new file:

import { createWebhookHandler } from '@blogree/nextjs-adapter';
import { revalidatePath } from 'next/cache';

export const POST = createWebhookHandler(
  {
    apiKey: process.env.BLOGREE_API_KEY!,
    apiUrl: process.env.BLOGREE_API_URL!,
    webhookSecret: process.env.BLOGREE_WEBHOOK_SECRET!,
  },
  async (payload) => {
    // This tells Next.js to clear out the old pages and grab your new article
    revalidatePath('/blog');
    revalidatePath(`/blog/${payload.post.slug}`);
  }
);

4. Create Your Blog Page (The Listing)

Now let's actually show your blog posts to the world. We need to create a page that lists all of your articles.

Open your app folder, create a new folder named blog, and inside it, create a file named page.tsx. Paste this code:

import { getBlogreePosts } from '@blogree/nextjs-adapter';
import type { BlogreePost } from '@blogree/nextjs-adapter';
import Link from 'next/link';

export default async function BlogPage() {
  // This securely fetches your latest articles from Blogree
  const posts: BlogreePost[] = await getBlogreePosts({
    apiKey: process.env.BLOGREE_API_KEY!,
    apiUrl: process.env.BLOGREE_API_URL!,
  });

  return (
    <main className="p-8">
      <h1 className="text-3xl font-bold mb-6">Our Latest Articles</h1>
      <div className="flex flex-col gap-6">
        {posts.map((post) => (
          <article key={post.slug} className="border p-4 rounded-lg">
            <h2 className="text-xl font-semibold">
              <Link href={`/blog/${post.slug}`} className="hover:underline">
                {post.title}
              </Link>
            </h2>
            <p className="text-gray-600 mt-2">{post.excerpt}</p>
          </article>
        ))}
      </div>
    </main>
  );
}

5. Create the Individual Article Page

When someone clicks on an article from your list, they need a page to read it on. Next.js uses brackets [slug] to create dynamic templates for things like blog posts.

Inside your app/blog folder, create a new folder named exactly [slug]. Inside that folder, create a page.tsx file and paste this code:

import { getBlogreePost } from '@blogree/nextjs-adapter';
import { notFound } from 'next/navigation';

export default async function SinglePostPage({ params }: { params: { slug: string } }) {
  // Fetch the specific post the user clicked on
  const post = await getBlogreePost(params.slug, {
    apiKey: process.env.BLOGREE_API_KEY!,
    apiUrl: process.env.BLOGREE_API_URL!,
  });

  // If the post doesn't exist, show a 404 error page
  if (!post) {
    notFound();
  }

  return (
    <article className="max-w-3xl mx-auto p-8 prose">
      <h1>{post.title}</h1>
      <time className="text-gray-500">
        Published on {new Date(post.published_at).toLocaleDateString()}
      </time>
      
      {/* This renders the actual blog content you wrote in Blogree */}
      <div 
        className="mt-8"
        dangerouslySetInnerHTML={{ __html: post.body.html }} 
      />
    </article>
  );
}

6. Final Step: Tell Blogree Where Your Website Is

Your code is completely ready! Now you just have to tell Blogree where to send those webhook updates when you hit publish.

1. Go back to app.blogree.com.
2. Go to Sites → select your site → find the Webhook URL field.
3. Paste in your live website's API address. It should look like this:

https://your-actual-website.com/api/blogree

Click Verify Webhook. Blogree will send a quick test signal to your site. If it says "Verified," you are completely done! Your blog is now fully automated.

Troubleshooting (FAQ)

My website isn't updating when I publish a new post!

Check your deployment platform (like Vercel or Netlify). You added your `.env.local` variables to your personal computer, but you also need to add those exact same variables in the settings dashboard of your hosting provider!

The HMAC signature is failing.

This means your BLOGREE_WEBHOOK_SECRET is incorrect. Go to your Blogree dashboard, copy the secret again, and paste it directly into your environment variables. Do not type it manually.

My Webhook URL says "Not Found" when I verify it.

Double-check that you named the folders correctly in Step 3. It must be exactly app/api/blogree/route.ts. Also, make sure you pushed your code to your live server before clicking "Verify" in the dashboard!