DEV Community: Manuel Schröder

Announcing a Storyblok Loader for the Astro Content Layer API

Manuel Schröder — Thu, 19 Sep 2024 13:26:56 +0000

We are very excited to announce that the latest alpha version of our Astro integration @storyblok/astro now supports the new Astro Content Layer API. The Content Layer API is an innovative new solution to fetch and handle content from external APIs and store it locally. It is designed to scale efficiently and handle large sites with thousands of pages highly performantly. With our new, built-in Storyblok loader, fetching your stories and turning them into an Astro Content Collection is simple and straightforward to accomplish.

How to use it

First of all, install the latest alpha version of our integration in your Astro project:

npm i @storyblok/astro@alpha

As this is an experimental opt-in feature, you need to enable it by setting contentLayer to true in your astro.config.mjs file.

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: "your-access-token",
      contentLayer: true,
    }),
  ],
  experimental: {
    contentLayer: true,
  },
});

Next, in the src/content folder, you need to create a config.ts file that defines one or more collections that consist of the entirety of stories available in your Storyblok space.

import { storyblokLoader } from "@storyblok/astro";
import { defineCollection } from "astro:content";

const storyblokCollection = defineCollection({
  loader: storyblokLoader({
    accessToken: "your-access-token",
    apiOptions: {
      region: "us",
    },
    version: "published",
  }),
});

export const collections = {
  storyblok: storyblokCollection,
};

Let’s look at an example […slug].astro dynamic route that renders the content entries stored in a collection.

---
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";
import BaseLayout from "../layouts/BaseLayout.astro";
import { getCollection } from "astro:content";
import { type ISbStoryData } from "@storyblok/astro";

export async function getStaticPaths() {
  const stories = await getCollection("storyblok");

  return stories.map(({ data }: { data: ISbStoryData }) => {
    return {
      params: { slug: data.full_slug },
      props: { story: data },
    };
  });
}

interface Props {
  story: ISbStoryData;
}

const { story } = Astro.props;
---

<BaseLayout>
  <StoryblokComponent blok={story.content} />
</BaseLayout>

Benefits of using Storyblok with the Astro Content Layer API

The Astro Content Layer API stores all stories of a Storyblok space locally in the project. This approach provides two benefits:

Only new and updated stories have to be fetched from Storyblok instead of fetching all stories with every build. Especially with large-scale sites with thousands of pages, this can significantly reduce API traffic and reduce build times.
Direct access to the database provides a powerful query API to perform complex search and filtering operations.

The Astro Content Layer API is designed to work with Static Site Generation (SSG). Therefore, it is a perfect approach to consider for the production environment of a Storyblok project. You can learn more about deploying Storyblok projects in this tutorial.

Next steps

We hope you’re excited to try out this new feature! We would absolutely love to see your projects built with Storyblok and Astro, and hear your feedback about our experimental support of the new Content Layer API.

Would you like to contribute to the development of @storyblok/astro? Feel free to create an issue or a PR in the official GitHub repository.

Announcing Live Preview for Storyblok’s Astro Integration

Manuel Schröder — Thu, 13 Jun 2024 15:31:35 +0000

We are absolutely thrilled to announce that starting with version 4.1.0 our Astro integration @storyblok/astro now officially supports the live preview functionality of Storyblok’s beloved Visual Editor. With this new feature, developers can empower editors to create content in Astro projects and benefit from real-time, instantaneous feedback reflecting their changes. Let’s see it in action:

How to Use it

As this is an experimental, opt-in feature, you first of all need to enable it by setting livePreview to true in your astro.config.mjs file.

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: "your-access-token",
      livePreview: true,
    }),
  ],
});

Since the live preview feature depends on the Astro object, we’ve designed a new utility function called useStoryblok that takes it as a parameter. Additionally, you may want to pass Storyblok Bridge Options for a particular page or route as a parameter. Let’s take a look at an example:

---
import { useStoryblok } from "@storyblok/astro";
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";

const { slug } = Astro.params;

const story = await useStoryblok(
  // The slug to fetch
  `cdn/stories/${slug === undefined ? "home" : slug}`,
  // The API options
  {
    version: "draft",
  },
  // The Bridge options (optional, if an empty object, null, or false are set, the API options will be considered automatically as far as applicable)
  {},
  // The Astro object (essential for the live preview functionality)
  Astro
);
---

<StoryblokComponent blok={story.content} />

Finally, make sure that your project runs in SSR mode for the live preview functionality to work. For further information, you may want to read our tutorial on how to create a dedicated preview environment for a Storyblok and Astro project.

And that’s it, just like that, you enabled live preview!

How it Originated

