storyblok-js-client

What is storyblok-js-client?

The storyblok-js-client is a JavaScript client for interacting with the Storyblok API. It allows developers to easily manage content, perform CRUD operations, and interact with the Storyblok content delivery and management APIs.

What are storyblok-js-client's main functionalities?

Initialize the Client

This feature allows you to initialize the Storyblok client with your access token, which is required to authenticate and interact with the Storyblok API.

const StoryblokClient = require('storyblok-js-client');
const client = new StoryblokClient({
  accessToken: 'your-access-token'
});

Get a Story

This feature allows you to fetch a specific story from the Storyblok API. In this example, it fetches the 'home' story.

client.get('cdn/stories/home', {}).then(response => {
  console.log(response.data.story);
}).catch(error => {
  console.error(error);
});

Create a Story

This feature allows you to create a new story in your Storyblok space. The example demonstrates creating a story with a name, slug, and content.

client.post('spaces/your-space-id/stories', {
  story: {
    name: 'New Story',
    slug: 'new-story',
    content: {
      component: 'page',
      body: []
    }
  }
}).then(response => {
  console.log(response.data.story);
}).catch(error => {
  console.error(error);
});

Update a Story

This feature allows you to update an existing story in your Storyblok space. The example shows how to update the name, slug, and content of a story.

client.put('spaces/your-space-id/stories/your-story-id', {
  story: {
    name: 'Updated Story',
    slug: 'updated-story',
    content: {
      component: 'page',
      body: []
    }
  }
}).then(response => {
  console.log(response.data.story);
}).catch(error => {
  console.error(error);
});

Delete a Story

This feature allows you to delete a story from your Storyblok space. The example demonstrates how to delete a story by its ID.

client.delete('spaces/your-space-id/stories/your-story-id').then(response => {
  console.log('Story deleted');
}).catch(error => {
  console.error(error);
});

Other packages similar to storyblok-js-client

contentful

Contentful is a content management platform that allows you to create, manage, and distribute content to any platform. It offers a JavaScript client similar to storyblok-js-client for interacting with its API. Contentful provides a more extensive set of features and integrations, but Storyblok is known for its visual editor and ease of use.

prismic-javascript

Prismic is a headless CMS that offers a JavaScript client for interacting with its API. It provides similar functionalities to storyblok-js-client, such as fetching and managing content. Prismic is known for its flexible content modeling and integration capabilities.

strapi-sdk-javascript

Strapi is an open-source headless CMS that provides a JavaScript SDK for interacting with its API. It offers similar functionalities to storyblok-js-client, including content management and CRUD operations. Strapi is highly customizable and can be self-hosted, providing more control over the CMS environment.

README

Universal JavaScript SDK for Storyblok's API

This client is a thin wrapper for the Storyblok API's to use in Node.js and the browser.

The version 2 uses corejs 3. If you are looking for the version that uses corejs 2 please use version 1.x.x.

Install

npm install storyblok-js-client

Usage

Class Storyblok

Parameters

• config Object
  • accessToken String, The preview token you can find in your space dashboard at https://app.storyblok.com
  • cache Object
    • type String, none or memory
  • (region String, optional)
  • (https Boolean, optional)
  • (rateLimit Integer, optional, defaults to 3 for management api and 5 for cdn api)
  • (timeout Integer, optional)
  • (maxRetries Integer, optional, defaults to 5)
• (endpoint String, optional)

Example for using the content deliver api

// 1. Require the Storyblok client
const StoryblokClient = require('storyblok-js-client')

// 2. Initialize the client with the preview token
// from your space dashboard at https://app.storyblok.com
let Storyblok = new StoryblokClient({
  accessToken: 'xf5dRMMjltLzKOcNgMaU9Att'
})

Example for using the content management api

// 1. Require the Storyblok client
const StoryblokClient = require('storyblok-js-client')
const spaceId = 12345

// 2. Initialize the client with the oauth token
// from the my account area at https://app.storyblok.com
let Storyblok = new StoryblokClient({
  oauthToken: 'YOUR_OAUTH_TOKEN'
})

Storyblok.post(`spaces/${spaceId}/stories`, {story: {name: 'xy', slug: 'xy'}})
Storyblok.put(`spaces/${spaceId}/stories/1`, {story: {name: 'xy', slug: 'xy'}})
Storyblok.delete(`spaces/${spaceId}/stories/1`, null)

Activating request cache

The Storyblok client comes with a caching mechanism. When initializing the Storyblok client you can define a cache provider for caching the requests in memory. To clear the cache you can call Storyblok.flushCache() or activate the automatic clear with clear: 'auto'.

let Storyblok = new StoryblokClient({
  accessToken: 'xf5dRMMjltLzKOcNgMaU9Att',
  cache: {
    clear: 'auto',
    type: 'memory'
  }
})

Method Storyblok#get

With this method you can get single or multiple items. The multiple items are paginated and you will receive 25 items per page by default. If you want to get all items at once use the getAll method.

Parameters

