> For the complete documentation index, see [llms.txt](https://docs.shopstory.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shopstory.app/getting-started/installation.md).

# Installation

## 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`:

```typescript
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`:

```typescript
import {
  ShopstoryProvider,
} from "@shopstory/react";

export const DemoShopstoryProvider: React.FC = ({ children }) => {
  return (
    <ShopstoryProvider>
      {children}
    </ShopstoryProvider>
  );
};

```

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`:

```typescript
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} />
  </DemoShopstoryProvider>
}

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.&#x20;

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.shopstory.app/getting-started/installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.