storyblok-qwik v0.1.0

🚀 Usage

If you are first-time user of the Storyblok, read the Getting Started guide to get a project ready in less than 5 minutes.

Installation

Install storyblok-qwik

npm install storyblok-qwik
# yarn add storyblok-qwik

Initialize the library in your application (usually in root.tsx) by adding the apiPlugin and the access token of your Storyblok space:

export default component$(() => {
  storyblokInit({
    accessToken: "<your-token>",
    // bridge: false,
    // apiOptions: {  },
    use: [apiPlugin],
    components: {
      teaser: Teaser,
    },
  });

  // your root component code
});

Add all your components to the components object in the storyblokInit function. You can load all of them at the same time by adding them to the list.

Now, all features are enabled for you: the Api Client for interacting with Storyblok CDN API, and Storyblok Bridge for real-time visual editing experience.

You can enable/disable some of these features if you don't need them, so you save some KB. Please read the "Features and API" section

Getting started

1. Fetching Content

Using the useStoryblok() gets your stories from the Storyblok CDN API:

import { component$, useMount$, useStore } from "@builder.io/qwik";
import { StoryblokStory, StoryData, useStoryblokApi } from "storyblok-qwik";
import { NotFound } from "~/components/not-found";

export default component$(() => {
  const state = useStore({
    story: null as StoryData | null,
  });

  useMount$(async () => {
    const storyblokApi = useStoryblokApi();
    const { data } = await storyblokApi.get(`cdn/stories/home`, {
      version: "draft",
    });
    state.story = data.story as StoryData;
  });

  const story = state.story;

  return <>{story ? <StoryblokStory initialStory={story} /> : <NotFound />}</>;
});

2. Link your components to Storyblok Visual Editor

In order to link the storyblok components, you have to:

• Load them in components when calling storyblokInit

• Spread the restProps on the root element of each component

  import { component$ } from "@builder.io/qwik";
  import { SbBlokData, StoryblokComponentProps } from "storyblok-qwik";
  interface FeatureProps extends SbBlokData {
    name: string;
    description: string;
  }
  
  export const Feature = component$(
    ({
      blok: { name, description },
      ...restProps
    }: StoryblokComponentProps<FeatureProps>) => {
      return (
        <div {...restProps}>
          <div>
            <div>{name as string}</div>
            <p>{description as string}</p>
          </div>
        </div>
      );
    }
  );

• Wrap your nested components with the StoryblokComponent component

  import { component$ } from "@builder.io/qwik";
  import {
    SbBlokData,
    StoryblokComponent,
    StoryblokComponentProps,
  } from "storyblok-qwik";
  
  interface PageProps extends SbBlokData {
    body: SbBlokData[];
  }
  
  export const Page = component$(
    ({ blok: { body }, ...restProps }: StoryblokComponentProps<PageProps>) => {
      return (
        <div {...restProps}>
          {body?.map((nestedBlok) => {
            return <StoryblokComponent blok={nestedBlok} />;
          })}
        </div>
      );
    }
  );

The blok is the actual blok data coming from Storblok's Content Delivery API.

Features and API

You can choose the features to use when you initialize the plugin. In that way, you can improve Web Performance by optimizing your page load and save some bytes.

Storyblok API

You can use an apiOptions object. This is passed down to the storyblok-js-client config object:

storyblokInit({
  accessToken: "<your-token>",
  apiOptions: {
    //storyblok-js-client config object
    cache: { type: "memory" },
  },
  use: [apiPlugin],
});

ℹ️ More Resources

Support

• Bugs or Feature Requests? Submit an issue.
• Do you have questions about Storyblok or you need help? Join the Discord Community.

Contributing

Please see our contributing guidelines and our code of conduct. This project uses semantic-release for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check this question about it in semantic-release FAQ.