• [return] Promise, Object response
• path String, Path (can be cdn/stories, cdn/stories/*, cdn/tags, cdn/datasources, cdn/links)
• options Object, Options can be found in the API documentation.

Example

Storyblok
  .get('cdn/stories/home', {
    version: 'draft'
  })
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  })

Method Storyblok#getAll

With this method you can get all items at once.

Parameters

• [return] Promise, Array of entities
• path String, Path (can be cdn/stories, cdn/stories/*, cdn/tags, cdn/datasources, cdn/links)
• options Object, Options can be found in the API documentation.
• entity String, Storyblok entity like stories, links or datasource. It's optional.

Example

Storyblok
  .getAll('cdn/stories', {
    version: 'draft'
  })
  .then((stories) => {
    console.log(stories); // an array
  })
  .catch((error) => {
    console.log(error);
  })

Method Storyblok#post (only management api)

Parameters

• [return] Promise, Object response
• path String, Path (spaces/*, ... see more at https://www.storyblok.com/docs/management-api/authentication)
• payload Object

Example

Storyblok
  .post('spaces/12345/stories', {
    story: {name 'xy', slug: 'xy'}
  })
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  })

Method Storyblok#put (only management api)

Parameters

• [return] Promise, Object response
• path String, Path (spaces/*, ... see more at https://www.storyblok.com/docs/management-api/authentication)
• payload Object

Example

Storyblok
  .put('spaces/12345/stories', {
    story: {name 'xy', slug: 'xy'}
  })
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  })

Method Storyblok#delete (only management api)

Parameters

• [return] Promise, Object response
• path String, Path (spaces/*, ... see more at https://www.storyblok.com/docs/management-api/authentication)
• payload Object

Example

Storyblok
  .delete('spaces/12345/stories', null)
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  })

Method Storyblok#flushCache

Parameters

• [return] Promise, Object returns the Storyblok client

Example

Storyblok.flushCache()

Method Storyblok#setComponentResolver

Parameters

• callback Function, Render function to render components of the richtext field

Option 1: Use a switch case definition to render different components:

Storyblok.setComponentResolver((component, blok) => {
  switch(component) {
    case 'my-custom-component':
      return `<div class="my-component-class">${blok.text}</div>`
      break;
    case 'my-header':
      return `<h1 class="my-class">${blok.title}</h1>`
      break;
    default:
      return 'Resolver not defined'
  }
})

Option 2: Dynamically render a component (Example in Vue.js):

Storyblok.setComponentResolver((component, blok) => {
  return `<component :blok='${JSON.stringify(blok)}'
                     is="${component}"></component>`
})

Method Storyblok#richTextResolver.render

Parameters

• [return] String, Rendered html of a richtext field
• data Richtext object, An object with a content (an array of nodes) field.

Example

Storyblok.richTextResolver.render(blok.richtext)

Code examples

Filter by content type values and path

const StoryblokClient = require('storyblok-js-client')

let client = new StoryblokClient({
  accessToken: 'zlRONoLBKrilxkz2k6fYuwtt'
})

// Filter by boolean value in content type
client.get('cdn/stories', {
    version: 'draft',
    filter_query: {
      is_featured: {
        in: true
      }
    }
  }).then((res) => {
    console.log(res.data.stories)
  })

// Get all news and author contents
client.get('cdn/stories', {
    version: 'draft',
    filter_query: {
      component: {
        in: 'news,author'
      }
    }
  }).then((res) => {
    console.log(res.data.stories)
  })

// Get all content from the news folder
client.get('cdn/stories', {
    version: 'draft',
    starts_with: 'news/'
  }).then((res) => {
    console.log(res.data.stories)
  })

Download all content from Storyblok

Following a code example using the storyblok-js-client to backup all content on your local filesystem inside a 'backup' folder.

const StoryblokClient = require('storyblok-js-client')
const fs = require('fs')

let client = new StoryblokClient({
  accessToken: 'WcdDcNgDm59K72EbsQg8Lgtt'
})

let lastPage = 1
let getStories = (page) => {
  client.get('cdn/stories', {
      version: 'draft',
      per_page: 25,
      page: page
    }).then((res) => {

    let stories = res.data.stories
    stories.forEach((story) => {
      fs.writeFile('./backup/' + story.id + '.json', JSON.stringify(story), (err) => {
        if (err) throw err

        console.log(story.full_slug + ' backed up')
      })
    })

    let total = res.total
    lastPage = Math.ceil((res.total / res.perPage))

    if (page <= lastPage) {
      page++
      getStories(page)
    }
  })
}

getStories(1)

Initialize with a proxy server

const proxy = {
  host: host,
  port: port,
  auth: {
    username: 'username',
    password: 'password'
  }
}

const storyblok = new StoryblokClient({
  ...
  https: false,
  proxy: proxy
})

Read more about proxy settings in axios documentation

How to define a custom schema for the rich text renderer

To define to add some classes to specific html attributes rendered by the rich text renderer. To do so you can overwrite the resolver and initialize it with your own schema definition. Copy the content of https://github.com/storyblok/storyblok-js-client/blob/master/source/schema.js to my-schema.js and overwrite richTextResolver like in the following example:

const StoryblokClient = require('storyblok-js-client')
const RichTextResolver = require('storyblok-js-client/dist/richTextResolver')
const MySchema = require('./my-schema')

let client = new StoryblokClient({
  accessToken: 'WcdDcNgDm59K72EbsQg8Lgtt'
})

client.richTextResolver = new RichTextResolver(MySchema)

Contribution

Fork me on Github.

This project use 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.