When we released the first version of @storyblok/astro in 2022, we were aware that, in direct comparison to the other integrations provided as part of our JavaScript SDK ecosystem, the Astro integration does not offer the benefit of real-time visual feedback. As Astro differs fundamentally from other modern JavaScript frameworks and does not provide a client-side runtime for its native components (which, of course, is part of its allure), the time-proven approach we utilize for other frameworks is not applicable in an Astro context. While we had always envisioned and hoped to be able to introduce support for this integral Storyblok feature, we had concluded that it was not technically feasible.

It took the ingenious effort of one of our closest partners, Virtual Identity, and, in particular, their developer Mario Hamann, to prove us (very!) wrong. Virtual Identity Board Member Timo Mayer and Mario Hamann reached out to us and presented a POC that follows a very creative and masterfully designed approach. In close collaboration, Mario Hamann and our own Dipankar Maikap refined, tested, and integrated this solution. We are truly grateful to Virtual Identity for not only providing this innovative impetus but even going above and beyond to dedicate their time and effort in order to get this market-ready. In any case, we know which super talented team we would turn to again to solve an almost impossible challenge.

How it Works Under The Hood

In a nutshell, this approach works by updating the DOM using the JavaScript replaceWith() method. The DOM is replaced either entirely or partially, depending on the context in which the input event of the Storyblok Bridge is triggered. Thanks to the power and flexibility of Astro’s Integration API, the Astro object can be utilized to store the most up-to-date story data delivered by the Storyblok Bridge. Furthermore, an injected middleware determines whether to load a story normally or update the DOM, taking into account the data stored in the Astro object.

While this method has proven to work incredibly well in the majority of our tests, it is important to point out that you may encounter performance drawbacks in large-scale projects with complex relations to resolve and/or heavy client slide scripts. Hence, we’ve released it as an experimental, opt-in feature for now. If you experience any issues, we’d really appreciate it if you created an issue on GitHub. We rely on your feedback and are more than happy to look into it.

If you want to explore it yourself, the key logic is contained in these files:

Additionally, Dipankar Maikap, thanks to the support provided by Matthew Phillips, CTO of The Astro Technology Company, has successfully created a Vite virtual module that makes it possible to pass Storyblok Bridge Options from Astro Pages.

Next Steps

We hope you’re excited to try out this new feature! We would absolutely love to see your projects built with Storyblok and Astro, and hear your feedback about this latest feature.

Would you like to contribute to the development of @storyblok/astro? Feel free to create an issue or a PR in the official GitHub repository.

Further Resources

Storyblok’s Astro SDK now supports Astro 3

Manuel Schröder — Wed, 13 Sep 2023 09:06:41 +0000

We are excited to announce that we released @storyblok/astro v3.0.0, providing complete support for Astro 3.0. You spin off a working Astro 3.0 + Storyblok project in less than a minute by running:
npx @storyblok/create-demo@next -f astro

By the way, our CLI also supports Bun now, so you can also run:
bunx @storyblok/create-demo@next -f astro -p bun

Astro 3.0 comes packed with amazing new features, such as image optimization, up to 30% faster rendering, SSR enhancements, cleaner and more performant HTML output, and much more. Morever, Astro now is the first major web framework to support the View Transitions API!

We are very curious to see what you are building with Storyblok and Astro, and always love to hear your feedback. Feel free to get in touch, for example by joining our Discord or reaching out on Twitter.

If you are new to Storyblok and Astro, our Ultimate Tutorial got you covered. For a good overview and more advanced use cases, you can always refer to the SDK readme. In case you are already very experienced and want to share your knowledge, you might like to check out our Storyblok Ambassador and Community Writer Program.

Announcing @storyblok/astro

Manuel Schröder — Thu, 01 Sep 2022 13:41:06 +0000

We are very excited to announce the release of @storyblok/astro! Using Storyblok in your Astro project is now much easier and faster than before. Thanks to the powerful Astro Integration API and our new module, you can get up and running in a matter of minutes.

Let's explore how it works!

In a hurry? Head over to the live demo!

Usage

First of all, install @storyblok/astro:

npm install @storyblok/astro
# yarn add @storyblok/astro

Add the following code to your astro.config.mjs and replace the accessToken with the preview API token of your Storyblok space.

import { defineConfig } from "astro/config";
import storyblok from "@storyblok/astro";

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: "<your-access-token>",
      components: {
        page: "storyblok/Page",
        feature: "storyblok/Feature",
        grid: "storyblok/Grid",
        teaser: "storyblok/Teaser",
      }
    }),
  ],
});

As you can see, all components that you defined in Storyblok have to be globally registered through the components object. Henceforth, they’ll be loaded automatically when using StoryblokComponent as shown below.

