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.

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

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#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] Object, returns the Storyblok client

Example

Storyblok.flushCache()

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

Contribution

Fork me on Github