cs-icon.svg

Kickstart Nuxt

This guide walks you through setting up and running a Nuxt project integrated with Contentstack. It's designed for developers who are new to Nuxt or Contentstack.

Hero image for Constentstack Kickstart Nuxt Implementation

Prerequisites

  • Node.js version > 22 installed on your machine
  • Basic understanding of JavaScript and/or TypeScript
  • Contentstack account

Project Setup

1. Clone the Repository

Clone the project repository from GitHub:

git clone https://github.com/contentstack/kickstart-nuxt.git
cd kickstart-nuxt

Github for Frontend Nuxt App: Contentstack Kickstart - Nuxt

2. Install Dependencies

Install the required dependencies and packages:

npm install

Project Structure

After you clone the repo and install dependencies, your project should resemble the following structure:

#kickstart-nuxt
- 📁 composables/
  - 📄 useGetPage.ts
- 📁 plugins/
  - 📄 contentstack.ts
- 📁 public/
  - 📄 favicon.ico
  - 📄 robots.txt
- 📁 server/
  - 📄 tsconfig.json
- 📄 .env.example
- 📄 app.vue
- 📄 nuxt.config.ts
- 📄 package-lock.json
- 📄 package.json
- 📄 tsconfig.json
- 📄 types.ts
- 📄 README.md

3. Create a Stack

Log in to your Contentstack account and create a new Stack. Follow these steps to seed your Stack with the necessary data:

  1. Download the Stack seed data from GitHub.
  2. Install the Contentstack CLI:
    npm install -g @contentstack/cli
  3. If you are running the CLI for the first time, set your region:
    csdx config:set:region EU
    Note:
    • North America: Set the region as NA.
    • Europe: Set the region as EU.
    • Azure North America: Set the region as AZURE-NA.
    • Azure Europe: Set the region as AZURE-EU.
    • Google Cloud Platform North America: Set the region as GCP-NA.
    • Google Cloud Platform Europe: Set the region as GCP-EU.
  4. Log in via the CLI:
    csdx auth:login

    This command will ask you to provide your Contentstack’s account credentials (email and password).

  5. Get your Organization ID from the Contentstack dashboard: Go to Org Admin > Info and copy the Org IDget-orgID.png
  6. Seed your Stack:
    csdx cm:stacks:seed --repo "contentstack/kickstart-stack-seed" --org "<YOUR_ORG_ID>" -n "CS Kickstart Nuxt"

Need more information, watch a quick video on how to seed a stack in the CLI.

4. Create a Delivery Token

In you stack, go to Settings > Tokens in your Contentstack dashboard and create a delivery token with the preview setting toggled to On.
Alternatively, watch a quick step-by-step tutorial on How to create delivery tokens.

5. Setup environment variables

Create a .env file in the root of your project and add your Contentstack credentials:

NUXT_PUBLIC_CONTENTSTACK_API_KEY=<YOUR_API_KEY>
NUXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=<YOUR_DELIVERY_TOKEN>
NUXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=<YOUR_PREVIEW_TOKEN>
NUXT_PUBLIC_CONTENTSTACK_REGION=<YOUR_REGION_NAME>
NUXT_PUBLIC_CONTENTSTACK_ENVIRONMENT=<ENVIRONMENT_NAME>
NUXT_PUBLIC_CONTENTSTACK_PREVIEW=true
#By default the live preview feature is enabled for this project.

For more information on environments and setting up delivery tokens, watch the Understanding Environments Contentstack Academy video.

6. Turn on Live Preview

Go to Settings > Live Preview in your Contentstack dashboard. Enable it and select the Preview environment.

7. Run Your Nuxt App

Start the development server from your kickstart-nuxt project directory in the terminal:

npm run dev

Open http://localhost:3000 in your browser to see your app in action.

Tip: You can Command + Click or Enter to open up the Localhost URL in the browser. You Nuxt app should resemble the following:

Screenshot_2025-04-17_at_09.56.04.png

Kickstart guide video

Want to see this Nuxt guide in action? Check out this kickstart video!

Key Files and Code Breakdown

Let's quickly go over a few key files and the code.

Contentstack SDK

File name: plugins/contentstack.ts

This file initializes the Contentstack Delivery SDK and provides helper functions to fetch data:

/**
 * Contentstack Delivery SDK plugin
 * 
 * This plugin initializes the Contentstack Delivery SDK and Live Preview functionality
 * Key Features:
 * 1. Sets up the Contentstack stack instance with provided configuration
 * 2. Configures live preview with edit button functionality
 * 3. Provides the stack instance and preview utilities to the application
 * 
 * Configuration is loaded from the Nuxt public config and includes:
 * - API Key
 * - Delivery Token
 * - Preview Token
 * - Region
 * - Environment
 * - Preview mode flag
 */

// Imports
import contentstack, { Region } from "@contentstack/delivery-sdk"
import ContentstackLivePreview, { type IStackSdk } from "@contentstack/live-preview-utils";
import { getContentstackEndpoints, getRegionForString } from "@timbenniks/contentstack-endpoints";