Querying the Storyblok API

In any of your Astro pages, you can now use the useStoryblokApi function to fetch data from Storyblok. In this example, we're retrieving the home Story:

---
import { useStoryblokApi } from "@storyblok/astro";
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";

const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get("cdn/stories/home", {
  version: "draft",
});

const story = data.story;
---

<StoryblokComponent blok="{story.content}" />

Creating Astro Components

For each Astro component that should be linked to its equivalent in your Storyblok Space, you can use the storyblokEditable() function on its root element, passing the blok property that they receive and enabling communication with the Storyblok Bridge. Furthermore, you can use the StoryblokComponent to dynamically load any of the components that you registered globally.

---
import { storyblokEditable } from "@storyblok/astro";
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";

const { blok } = Astro.props
---

<main {...storyblokEditable(blok)}>
  {blok.body?.map(blok => {return <StoryblokComponent blok="{blok}" />})}
</main>

...but what about partial hydration?

We've got you covered! Being able to bring your favorite framework and benefitting from partial hydration is a huge advantage of using Astro.

If you want to use partial hydration with any of the frameworks supported by Astro, follow these steps:

Install the official Astro integration for your desired framework
Create an Astro component that serves as a wrapper and utilizes the most suitable client directive
Create the actual component in Vue, Svelte, React or any other supported framework

For working examples, you can explore the Live Demo on Stackblitz.

Enabling the Storyblok Bridge

The Storyblok Bridge is automatically activated by default. If you would like to disable it or enable it conditionally (e.g. depending on the environment) you can set the bridge parameter to false in astro.config.mjs.

Since Astro is not a reactive JavaScript framework and renders everything as HTML, the Storyblok Bridge will not provide real-time editing as you may know it from other frameworks. However, it automatically refreshes the site for you whenever you save or publish a story.

And that’s it! Your Astro project is now fully integrated with the Storyblok CMS.

Have a look at @storyblok/astro for more detailed documentation.

Next Steps

Are you excited to try it out? We would love to see your projects built with Storyblok and Astro!

We are planning to release a complete Storyblok Astro Ultimate Tutorial in which you will learn how to build a feature-rich, multilingual website.

Would you like to contribute to the development of @storyblok/astro? Feel free to create an issue or a PR in the official GitHub repository.

Storyblok SDKs for Vue 2 and 3 – now with TypeScript support

Manuel Schröder — Mon, 20 Jun 2022 10:52:04 +0000

Over the last couple of days, we have been working hard to improve our Vue SDKs. We are thrilled to announce that @storyblok/vue and@storyblok/vue-2 now come with TypeScript support!

Would you like to see it in action? We have created a Storyblok Vue SDK w/ TypeScript live demo for you!

Not sure how to start? Here's our easy-to-follow tutorial: How to add Storyblok to your Vue project in 5 minutes.

With the addition of TypeScript support, you now get to enjoy auto-completion, static typing and warnings when using either of the two Vue SDKs. This results in a significantly improved developer experience – even if you don't actually use TypeScript.

But have a look for yourself:

If you are unsure how to set up a a Vue project in combination with TypeScript, you can learn more about this topic in the official docs.

We intend to roll out TypeScript support for all of our other SDKs soon – so stay tuned!

Finally, we'd love to hear what you think about this latest update. What do you like about it and what could do to improve it even further?

Storyblok CheatSheet for Nuxt 3

Manuel Schröder — Fri, 03 Jun 2022 09:44:37 +0000

We have created a Storyblok Nuxt 3 CheatSheet for you! It provides all the information you need to get started right away.

Download the CheatSheet to have a quick and concise overview on how to configure our SDK, create Storyblok components, render pages dynamically, fetch multilingual content and much more!

Download the Nuxt 3 CheatSheet

New SDK naming for Nuxt 2 and Nuxt 3

Manuel Schröder — Mon, 23 May 2022 09:57:58 +0000

We have updated the naming of our Nuxt SDK npm packages! Since Nuxt 3 is currently in RC stage and will become the new default very soon, the default package for Nuxt 3 is now @storyblok/nuxt. The package for Nuxt 2 is now @storyblok/nuxt-2.

Depending on which you want to use, you would npm install:

@storyblok/nuxt-2 for Nuxt 2
@storyblok/nuxt for Nuxt 3

All of the SDK demos and getting-started repositories have been updated to reflect these changes. Expect more tutorial content for Nuxt 3 from our side over the next few weeks.

We would like to apologize for the recent naming changes and are aware of the confusion this has created among the Vue and Nuxt communities respectively. No more changes are to be expected anytime soon. Thank you very much for your understanding, your feedback, and your patience.