This example showcases Next.js's Static Generation feature using Umbraco CMS as the data source.

Execute create-next-app with npm or Yarn to bootstrap the example:

npx create-next-app --example cms-umbraco umbraco-app
# or
yarn create next-app --example cms-umbraco umbraco-app
# or
pnpm create next-app --example cms-umbraco umbraco-app

Use the .NET CLI to create a project locally.

1. Create an empty folder and open a terminal there.
2. If you haven't already, install the Umbraco .NET CLI templates for version 12.0 or above by running: dotnet new install Umbraco.Templates::13.*.
3. Create the Umbraco project by running: dotnet new umbraco

For more information on the Umbraco .NET CLI templates, visit this page.

To avoid having to create the entire blog dataset in hand, we have created a NuGet package with everything you need to get started.

Install the NuGet package with the following command in the terminal window: dotnet add package Umbraco.Sample.Headless.Blog.

The Umbraco Delivery API will be the data source for the blog. This API must be enabled explicitly.

Open appsettings.json and add the DeliveryApi configuration inside Umbraco::CMS:

  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "ApiKey": "my-secret-api-key"
      },
      ....

The ApiKey configuration is optional, though necessary if you want to use the preview functionality of the blog sample.

Start Umbraco with the following command in the terminal window: dotnet run.

Follow the installation wizard to complete the Umbraco setup.

Once completed you'll be redirected to the Umbraco backoffice where the blog sample data is already installed.

All the sample content is unpublished to begin with. You need to publish all of it to show the blog posts on the blog.

1. Click the Posts item in the Content tree. This item contains all the individual blog posts.
2. In the lower right hand corner of the browser you'll find a green button labelled "Save and publish".
3. Click the little up-arrow next to this button and select "Publish with descendants...".
4. In the dialog, tick "Include unpublished content items" to publish the Posts item and all the blog posts in one go.

Now do the same for the Authors item.

Locate .env.local.example where you created the umbraco-app project. Create a copy of the file and name it .env.local. Now edit the file and fill in the blanks.

• UMBRACO_SERVER_URL: The base URL of your Umbraco site. Avoid trailing slashes here.
• UMBRACO_DELIVERY_API_KEY: The API key you configured in appsettings.json. This is only necessary if you want to test Preview Mode.
• UMBRACO_PREVIEW_SECRET This can be any random string (but avoid spaces), like my-preview-secret. This is used for triggering preview, thus only necessary if you want to test Preview Mode.

The file should end up looking something like this:

NODE_TLS_REJECT_UNAUTHORIZED=0
UMBRACO_SERVER_URL = 'https://localhost:12345'
UMBRACO_DELIVERY_API_KEY = 'my-secret-api-key'
UMBRACO_PREVIEW_SECRET = 'my-preview-secret'

Notice the NODE_TLS_REJECT_UNAUTHORIZED=0 setting. When running a .NET website locally, a self-signed SSL certificate is created to allow HTTPS bindings. Node.js does not trust self-signed SSL certificates, so you need to bypass the SSL/TLS certificate verification with this setting. Do not use this workaround in production.

In the umbraco-app project folder, run:

npm install
npm run dev

# or

yarn install
yarn dev

Your blog should be up and running on http://localhost:3000! If it doesn't work, post on GitHub discussions.

If you edit a post in Umbraco without publishing the changes, you won't see these changes at http://localhost:3000 by default. However, if you enable Preview Mode, you'll be able to see the changes (Documentation).

To enable Preview Mode, go to this URL:

http://localhost:3000/api/preview?secret=<secret>

• <secret> should be the string you entered for UMBRACO_PREVIEW_SECRET in .env.local.

If you browse to the changed post, you will now see the unpublished changes.

To exit Preview Mode go to this URL:

http://localhost:3000/api/exit-preview

You can deploy this app to the cloud with Vercel (Documentation).

Before you can deploy the blog to Vercel, you first need to deploy your Umbraco site to a hosting provider, to make the blog data available for Vercel.

If you use Azure, be sure to read the guidelines on deploying Umbraco to Azure.

You can also try this out on Umbraco Cloud.

To deploy your local project to Vercel, push it to GitHub/GitLab/Bitbucket and import to Vercel.

Important: When you import your project on Vercel, make sure to click on Environment Variables and set them to match your Umbraco deployment.

Alternatively, you can deploy using our template by clicking on the Deploy button below.

This example utilizes the native Content Delivery API in Umbraco to fetch the blog data headlessly.

The Content Delivery API is a feature-rich API for headless content delivery. However, in an effort to keep the complexity down in this sample, certain features and optimizations have been omitted from the API queries. This results in slight over-fetching, particularly when fetching multiple blog posts.

You can read all about the Content Delivery API here.