export default defineNuxtPlugin((nuxtApp) => {
  const {
    apiKey,
    deliveryToken,
    previewToken,
    region,
    environment,
    preview
  } = nuxtApp.$config.public;

  const regionEnum: Region = getRegionForString(region)
  const endpoints = getContentstackEndpoints(regionEnum, true)

  const stack = contentstack.stack({
    apiKey,
    deliveryToken,
    environment,
    region: regionEnum,
    live_preview: {
      enable: preview ? true : false,
      preview_token: previewToken,
      host: endpoints.preview
    }
  });

  if (preview && import.meta.client) {
    ContentstackLivePreview.init({
      ssr: false,
      mode: "builder",
      enable: preview ? true : false,
      stackSdk: stack.config as IStackSdk,
      stackDetails: {
        apiKey: apiKey,
        environment: environment,
      },
      clientUrlParams: {
        host: endpoints.application
      },
      editButton: {
        enable: true,
        exclude: ["outsideLivePreviewPortal"]
      }
    });
  }

  return {
    provide: {
      stack,
      preview,
      ContentstackLivePreview
    },
  };
});

Contentstack Data Query

File name: composables/getPageData.ts

This file contains the async function that queries Contentstack to fetch all page data. In addition, a conditional is added to check if you are in preview mode and if so, add editable tags to the fetched entry.

/**
 * Retrieve Contentstack Page Data
 * 
 * This composable fetches and manages page data from Contentstack using Nuxt's composables.
 * It supports both regular content delivery and live preview functionality.
 * 
 * Features:
 * - Fetches page content based on URL parameter
 * - Supports Contentstack Live Preview mode
 * - Handles data fetching with Nuxt's useAsyncData
 * - Implements type-safe Contentstack queries
 * - Adds editable tags for content management
 * 
 * Note: This composable automatically handles preview mode when the 'live_preview' query parameter is present.
 */

// Imports 
import contentstack, { QueryOperation, type LivePreviewQuery } from "@contentstack/delivery-sdk"; 
import type { Page } from "~/types"; 

// Define an asynchronous function to fetch page data based on the URL
export const useGetPage = async (url: string) => {
  // Use the useAsyncData hook to fetch data and manage its state
  const { data, status, refresh } = await useAsyncData(`page-${url}`, async () => {
    // Get the Nuxt app instance and the current route
    const { $preview, $stack } = useNuxtApp()
    const route = useRoute()
    const qs = { ...toRaw(route.query) } // Convert the route query to a raw object

    // Check if preview mode is enabled and if live preview query parameter is present
    if ($preview && qs?.live_preview) {
        $stack.livePreviewQuery(qs as unknown as LivePreviewQuery) 
    }
    // Fetch the page data from Contentstack
    const result = await $stack
       // Specify the content type as 'page'
      .contentType("page")
       // Access the entries of the content type 
      .entry()
      // Create a query to filter the entries 
      .query()      
      // Filter entries where the 'url' field matches the provided URL 
      .where("url", QueryOperation.EQUALS, url)      
      // Execute the query and cast the result to the Page type 
      .find<Page>(); 

    // Check if there are any entries in the result
    if (result.entries) {       
       // Get the first entry from the result
      const entry = result.entries[0]
       // If preview mode is enabled, add editable tags to the entry
      if ($preview) {
        contentstack.Utils.addEditableTags(entry as Page, 'page', true);
      }
     // Return the entry as the data
      return entry; 
    }

  });
  // Return the data, status, and refresh function from useAsyncData
  return { data, status, refresh }
}

Quick Tip: API Endpoint helper package

You can use the Contentstack Endpoints NPM package to gather all the API endpoints you need to deliver content. For more details on how the package works, check out this explainer video!

Now, let's jump into how the main Nuxt component works.

Main Nuxt component

File name: app.vue

The app.vue is the main Nuxt application file where live preview is integrated and fetched data from Contentstack is populated into your markup inside the template tag.

You now have a basic understanding of how to set up and run a Nuxt project integrated with Contentstack. If you have any questions or run into an error, join the Contentstack Community in Discord for further support.

Was this article helpful?

More articles in "Set up Guides"

Set up Live Preview with GraphQL for Client-side Rendering (CSR)

Learn more

Set up Live Preview with GraphQL for Server-side Rendering (SSR)

Learn more

Set up Live Preview for Gatsby-powered Sites

Learn more

Set up Live Preview with REST for Client-side Rendering (CSR)

Learn more

Set up Live Preview with REST for Server-side Rendering (SSR)

Learn more

Set up Live Preview for Static-Site Generator (SSG)

Learn more

Set up Live Edit Tags for Entries with REST

Learn more

Live Preview Implementation for NextJS SSR App Router

Learn more

Live Preview Implementation for ReactJS CSR App Router

Learn more

Live Preview Implementation for NextJS CSR App Router

Learn more

Migrate to Preview Service

Learn more
^