Install package

Start with installing @shopstory/core and @shopstory/react in your project:

npm install @shopstory/core @shopstory/react

Add the configuration files

Add the main Shopstory configuration file in src/shopstory/config.ts:

import { Config } from "@shopstory/core"

export const shopstoryConfig : Config = {

We're gonna populate it soon but for now let's keep it empty.

Another file we'll need is a custom ShopstoryProvider. Let's create src/shopstory/provider.tsx:

import {
} from "@shopstory/react";

export const DemoShopstoryProvider: React.FC = ({ children }) => {
  return (

We'll use this component later to pass all the references to custom components and actions used by Shopstory.

It's a good practice to have a dedicated shopstory/ directory for all Shopstory configuration.

Create a canvas page

In order to use Shopstory in your project you must create a canvas page. A canvas page is simply a blank page in your project that Shopstory will use to render content into.

Let's add a canvas page to pages/shopstory-canvas.tsx:

import type { NextPage } from 'next'
import { Canvas } from "@shopstory/react";
import { shopstoryConfig } from "../src/shopstory/config";
import { DemoShopstoryProvider } from "../src/shopstory/provider";

const ShopstoryCanvasPage: NextPage = () => {
  return <DemoShopstoryProvider>
    <Canvas config={shopstoryConfig} />

export default ShopstoryCanvasPage

<Canvas /> component must be wrapped with our <DemoShopstoryProvider>.

Important! Canvas page should be stripped from any elements like menu, footer, cookie messages, etc. It should be as empty as you can make it, without any margins, paddings, etc.

Now open your next.js application and go to localhost:3000/shopstory-canvas. You should see Shopstory editor in a "playground mode". Playground mode means that Shopstory editor is opened outside of CMS. Playground mode is great for developers to test the Shopstory configuration: custom components, actions, design tokens etc. However, it comes with limitations:

  1. You can only use mock image / video pickers. You don't have access to built-in CMS entry / media pickers.

  2. The content you build is not saved anywhere.

Last updated