Kickstart Astro

Introduction

Kickstart Astro is a minimal starter that connects Astro applications to Contentstack. The repository uses server-side rendering (SSR) with output:"server" and the @astrojs/node adapter in standalone mode. For more background, see SSR.

Use this starter to set up an Astro app that connects to Contentstack with these preconfigured features:

• The Contentstack Delivery SDK retrieves content.
• Live Preview supports content visualization with SSR-oriented behavior. The app passes URL query parameters to the SDK, and the CMS may refresh the browser when content changes.
• Visual Editor supports on-page editing in preview mode.

What You'll Learn

In this guide, you:

• Provision a stack and sample content by importing a Starter when one is available for this project, or by seeding with the Contentstack CLI
• Optionally deploy the app with Launch and align the environment configuration for local development
• Use the Contentstack Delivery SDK to fetch content from an Astro project
• Configure Live Preview and Visual Editor for preview mode and inline editing
• Configure the app with a .env file and PUBLIC_CONTENTSTACK_* variables. Astro exposes PUBLIC_* variables to the client where applicable
• Connect the local app with delivery tokens and preview tokens from the stack or from Launch mappings

Prerequisites

Before you begin, make sure you have the following:

• Node.js is installed from the Node.js download page at a version that satisfies Astro’s installation requirements for your Astro major version
• A basic understanding of JavaScript or TypeScript, and familiarity with Astro project basics, such as pages and components
• A Contentstack account
• Organization Owner/Admin access to import a Starter, which creates a new stack
• A GitHub account if you deploy with Launch or clone a fork

Choose How to Set Up Your Stack

Use one of the following paths to create a stack with the content model and sample entries that Kickstart Astro expects.

Option 1: Import the Starter and Optionally Deploy with Launch

Use these guides to complete setup:

• Importing a Starter: Import a prebuilt stack and content model
• Refer to the Launch Quick Start Guide with Astro to connect GitHub, deploy the application, configure environment variables, and manage deployments using Contentstack Launch.

Typical outcomes

• A stack with sample content
• A hosted application
• A GitHub repository, if you deploy through Launch

If you use Launch, note that variable names often use prefixes such as CONTENTSTACK_*. For local development in this repository, you will later map those values to PUBLIC_CONTENTSTACK_* keys in .env.

Once your stack or deployment is ready, continue with the local clone and configuration steps below.

Option 2: Create and Seed Your Stack with CLI

The Kickstart Astro project expects content from the shared seed repository contentstack/kickstart-stack-seed. Seeding that repository with the CLI produces the same outcome as a Starter import for local and repeatable setups, such as onboarding or CI.

This approach works well for terminal-first workflows or when you do not use the Marketplace onboarding path.

Note: If you already created a stack from this seed, or from another compatible Kickstart project, you can reuse that stack and skip creating another one.

1. Install the Contentstack globally:

npm install -g @contentstack/cli

2. If you are configuring the CLI for the first time, set your region:

csdx config:set:region EU

3. Sign in, and provide your Contentstack account details when prompted:

csdx auth:login

4. Perform the following steps to get your Organization UID:
   1. Go to Contentstack CMS and Select Administration from the “App Switcher”.
   2. Copy the Organization UID to use with the seed command.
5. Create a stack and seed it from the repository. Replace <ORG_ID> with your organization UID:

csdx cm:stacks:seed --repo "contentstack/kickstart-stack-seed" --org "<ORG_ID>" -n "Kickstart Stack"

After the process completes, the CLI creates a stack, imports the Kickstart content models, and adds sample entries.

Once the seed completes, continue with the local clone and configuration steps below.

Clone the Project and Install Dependencies

For local development, clone the repository you plan to run:

• If you used Launch, clone the repository linked to your deployment from Launch or GitHub
• If you did not use Launch, clone the official repository:

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

In the cloned project folder, run:

npm install

This command installs dependencies to run and build the app locally.

With the local project ready, gather the stack credentials you need for .env.

Get Delivery and Preview Tokens

Gather these values before you update .env. Use the stack you created through the Starter or CLI path earlier. Create a new stack manually only if you are not using those paths. For manual setup, see Create a new stack.

1. Log in to Contentstack and open your stack.
2. Go to Settings > Tokens, and create a new Delivery Token.
3. Ensure the Preview Token is enabled (it is enabled by default).
4. To configure preview, go to Settings > Environment and set the application URL based on where the app runs:
   • Local development: http://localhost:4321/, which is Astro’s default dev server port
   • Hosted (Launch or other): Use your deployment’s public HTTPS origin and path if the app is not served from /. Mismatched origins break Live Preview and Visual Editor, even when delivery content loads.

