@storyblok/svelte

The Svelte SDK you need to interact with Storyblok API and enable the Real-time Visual Editing Experience.

🚀 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/svelte

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

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

import App from "./App.svelte";
import { storyblokInit, apiPlugin } from "@storyblok/svelte";

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

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

From a CDN

Install the file from the CDN and access the methods via window.storyblokSvelte:

<script src="https://unpkg.com/@storyblok/svelte"></script>

Getting started

1. Fetching Content

Use the getStoryblokApi() gets your stories from the Storyblok CDN API:

<script>
  import { onMount } from "svelte";
  import { getStoryblokApi } from "@storyblok/svelte";

  onMount(async () => {
    const storyblokApi = getStoryblokApi();
    const { data } = await storyblokApi.get("cdn/stories/home", {
      version: "draft",
    });
  });
</script>

Note: you can skip using storyblokApi if you prefer your own method or function to fetch your data.

2. Listen to Storyblok Visual Editor events

Use useStoryBridge to get the updated story every time a change event is triggered from the Visual Editor. You need to pass the story id as first param, and a callback function as second param to update the new story:

<script>
  import { onMount } from "svelte";
  import { getStoryblokApi, useStoryblokBridge } from "@storyblok/svelte";

  let story = null;

  onMount(async () => {
    const storyblokApi = getStoryblokApi();
    const { data } = await storyblokApi.get("cdn/stories/home", {
      version: "draft",
    });
    story = data.story;
    useStoryblokBridge(story.id, (newStory) => (story = newStory));
  });
</script>

You can pass Bridge options as a third parameter as well:

useStoryblokBridge(story.id, (newStory) => (story = newStory), {
  resolveRelations: ["Article.author"],
});

3. Link your components to Storyblok Visual Editor

In order to link the storyblok components, you have to

Load them in components when calling storyblokInit
Use the storyblokEditable action on the root element of each component

<div use:storyblokEditable={blok} / >

Use the StoryblokComponent to load them by passing the blok property

<StoryblokComponent {blok} />

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],
});

If you prefer to use your own fetch method, just remove the apiPlugin and storyblok-js-client won't be added to your application. You can find out more about our Content Delivery API in the documentation.

Storyblok Bridge

You can conditionally load it by using the bridge option. Very useful if you want to disable it in production:

storyblokInit({
  bridge: process.env.NODE_ENV !== "production",
});

Keep in mind you have still access to the raw window.StoryblokBridge:

const sbBridge = new window.StoryblokBridge(options);

sbBridge.on(["input", "published", "change"], (event) => {
  // ...
});

For background information on the Storyblok JS Bridge, please check out documentation.

Rendering Rich Text

You can easily render rich text by using the renderRichTextfunction that comes with @storyblok/svelteand Sveltes {@html htmlstring}directive.

<script>
  import { renderRichText } from "@storyblok/svelte";

  export let blok;
  $: articleHTML = renderRichText(blok.article);
</script>

<div>{@html articleHTML}</div>

You can set a custom Schema and component resolver globally at init time by using the richText init option:

import { RichTextSchema, storyblokInit } from "@storyblok/svelte";
import cloneDeep from "clone-deep";

const mySchema = cloneDeep(RichTextSchema); // you can make a copy of the default RichTextSchema
// ... and edit the nodes and marks, or add your own.
// Check the base RichTextSchema source here https://github.com/storyblok/storyblok-js-client/blob/master/source/schema.js

storyblokInit({
  accessToken: "<your-token>",
  richText: {
    schema: mySchema,
    resolver: (component, blok) => {
      switch (component) {
        case "my-custom-component":
          return `<div class="my-component-class">${blok.text}</div>`;
        default:
          return "Resolver not defined";
      }
    },
  },
});

You can also set a custom Schema and component resolver only once by passing the options as the second parameter to renderRichText function:

import { renderRichText } from "@storyblok/svelte";

renderRichText(blok.richTextField, {
  schema: mySchema,
  resolver: (component, blok) => {
    switch (component) {
      case "my-custom-component":
        return `<div class="my-component-class">${blok.text}</div>`;
        break;
      default:
        return `Component ${component} not found`;
    }
  },
});

Compatibility

This plugin is for Svelte. Thus, it supports the same browsers as Svelte 3. In short: all modern browsers and IE10+.

Troubleshooting

Working with a Component Library

When working with a component library, create an alias pointing '@storyblok/svelte' to './node_modules/@storyblok/svelte'. This will ensure the imported module will use the local version of storyblok. In your svelte.config.js, include:

kit: {
		alias: {
			'@storyblok/svelte': './node_modules/@storyblok/svelte'
		},

Any module importing @storyblok/svelte will now get it from the aliased location. For more information and alternatives to this solution, please see npm link, peerDependencies and webpack.

Another option might also be using npm / yarn workspaces.

🔗 Related Links

Add a headless CMS to Svelte in 5 minutes: Quick-start guide on getting up and running with Storyblok and Vue.
Storyblok CLI: A simple CLI for scaffolding Storyblok projects and fieldtypes.
Svelte Documentation

ℹ️ More Resources

Support

Bugs or Feature Requests? Submit an issue.
Do you have questions about Storyblok or you need help? Join our 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.

loghomefinishing/storyblok-svelte