Storyblok Core Space Blueprint: Astro

Integrate Astro with Storyblok as a headless CMS.

This blueprint is ideal for kickstarting new Storyblok and Astro projects. What's inside:

• Pre-configured default blocks: page, teaser, grid, and feature.
• Support for the Visual Editor's live preview.
• Dynamic routing to fetch and render new stories automatically.
• Minimal styling.

Tip

Follow our Astro guide for a step-by-step walkthrough and learn more about Storyblok's range of features, including rich text rendering, custom content modeling, and internationalization. See the @storyblok/astro package reference for further information.

---

Get Started

No Storyblok account yet? Sign up now to experience a 14-day free trial of all features and enjoy our completely free Starter plan.

1. Create a new empty Storyblok space
2. Create a new repository based on this template
3. Open the project on your device
4. Install dependencies

npm install

Authentication

In the root of the project, create a .env file to store the access token of your space:

STORYBLOK_DELIVERY_API_TOKEN=<REPLACE_WITH_YOUR_TOKEN>
STORYBLOK_REGION=<REPLACE_WITH_SPACE_REGION>

Tip

Copy your space's preview access token from Settings > Access Tokens. STORYBLOK_REGION defaults to eu if omitted; valid values are eu, us, ca, ap. Learn more about Storyblok access tokens.

Connect the Visual Editor

The Visual Editor lets content editors preview changes in real time while editing content in the Storyblok dashboard. To render a preview of the local project in the Visual Editor, follow these steps:

1. In your space, navigate to Settings > Visual Editor.
2. Set the default environment to https://localhost:4321/.
3. Save.
4. Open the home story.
5. Click Config.
6. Type / in the Real path.

Run the development server:

npm run dev

Important

To connect the Storyblok Visual Editor, the local project must run over HTTPS. Learn more in the Visual Editor concept. Check the Visual Preview section of the Astro guide for detailed instructions.

Back in Storyblok, open the Home story to start editing.

Happy building!

Architecture Overview

The site is statically built from Storyblok content and served via AWS CloudFront.

flowchart LR
    Editor["Storyblok Visual Editor"] --> API["Storyblok CDN API"]
    API --> Build["Astro Build (GitHub Actions)"]
    Build --> S3["S3 Bucket"]
    S3 --> CF["CloudFront CDN"]
    CF --> User["End User"]

Loading

Prerequisites

• Node.js 20+
• npm
• A Storyblok account
• OpenTofu / Terraform (only for infrastructure changes)
• AWS CLI configured (only for infrastructure changes)

Project Structure

src/
  layouts/Layout.astro        # Base HTML layout
  pages/[...slug].astro       # Dynamic catch-all route
  storyblok/                  # Astro components mapped to Storyblok blocks
    Page.astro
    Grid.astro
    Feature.astro
    Teaser.astro
infra/                        # AWS infrastructure (OpenTofu)
.github/workflows/            # CI/CD pipelines
astro.config.mjs              # Astro + Storyblok SDK configuration

Adding a New Component

1. Create the content block in Storyblok's Block Library.
2. Create a matching .astro file in src/storyblok/.
3. Register it in the components map in astro.config.mjs.
4. Use storyblokEditable(blok) on the root element.

Deployment

• Pushing to main triggers the deploy workflow: build, S3 sync, CloudFront cache invalidation.
• Content updates in Storyblok require a new build to go live (no automatic webhook rebuilds).
• Required GitHub Actions secrets: AWS_DEPLOY_ROLE_ARN, AWS_REGION, STORYBLOK_DELIVERY_API_TOKEN.
• See infra/README.md for initial AWS infrastructure setup and bootstrap instructions.

Available Scripts

• npm run dev — start development server (HTTPS via mkcert)
• npm run build — build static site to dist/
• npm run preview — preview the built site locally

Resources

• To learn more about what you can do with Storyblok, visit our documentation and learning hub.
• To learn more about the integration between Storyblok and Astro, check our dedicated developer tutorials.
• To learn more about Astro, check the official documentation.
• Infrastructure documentation

Support

• Have questions, need help, want to chat with other users? Join our Discord community.
• Visit the Storyblok Help Center.