Additional Resource: Refer to the Create a Delivery Token document for detailed steps.

Once you have these values, add them to the local environment file.

Configure .env for Kickstart Astro

After you have a stack, the required tokens, and a local clone, connect the app to Contentstack.

1. Rename .env.example to .env in the project root, or create .env with the same variables.
2. Add your Contentstack credentials:
   PUBLIC_CONTENTSTACK_API_KEY=<STACK_API_KEY>
   PUBLIC_CONTENTSTACK_DELIVERY_TOKEN=<DELIVERY_TOKEN>
   PUBLIC_CONTENTSTACK_PREVIEW_TOKEN=<PREVIEW_TOKEN>
   PUBLIC_CONTENTSTACK_ENVIRONMENT=preview
   PUBLIC_CONTENTSTACK_REGION=EU
   PUBLIC_CONTENTSTACK_PREVIEW=true

Note: When you set PUBLIC_CONTENTSTACK_PREVIEW=true, the app enables Live Preview behavior in code paths that read this flag.

Credential details

• API key: Get this from your stack, such as Settings > API Keys
• Delivery token / Preview token: Get these from the token you created with preview enabled, or from the equivalent Launch values after you map them to PUBLIC_CONTENTSTACK_* keys
• Environment: Use the publishing environment that the app should read, such as preview or development
• Region: Use the stack region, such as EU, NA, or AZURE-NA, as your account supports it
• Preview: Set this to true to enable Live Preview integration in the app

Note: Free Contentstack developer accounts are commonly bound to the EU region. The CDN routes API requests for responsiveness, but you still need to set PUBLIC_CONTENTSTACK_REGION to match your stack.

How the configuration works

This project uses Astro with Vite. Variables prefixed with PUBLIC_ are available as import.meta.env.PUBLIC_* in server and client code, as described in Astro environment variables. No separate script generates TypeScript environment files from .env. The app reads configuration at development time and build time from .env, and it can read the same names from the process environment in CI.

Optional configuration overrides

You can override the default API hosts with these optional variables. The code supports them even if .env.example does not include them:

• PUBLIC_CONTENTSTACK_CONTENT_DELIVERY
• PUBLIC_CONTENTSTACK_PREVIEW_HOST
• PUBLIC_CONTENTSTACK_CONTENT_APPLICATION

If you omit these variables, @timbenniks/contentstack-endpoints() resolves hosts from PUBLIC_CONTENTSTACK_REGION.

Warning: Do not commit .env to version control. It should remain listed in .gitignore.

With local configuration in place, enable Live Preview in the stack so the CMS and app use matching settings.

Enable Live Preview in the Stack

1. In your stack, go to Settings and navigate to Environments. Select an existing environment or create a new one, and add a Base URL for each locale.
2. Navigate to Visual Experience from the Settings menu and select the Enable Live Preview checkbox.
3. Select the Default Preview Environment that matches your app. For example, if PUBLIC_CONTENTSTACK_ENVIRONMENT=preview, select Preview.
4. Click Save.

Additional Resource: For detailed setup instructions, refer to Set Up Live Preview for Your Stack.

Verify Your Setup

Run the app, and confirm that it loads content from your stack.

Start the development server

1. From the project root, run:
   npm run dev

2. Open http://localhost:4321/ in your browser.

You should see the homepage with:

• A title, description, and image from your stack
• Example modular blocks, such as image and copy blocks

Test Live Preview

Prerequisites to Test Live Preview

• Live Preview is enabled in the stack
• PUBLIC_CONTENTSTACK_PREVIEW=true is set in .env

Steps

1. Edit an entry in Contentstack, such as the homepage.
2. Observe updates in the browser.
   1. Kickstart Astro reads Live Preview query parameters in src/pages/index.astro
   2. These parameters are passed to the Contentstack SDK.
   3. Client-side Live Preview setup is handled by initLivePreview()

This happens because initLivePreview() in src/lib/contentstack.ts wires the app to Contentstack Live Preview update events, so preview content refreshes when entries change.

Tip: Open the entry in the CMS, and then use the Live Preview entry point or Visual Editor so the app runs within the CMS for click-to-edit workflows.

Understand the Codebase

The sections below show where the main integration points live after setup is working.

Project structure

After you install dependencies, the repository follows this structure:

kickstart-astro/
├── src/
│   ├── layouts/
│   │   └── Layout.astro
│   ├── lib/
│   │   ├── contentstack.ts
│   │   └── types.ts
│   ├── env.d.ts
│   ├── pages/
│   │   └── index.astro
│   └── styles/
│       └── global.css
├── public/
│   └── favicon.svg
├── .env.example
├── astro.config.mjs
├── package.json
├── package-lock.json
├── tsconfig.json
├── LICENSE
├── README.md
├── SECURITY.md
├── .github/          # CI and repository metadata
├── .vscode/          # Optional editor recommendations
└── .talismanrc       # Security scanning config

Build and configuration

• Astro config: astro.config.mjs
  • Enables SSR with output: "server"
  • Configures the Node adapter in standalone mode
• Local scripts:
  • npm run dev / npm start: Start the local dev server (astro dev)
  • npm run build: Run type checks, then build for production (astro build)
  • npm run preview: Serve the local production build (astro preview)
• Build output: npm run build
  • Writes the production build to dist/
  • Includes the server and client artifacts that the Node adapter expects
• Package name: package.json
  • Defines the npm package name kickstart-astro
  • Declares the npm scripts and dependencies the starter uses

Key source files

• Contentstack integration: src/lib/contentstack.ts
  • Initializes the Delivery SDK stack client with region and optional custom hosts
  • Configures live_preview when PUBLIC_CONTENTSTACK_PREVIEW is true
  • Exports initLivePreview() for the Live Preview utilities
  • Exports getPage() to load a page entry
  • Adds editable tags in preview mode for the Visual Editor
• Home page: src/pages/index.astro
  • Uses export const prerender = false so the page renders on the server
  • Reads Live Preview search parameters and passes them to getPage()
  • Renders page fields and modular blocks using patterns that work with the Visual Editor
• Type definitions: src/lib/types.ts
  • Defines the Page shape used by the app
  • Describes the nested block types used when the page renders modular content
• Layout shell: src/layouts/Layout.astro
  • Provides the shared page wrapper for routes
• Global styles: src/styles/global.css
  • Defines shared styles used across the app

Troubleshooting Common Issues

Use these checks if the homepage is empty, the SDK cannot authenticate, or Live Preview does not update as expected.

Critical Setup Checks

• Wrong Contentstack region
  • Free developer accounts are often bound to the EU. If PUBLIC_CONTENTSTACK_REGION does not match the stack, API calls can fail, and content can appear empty.
  • Use EU in .env and run csdx config:set:region EU when you work with EU-bound stacks.
• Stack not seeded

  The application expects the page content type and sample entries from the Kickstart stack seed or an equivalent Starter. If the model or entries are missing, the home page may appear empty or fail to resolve /.

• .env is missing or using the wrong prefix

  The project reads PUBLIC_CONTENTSTACK_* variables. If .env is missing, or if the keys do not use the correct Astro prefix, import.meta.env values are empty, and the SDK cannot authenticate.

• Wrong Live Preview or Preview Token base URL

  Local Astro uses http://localhost:4321/ by default. Hosted apps must use the real deployment URL. If you use the wrong origin, Live Preview and Visual Editor break even when delivery works.

• Live Preview is not enabled in the stack

  Enable Live Preview under Settings, and select the environment that matches PUBLIC_CONTENTSTACK_ENVIRONMENT.

Additional Checks

• Committing .env

  Warning: The file contains secrets. Keep it out of git and rely on .gitignore.

• Wrong or swapped delivery and preview tokens

  Use the correct tokens from the stack, or map the correct values from Launch.

• Incorrect publishing environment name

  PUBLIC_CONTENTSTACK_ENVIRONMENT must match an environment that exists in your stack.

• Skipping npm install

  Install dependencies after you clone the repository so scripts and types resolve correctly.

• Querying unpublished or mismatched environment content

  The app reads from the environment named in .env. Content that is unpublished or published to a different environment does not appear.

• Changing the page content type or URL contract without updating the code

  getPage() queries the page content type and matches the URL to the path (e.g., /). If you rename fields or content types in the stack, update the query and types accordingly.

Next Steps

• Learn more about Live Preview and Visual Editor for your workflow
• Extend routing by adding Astro pages and reusing getPage(), or by adding more queries for URLs that exist in your stack
• Review Astro server-side rendering and the Node adapter as you prepare for production hosting

For questions or issues, join the Contentstack Community on Discord.