Storyblok React

https://github.com/storyblok/storyblok-react
Admin
Storyblok React is the official React SDK designed to integrate Storyblok with React and React-based...
Tokens:32,735
Snippets:329
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Component Setup

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokComponent.md

Defining components and initializing the Storyblok SDK.

```typescript
// components/Page.tsx
export const Page = ({ blok }) => (
  <main className="page">
    {blok.body?.map(block => (
      <StoryblokComponent key={block._uid} blok={block} />
    ))}
  </main>
);

// components/Teaser.tsx
export const Teaser = ({ blok }) => (
  <div className="teaser">
    <h2>{blok.headline}</h2>
    <p>{blok.description}</p>
  </div>
);

// app/App.tsx
import { storyblokInit, apiPlugin } from '@storyblok/react';
import { Page, Teaser } from './components';

storyblokInit({
  accessToken: 'your_token',
  use: [apiPlugin],
  components: {
    page: Page,
    teaser: Teaser,
  }
});
```

--------------------------------

### Install dependencies

Source: https://github.com/storyblok/storyblok-react/blob/main/CONTRIBUTING.md

Install project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Initialize SDK with SbReactSDKOptions

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Example of configuring the SDK with fallback components and additional options.

```typescript
import { storyblokInit, apiPlugin } from '@storyblok/react';
import * as components from './components';
import FallbackComponent from './components/Fallback';

storyblokInit({
  accessToken: process.env.REACT_APP_STORYBLOK_TOKEN,
  use: [apiPlugin],
  components,
  enableFallbackComponent: true,
  customFallbackComponent: FallbackComponent,
  resolveRelations: ['author', 'category'],
  resolveLinks: 'story',
});
```

--------------------------------

### Run the development server

Source: https://github.com/storyblok/storyblok-react/blob/main/playground/next15/README.md

Use these commands to start the local development environment for the Next.js application.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Initialize SDK with SbReactComponentsMap

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Example of using the component map during SDK initialization.

```typescript
import { storyblokInit, apiPlugin } from '@storyblok/react';
import Page from './components/Page';
import Teaser from './components/Teaser';

const components: SbReactComponentsMap = {
  page: Page,
  teaser: Teaser,
};

storyblokInit({
  accessToken: 'your_token',
  use: [apiPlugin],
  components,
});
```

--------------------------------

### Initialize Storyblok with Minimal Setup

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit.md

Basic configuration requiring only an access token and the API plugin.

```typescript
import { apiPlugin, storyblokInit } from '@storyblok/react';

storyblokInit({
  accessToken: 'your_access_token',
  use: [apiPlugin],
});
```

--------------------------------

### Setup Storyblok in Next.js Client Components

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/configuration.md

Initializes the SDK for use within Next.js client components.

```typescript
// lib/storyblok.ts
'use client';

import { apiPlugin, storyblokInit } from '@storyblok/react';
import * as components from '@/components';

storyblokInit({
  accessToken: process.env.NEXT_PUBLIC_STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
  components,
});

export { getStoryblokApi, useStoryblok } from '@storyblok/react';
```

--------------------------------

### Complete Live Editing Flow Example

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/liveEditUpdateAction.md

A step-by-step overview of the live editing process from initial load to re-rendering with updated content.

```typescript
// 1. Initial page load
// app/page.tsx
async function Home() {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get('cdn/stories/home', { version: 'draft' });
  return <StoryblokStory story={data.story} />;
}

// 2. Editor opens page with ?_storyblok=true
// StoryblokLiveEditing component mounts
// Bridge registers with story ID

// 3. Editor changes content
// Visual Editor sends update via bridge

// 4. handleInput() called with new story
// liveEditUpdateAction({ story, pathToRevalidate: '/' })

// 5. Story cached in globalThis.storyCache
// revalidatePath('/') invalidates Next.js cache

// 6. Page re-renders with cached story
// Cached story retrieved and deleted to prevent leakage

// 7. User sees updated content in preview
```

--------------------------------

### Basic RSC Initialization

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit-rsc.md

Standard setup for Storyblok in a Next.js App Router environment.

```typescript
// app/lib/storyblok.ts
'use server';

import { storyblokInit, apiPlugin } from '@storyblok/react/rsc';
import Page from '@/components/Page';
import Teaser from '@/components/Teaser';
import Grid from '@/components/Grid';

storyblokInit({
  accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
  components: {
    page: Page,
    teaser: Teaser,
    grid: Grid,
  },
});
```

--------------------------------

### Fetching a Story

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/getStoryblokApi.md

Example of using getStoryblokApi to fetch a single story by slug.

```typescript
import { getStoryblokApi } from '@storyblok/react';

async function fetchStory() {
  const sbApi = getStoryblokApi();
  
  if (!sbApi) {
    console.error('Storyblok API not initialized');
    return;
  }

  const { data } = await sbApi.get('cdn/stories/home', {
    version: 'draft',
    resolve_relations: 'author'
  });

  return data.story;
}
```

--------------------------------

### Setup Storyblok in Next.js Server Components

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/configuration.md

Initializes the SDK for use within Next.js server components using the RSC-specific entry point.

```typescript
// lib/storyblok.ts
'use server';

import { storyblokInit, apiPlugin } from '@storyblok/react/rsc';
import * as components from '@/components';

storyblokInit({
  accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
  components,
});

export { getStoryblokApi, StoryblokStory } from '@storyblok/react/rsc';
```

--------------------------------

### Basic Usage with StoryblokStory

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokLiveEditing.md

Example showing how StoryblokStory automatically includes live editing capabilities.

```typescript
// app/components/Page.tsx
import { StoryblokStory } from '@storyblok/react/rsc';
import type { ISbStoryData } from '@storyblok/react/rsc';

interface PageProps {
  story: ISbStoryData;
}

export default function Page({ story }: PageProps) {
  // StoryblokStory automatically includes StoryblokLiveEditing
  return (
    <article>
      <h1>{story.name}</h1>
      <StoryblokStory story={story} />
    </article>
  );
}
```

--------------------------------

### Initialize Storyblok in Next.js

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit.md

Standard setup for Next.js applications using environment variables for the access token.

```typescript
// app/layout.tsx or pages/_app.tsx
import { apiPlugin, storyblokInit } from '@storyblok/react';

storyblokInit({
  accessToken: process.env.NEXT_PUBLIC_STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
  components: {
    // your components map
  },
});
```

--------------------------------

### Manual Usage with Error Handling

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/liveEditUpdateAction.md

Example showing how to wrap the action in a try-catch block to manage loading states and display errors.

```typescript
// app/components/SafeLiveEditHandler.tsx
'use client';

import { useEffect, useState } from 'react';
import { liveEditUpdateAction } from '@storyblok/react/rsc';
import type { ISbStoryData } from '@storyblok/react/rsc';

export function SafeLiveEditHandler({ story }: { story: ISbStoryData }) {
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  const handleUpdate = async (updatedStory: ISbStoryData) => {
    try {
      setLoading(true);
      setError(null);

      await liveEditUpdateAction({
        story: updatedStory,
        pathToRevalidate: window.location.pathname,
      });

      console.log('Story updated and path revalidated');
    } catch (err) {
      const message = err instanceof Error ? err.message : 'Unknown error';
      setError(`Failed to update story: ${message}`);
      console.error('Live edit action failed:', err);
    } finally {
      setLoading(false);
    }
  };

  return (
    <>
      {error && <div className="error">{error}</div>}
      {loading && <div className="loading">Updating...</div>}
    </>
  );
}
```

--------------------------------

### Implement StoryblokRichText component

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Example usage of the StoryblokRichText component with custom resolvers.

```typescript
import { StoryblokRichText, BlockTypes } from '@storyblok/react';

function Article({ story }) {
  const props: StoryblokRichTextProps = {
    doc: story.content.richText,
    resolvers: {
      [BlockTypes.HEADING]: (node, children) => (
        <h2 className="custom-heading">{children}</h2>
      ),
    },
  };

  return <StoryblokRichText {...props} />;
}
```

--------------------------------

### Configure StoryblokBridgeConfigV2

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Example of passing bridge configuration options to the useStoryblok hook.

```typescript
import { useStoryblok } from '@storyblok/react';

function Story() {
  const story = useStoryblok(
    'home',
    { version: 'draft' },
    {
      resolveRelations: ['author', 'comments'],
      resolveLinks: 'story',
    }
  );

  return null;
}
```

--------------------------------

### Implement useStoryblokState hook

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Example usage of the useStoryblokState hook with custom content types.

```typescript
import { useStoryblokState } from '@storyblok/react';
import type { ISbStoryData } from '@storyblok/react';

interface CustomContent {
  title: string;
  description: string;
}

function Page({ storyData }: { storyData: ISbStoryData<CustomContent> }) {
  const story = useStoryblokState<CustomContent>(storyData);
  
  return (
    <div>
      <h1>{story?.content.title}</h1>
      <p>{story?.content.description}</p>
    </div>
  );
}
```

--------------------------------

### Using Rich Text Resolvers

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Example of using the useStoryblokRichText hook with custom resolvers for specific block and mark types.

```typescript
import { useStoryblokRichText, BlockTypes, MarkTypes } from '@storyblok/react';

function RichText({ doc }) {
  const { render } = useStoryblokRichText({
    resolvers: {
      [BlockTypes.HEADING]: (node, children) => (
        <h2>{children}</h2>
      ),
      [MarkTypes.BOLD]: (node, children) => (
        <strong>{children}</strong>
      ),
    },
  });

  return render(doc);
}
```

--------------------------------

### Querying Multiple Stories

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/getStoryblokApi.md

Example of using getStoryblokApi to query multiple stories with filtering and sorting parameters.

```typescript
async function fetchBlogPosts() {
  const sbApi = getStoryblokApi();

  const { data } = await sbApi.get('cdn/stories', {
    version: 'published',
    starts_with: 'blog/',
    sort_by: 'created_at:desc',
    per_page: 10
  });

  return data.stories;
}
```

--------------------------------

### Manual Usage of liveEditUpdateAction

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/liveEditUpdateAction.md

Example demonstrating how to manually trigger the action using the Storyblok bridge within a client component.

```typescript
// app/components/ManualEditHandler.tsx
'use client';

import { useEffect } from 'react';
import { liveEditUpdateAction } from '@storyblok/react/rsc';
import { registerStoryblokBridge } from '@storyblok/js';
import type { ISbStoryData } from '@storyblok/react/rsc';

export function ManualEditHandler({ story }: { story: ISbStoryData }) {
  useEffect(() => {
    if (typeof window === 'undefined') {
      return;
    }

    const handleStoryUpdate = async (updatedStory: ISbStoryData) => {
      await liveEditUpdateAction({
        story: updatedStory,
        pathToRevalidate: window.location.pathname,
      });
    };

    registerStoryblokBridge(story.id, handleStoryUpdate);
  }, [story.id]);

  return null;
}
```

--------------------------------

### Initialize with Access Token

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/configuration.md

Configure the SDK using an environment variable for the Storyblok access token.

```typescript
storyblokInit({
  accessToken: process.env.REACT_APP_STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
});
```

--------------------------------

### Build the package

Source: https://github.com/storyblok/storyblok-react/blob/main/CONTRIBUTING.md

Compile the package using the build script.

```bash
pnpm build
```

--------------------------------

### Initialize Storyblok SDK

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

Configure the SDK with your access token and component mapping.

```typescript
storyblokInit({
  accessToken: 'token',
  use: [apiPlugin],
  components: { ... }
});
```

--------------------------------

### Using getStoryblokApi in useCallback

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/getStoryblokApi.md

Example of using getStoryblokApi within a React useCallback hook.

```typescript
import { useCallback } from 'react';
import { getStoryblokApi } from '@storyblok/react';

function StorySearchComponent() {
  const handleSearch = useCallback(async (query: string) => {
    const sbApi = getStoryblokApi();
    const { data } = await sbApi.get('cdn/stories', {
      search_term: query,
      per_page: 20
    });
    return data.stories;
  }, []);

  return <SearchForm onSearch={handleSearch} />;
}
```

--------------------------------

### Run tests

Source: https://github.com/storyblok/storyblok-react/blob/main/CONTRIBUTING.md

Execute the test suite defined in package.json.

```bash
pnpm test
```

--------------------------------

### useStoryblokRichText(options)

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/useStoryblokRichText.md

Initializes the rich text renderer with optional custom resolvers.

```APIDOC
## useStoryblokRichText(options)

### Description
Initializes a rich text renderer instance. Returns an object containing a `render` function that accepts a Storyblok rich text document object.

### Parameters
- **options** (Object) - Optional - Configuration object for the hook.
  - **resolvers** (Object) - Optional - A map of custom resolver functions for specific block or mark types (e.g., `MarkTypes.BOLD`, `BlockTypes.IMAGE`).

### Returns
- **render** (Function) - A function that takes a rich text document and returns the rendered React component tree.

### Usage Example
```typescript
import { useStoryblokRichText } from '@storyblok/react';

function RichTextProcessor({ doc }) {
  const { render } = useStoryblokRichText({});
  return render(doc);
}
```
```

--------------------------------

### storyblokInit(pluginOptions)

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit.md

Initializes the Storyblok React SDK with the provided configuration options.

```APIDOC
## storyblokInit(pluginOptions)

### Description
Initializes the Storyblok React SDK. This function must be called once at application startup to configure the API client, register React components, and set up fallback rendering.

### Signature
`storyblokInit(pluginOptions?: SbReactSDKOptions): void`

### Parameters
- **pluginOptions** (SbReactSDKOptions) - Optional - Configuration object for SDK initialization.

#### SbReactSDKOptions Properties
- **accessToken** (string) - Required - Storyblok API access token.
- **use** (Plugin[]) - Optional - Array of plugins to load.
- **components** (SbReactComponentsMap) - Optional - Map of component names to React component instances.
- **enableFallbackComponent** (boolean) - Optional - Enable fallback rendering for unknown components.
- **customFallbackComponent** (React.ElementType) - Optional - Custom component to render when a component is not found.
- **apiUrl** (string) - Optional - Storyblok API base URL (default: https://api.storyblok.com).
- **rateLimit** (number) - Optional - API request rate limit per second (default: 3).
- **resolveRelations** (string[]) - Optional - Relations to resolve globally.
- **resolveLinks** (string) - Optional - How to resolve links ('url', 'story').

### Usage Example
```typescript
import { apiPlugin, storyblokInit } from '@storyblok/react';

storyblokInit({
  accessToken: 'your_access_token',
  use: [apiPlugin],
  components: { teaser: Teaser },
  enableFallbackComponent: true
});
```
```

--------------------------------

### Initialize Storyblok React SDK

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/configuration.md

Pass configuration options to the storyblokInit function to set up the SDK environment.

```typescript
storyblokInit({
  accessToken: 'your_token',
  use: [apiPlugin],
  components: { /* ... */ },
  enableFallbackComponent: true,
  customFallbackComponent: FallbackComponent,
  // ... additional options
});
```

--------------------------------

### Use ISbStoryData in React Components

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Example of typing the result of the useStoryblok hook with a custom content interface.

```typescript
import { useStoryblok } from '@storyblok/react';
import type { ISbStoryData } from '@storyblok/react';

interface PageContent {
  title: string;
  body: any[];
}

function Page() {
  const story: ISbStoryData<PageContent> | null = useStoryblok('home');
  
  return story ? (
    <div>
      <h1>{story.name}</h1>
      <p>Updated: {story.updated_at}</p>
    </div>
  ) : null;
}
```

--------------------------------

### Initialize Components in a Module

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/setComponents.md

Encapsulating Storyblok initialization and component registration within a dedicated module.

```typescript
// modules/storyblok/init.ts
import { storyblokInit, apiPlugin, setComponents } from '@storyblok/react';
import * as components from './components';

export function initializeStoryblok() {
  storyblokInit({
    accessToken: process.env.REACT_APP_STORYBLOK_TOKEN,
    use: [apiPlugin],
  });

  // Register all components from the module
  setComponents(components);
}

// app/App.tsx
import { initializeStoryblok } from './modules/storyblok/init';

initializeStoryblok();
```

--------------------------------

### Automatic Usage via StoryblokLiveEditing

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/liveEditUpdateAction.md

Example showing how StoryblokLiveEditing automatically handles updates when integrated into a Next.js page.

```typescript
// app/page.tsx
import { getStoryblokApi, StoryblokStory } from '@storyblok/react/rsc';

async function getHome() {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get('cdn/stories/home', { version: 'draft' });
  return data.story;
}

export default async function Home() {
  const story = await getHome();

  // StoryblokLiveEditing automatically calls liveEditUpdateAction
  // when content changes in the Visual Editor
  return <StoryblokStory story={story} />;
}
```

--------------------------------

### In Custom Rich Text Renderer

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/convertAttributesInElement.md

Applies attribute conversion within a custom Storyblok rich text resolver setup.

```typescript
import { useStoryblokRichText, convertAttributesInElement } from '@storyblok/react';
import React from 'react';

function CustomRichTextRenderer({ doc }) {
  const { render } = useStoryblokRichText({
    resolvers: {
      // Custom resolvers that might produce HTML-like attributes
    },
  });

  const rendered = render(doc);
  const formatted = convertAttributesInElement(rendered as React.ReactElement);

  return <article className="rich-text">{formatted}</article>;
}
```

--------------------------------

### Initialize Storyblok with Components and Fallback

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit.md

Configuration including a component map and custom fallback rendering for unknown components.

```typescript
import { apiPlugin, storyblokInit } from '@storyblok/react';
import Teaser from './components/Teaser';
import Grid from './components/Grid';
import Page from './components/Page';
import FallbackComponent from './components/FallbackComponent';

storyblokInit({
  accessToken: 'your_access_token',
  use: [apiPlugin],
  components: {
    teaser: Teaser,
    grid: Grid,
    page: Page,
  },
  enableFallbackComponent: true,
  customFallbackComponent: FallbackComponent,
});
```

--------------------------------

### Import Client-Side Modules

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

Use this entry point for standard client-side React applications.

```typescript
import {
  useStoryblok,
  useStoryblokState,
  useStoryblokRichText,
  storyblokInit,
  getStoryblokApi,
  setComponents,
  getComponent,
  StoryblokComponent,
  StoryblokRichText,
  convertAttributesInElement,
} from '@storyblok/react';
```

--------------------------------

### Project File Structure

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/SUMMARY.md

Displays the directory layout of the documentation workspace.

```text
/workspace/home/output/
├── README.md                           # Start here
├── types.md                            # All type definitions
├── configuration.md                    # Setup and config
├── SUMMARY.md                          # This file
└── api-reference/
    ├── INDEX.md                        # API index
    ├── useStoryblok.md
    ├── useStoryblokState.md
    ├── useStoryblokRichText.md
    ├── storyblokInit.md
    ├── storyblokInit-rsc.md
    ├── getStoryblokApi.md
    ├── StoryblokComponent.md
    ├── StoryblokServerComponent.md
    ├── StoryblokStory.md
    ├── StoryblokRichText.md
    ├── setComponents.md
    ├── getComponent.md
    ├── componentResolver.md
    ├── convertAttributesInElement.md
    ├── StoryblokLiveEditing.md
    └── liveEditUpdateAction.md
```

--------------------------------

### SbReactSDKOptions

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Configuration object for SDK initialization, extending base SDK options with React-specific properties.

```APIDOC
## SbReactSDKOptions

### Description
Configuration object for SDK initialization. Extends `SbSDKOptions` with React-specific properties.

### Properties
- **components** (SbReactComponentsMap) - Optional - Map of Storyblok component names to React components
- **enableFallbackComponent** (boolean) - Optional - Whether to render fallback content for unknown components (Default: false)
- **customFallbackComponent** (React.ElementType) - Optional - Custom React component for unknown components

### Usage
```typescript
import { storyblokInit, apiPlugin } from '@storyblok/react';
import * as components from './components';
import FallbackComponent from './components/Fallback';

storyblokInit({
  accessToken: process.env.REACT_APP_STORYBLOK_TOKEN,
  use: [apiPlugin],
  components,
  enableFallbackComponent: true,
  customFallbackComponent: FallbackComponent,
  resolveRelations: ['author', 'category'],
  resolveLinks: 'story',
});
```
```

--------------------------------

### storyblokInit(pluginOptions)

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit-rsc.md

Initializes the Storyblok SDK for React Server Components, returning a getter function for the StoryblokClient instance.

```APIDOC
## storyblokInit(pluginOptions)

### Description
Initializes the Storyblok API client and component registry for React Server Components. It ensures a singleton instance is created and cached for server-side usage.

### Signature
`const storyblokInit = (pluginOptions?: SbReactSDKOptions): (() => StoryblokClient)`

### Parameters
- **pluginOptions** (SbReactSDKOptions) - Optional - Configuration object for SDK initialization.

### Return Type
Returns a function that returns `StoryblokClient`.
```

--------------------------------

### Initialize and Use Storyblok Client-Side

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/README.md

Requires initialization at the application entry point. Use the useStoryblok hook to fetch data and StoryblokComponent to render blocks.

```typescript
import { storyblokInit, apiPlugin, useStoryblok, StoryblokComponent } from '@storyblok/react';
import Page from './components/Page';

// Initialize once at app startup
storyblokInit({
  accessToken: 'your_token',
  use: [apiPlugin],
  components: { page: Page },
});

// Use in components
function Home() {
  const story = useStoryblok('home');
  return story ? <StoryblokComponent blok={story.content} /> : null;
}
```

--------------------------------

### SDK Functions

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

Core functions for SDK initialization, API client access, and component registration.

```APIDOC
## Functions

- **storyblokInit**: Initialize client-side SDK.
- **storyblokInit (RSC)**: Initialize server-side SDK.
- **getStoryblokApi**: Get initialized API client.
- **setComponents**: Register components after init.
- **getComponent**: Look up component by name.
- **componentResolver**: Built-in resolver for embedded components.
- **convertAttributesInElement**: Convert HTML attributes to JSX.
- **liveEditUpdateAction**: Server action for live editing updates.
```

--------------------------------

### storyblokInit

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

Initializes the Storyblok SDK with the provided access token, plugins, and component mapping.

```APIDOC
## storyblokInit

### Description
Initializes the Storyblok SDK instance.

### Parameters
- **accessToken** (string) - Required - The Storyblok access token.
- **use** (array) - Optional - Plugins to use, such as apiPlugin.
- **components** (object) - Optional - A mapping of component names to React components.
```

--------------------------------

### Configure playground dependencies

Source: https://github.com/storyblok/storyblok-react/blob/main/CONTRIBUTING.md

Add the local package as a dependency in the playground's package.json.

```json
{
  "dependencies": {
    "@storyblok/react": "workspace:^"
  }
}
```

--------------------------------

### Nested Layout Initialization

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokServerComponent.md

Initialize the Storyblok SDK with components in the root layout.

```typescript
// app/layout.tsx
import { storyblokInit, apiPlugin } from '@storyblok/react/rsc';
import Page from './components/Page';
import Teaser from './components/Teaser';
import Grid from './components/Grid';

storyblokInit({
  accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
  components: {
    page: Page,
    teaser: Teaser,
    grid: Grid,
  },
});

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

--------------------------------

### Initialize Storyblok with Global Relations and Links

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit.md

Configuration for resolving specific relations and link types globally across all requests.

```typescript
storyblokInit({
  accessToken: 'your_access_token',
  use: [apiPlugin],
  components: { page: Page },
  resolveRelations: ['author', 'category'],
  resolveLinks: 'story',
});
```

--------------------------------

### Implement basic server-side rendering

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/useStoryblokState.md

Use the hook to enable visual editing for stories fetched during server-side rendering.

```typescript
import { useStoryblokState } from '@storyblok/react';
import type { ISbStoryData } from '@storyblok/react';
import StoryblokComponent from './StoryblokComponent';

async function getStory(slug: string) {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get(`cdn/stories/${slug}`);
  return data.story;
}

export default function Page({ storyData }: { storyData: ISbStoryData }) {
  const story = useStoryblokState(storyData);

  return story ? (
    <div>
      <h1>{story.name}</h1>
      <StoryblokComponent blok={story.content} />
    </div>
  ) : null;
}
```

--------------------------------

### Basic useStoryblok Usage

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/useStoryblok.md

Fetches a story by slug and renders it using the StoryblokComponent.

```typescript
import { useStoryblok, StoryblokComponent } from '@storyblok/react';

function Home() {
  const story = useStoryblok('home');

  if (!story?.content) {
    return <div>Loading...</div>;
  }

  return <StoryblokComponent blok={story.content} />;
}
```

--------------------------------

### Dynamic Routes with ISR

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit-rsc.md

Implement dynamic routing and Incremental Static Regeneration for blog posts.

```typescript
// app/blog/[slug]/page.tsx
import { getStoryblokApi, StoryblokStory } from '@storyblok/react/rsc';

export const revalidate = 3600; // Revalidate every hour

async function getBlogPost(slug: string) {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get(`cdn/stories/blog/${slug}`, {
    version: 'published',
    resolve_relations: 'author'
  });
  return data.story;
}

export async function generateStaticParams() {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get('cdn/stories', {
    version: 'published',
    starts_with: 'blog/',
    per_page: 100
  });

  return data.stories.map(story => ({
    slug: story.slug
  }));
}

export default async function BlogPost({
  params: { slug }
}: {
  params: { slug: string };
}) {
  const story = await getBlogPost(slug);

  return (
    <article>
      <h1>{story.name}</h1>
      <StoryblokStory story={story} />
    </article>
  );
}
```

--------------------------------

### Basic Rich Text Rendering

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/useStoryblokRichText.md

Initializes the hook and renders a rich text document without custom resolvers.

```typescript
import { useStoryblokRichText } from '@storyblok/react';

function RichTextProcessor({ doc }) {
  const { render } = useStoryblokRichText({});
  return render(doc);
}
```

--------------------------------

### Root Layout Initialization

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit-rsc.md

Initialize Storyblok within the root layout of a Next.js application.

```typescript
// app/layout.tsx
import { storyblokInit, apiPlugin } from '@storyblok/react/rsc';
import * as components from '@/components';
import type { Metadata } from 'next';

// Initialize on first import
storyblokInit({
  accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
  components,
});

export const metadata: Metadata = {
  title: 'My App',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

--------------------------------

### useStoryblok

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

Fetches a story by its slug and returns the story object.

```APIDOC
## useStoryblok

### Description
Fetches a story from the Storyblok API using the provided slug.

### Parameters
- **slug** (string) - Required - The slug of the story to fetch.
```

--------------------------------

### Fetch stories with API parameters

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Shows how to use ISbStoriesParams to configure a request to the Storyblok API.

```typescript
import { getStoryblokApi } from '@storyblok/react';
import type { ISbStoriesParams } from '@storyblok/react';

const params: ISbStoriesParams = {
  version: 'published',
  starts_with: 'blog/',
  sort_by: 'created_at:desc',
  resolve_relations: ['author'],
  per_page: 10,
};

const api = getStoryblokApi();
const { data } = await api.get('cdn/stories', params);
```

--------------------------------

### Initialize Storyblok SDK correctly

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/configuration.md

Ensure storyblokInit is called before the application renders to avoid initialization errors.

```typescript
// Wrong order
<App /> // Throws error
storyblokInit({ ... })

// Correct order
storyblokInit({ ... })
<App />
```

--------------------------------

### Implement MyBlock component

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

Demonstrates using the SbBlokData type to type-check a component prop.

```typescript
import { StoryblokComponent } from '@storyblok/react';
import type { SbBlokData } from '@storyblok/react';

function MyBlock({ blok }: { blok: SbBlokData }) {
  return <StoryblokComponent blok={blok} />;
}
```

--------------------------------

### Main SDK Exports

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/README.md

Client-side utilities and components exported from the primary @storyblok/react entry point.

```typescript
export { useStoryblok }
export { useStoryblokState }
export { getStoryblokApi }
export { storyblokInit }
export { setComponents }
export { getComponent }
export { StoryblokComponent }
export { StoryblokRichText }
export { useStoryblokRichText }
export { convertAttributesInElement }
export * from './types'  // All types
export * from '@storyblok/js'  // Re-exported from base SDK
```

--------------------------------

### Configure Next.js Environment Variables

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/configuration.md

Defines environment variables for Next.js, using NEXT_PUBLIC_ for browser-accessible variables.

```bash
NEXT_PUBLIC_STORYBLOK_ACCESS_TOKEN=your_token
STORYBLOK_API_URL=https://api.storyblok.com
```

--------------------------------

### Shared Configuration for Multiple Layouts

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/storyblokInit-rsc.md

Use a shared initialization function to manage Storyblok configuration across multiple layouts.

```typescript
// app/config/storyblok.ts
'use server';

import { storyblokInit, apiPlugin } from '@storyblok/react/rsc';
import * as components from '@/components';

let initialized = false;

export function initStoryblok() {
  if (initialized) return;
  
  storyblokInit({
    accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
    use: [apiPlugin],
    components,
  });
  
  initialized = true;
}

// app/layout.tsx
import { initStoryblok } from './config/storyblok';

initStoryblok();

export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

// app/admin/layout.tsx
import { initStoryblok } from '../config/storyblok';

initStoryblok();

export default function AdminLayout({ children }) {
  return (
    <div className="admin">
      {children}
    </div>
  );
}
```

--------------------------------

### useStoryblok with API Options

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/useStoryblok.md

Fetches a story with specific API parameters like version and relation resolution.

```typescript
function BlogPost() {
  const story = useStoryblok(
    'blog/my-post',
    {
      version: 'draft',
      resolve_relations: ['author', 'category'],
      resolve_links: 'story'
    }
  );

  if (!story) {
    return <div>Loading...</div>;
  }

  return (
    <article>
      <h1>{story.name}</h1>
      <StoryblokComponent blok={story.content} />
    </article>
  );
}
```

--------------------------------

### Basic Usage

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokComponent.md

Standard implementation of StoryblokComponent within a page.

```typescript
import { StoryblokComponent } from '@storyblok/react';

function Page({ story }) {
  if (!story?.content) return null;

  return (
    <main>
      <StoryblokComponent blok={story.content} />
    </main>
  );
}
```

--------------------------------

### Import Server-Side RSC Modules

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

Use this entry point specifically for React Server Components and the Next.js App Router.

```typescript
import {
  storyblokInit,
  getStoryblokApi,
  setComponents,
  getComponent,
  useStoryblokRichText,
  StoryblokServerComponent,
  StoryblokStory,
  StoryblokRichText,
  StoryblokLiveEditing,
  liveEditUpdateAction,
} from '@storyblok/react/rsc';
```

--------------------------------

### getStoryblokApi()

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/getStoryblokApi.md

Retrieves the global Storyblok API client instance initialized by storyblokInit(). Returns null if not initialized.

```APIDOC
## getStoryblokApi()

### Description
Retrieves the initialized Storyblok API client instance. It provides access to the underlying HTTP client for making direct API calls to Storyblok's Content Delivery API and Management API.

### Signature
`const getStoryblokApi = (): StoryblokClient | null`

### Parameters
None.

### Return Type
- **StoryblokClient | null** - The API client instance if initialized via storyblokInit(), or null if not initialized.

### Usage Example
```typescript
import { getStoryblokApi } from '@storyblok/react';

const sbApi = getStoryblokApi();
if (sbApi) {
  const { data } = await sbApi.get('cdn/stories/home', { version: 'draft' });
}
```
```

--------------------------------

### useStoryblokState(initialStory, bridgeOptions)

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/useStoryblokState.md

The useStoryblokState hook accepts an initial story object and optional bridge configuration, returning the reactive story state.

```APIDOC
## useStoryblokState(initialStory, bridgeOptions)

### Description
Manages pre-fetched story data and enables real-time visual editing bridge integration.

### Signature
`const useStoryblokState = <T = void>(initialStory: ISbStoryData<T> | null, bridgeOptions?: StoryblokBridgeConfigV2): ISbStoryData<T> | null`

### Parameters
- **initialStory** (ISbStoryData<T> | null) - Required - The pre-fetched story data object.
- **bridgeOptions** (StoryblokBridgeConfigV2) - Optional - Configuration object for the Storyblok visual editing bridge.

### Returns
- **ISbStoryData<T> | null** - The current story state, which updates automatically when visual editing changes occur.

### Usage Example
```typescript
import { useStoryblokState } from '@storyblok/react';

export default function Page({ storyData }) {
  const story = useStoryblokState(storyData, {
    resolveRelations: ['author']
  });

  if (!story) return null;

  return <div>{story.name}</div>;
}
```
```

--------------------------------

### In Custom Renderer

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/getComponent.md

Using React.createElement to dynamically render components with fallback UI for missing definitions.

```typescript
import { getComponent } from '@storyblok/react';
import React from 'react';

function DynamicRenderer({ blok, ...props }) {
  const Component = getComponent(blok.component);
  
  if (!Component || Component === false) {
    return (
      <div className="missing-component">
        <p>Component '{blok.component}' not found</p>
        <details>
          <summary>Debug Info</summary>
          <pre>{JSON.stringify(blok, null, 2)}</pre>
        </details>
      </div>
    );
  }
  
  return React.createElement(Component, { blok, ...props });
}
```

--------------------------------

### Configure Vite alias for local development

Source: https://github.com/storyblok/storyblok-react/blob/main/CONTRIBUTING.md

Resolve the package from the local file system in vite.config.ts for debugging.

```ts
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: {
      '@storyblok/react': resolve(__dirname, '../src/index.ts'),
    },
  },
});
```

--------------------------------

### useStoryblok with Bridge Options

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/useStoryblok.md

Configures the visual editing bridge with custom options.

```typescript
function EditableStory() {
  const story = useStoryblok(
    'home',
    { version: 'draft' },
    {
      resolveRelations: ['author'],
      resolveLinks: 'story',
      customParent: 'my-app'
    }
  );

  return story ? <StoryblokComponent blok={story.content} /> : null;
}
```

--------------------------------

### Implement Revalidation

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokStory.md

Configure Next.js revalidation and static parameter generation for optimized content delivery.

```typescript
// app/blog/[slug]/page.tsx
import { getStoryblokApi, StoryblokStory } from '@storyblok/react/rsc';

export const revalidate = 3600; // Revalidate every hour

async function getBlogPost(slug: string) {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get(`cdn/stories/blog/${slug}`, {
    version: 'published'
  });
  return data.story;
}

export async function generateStaticParams() {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get('cdn/stories', {
    version: 'published',
    starts_with: 'blog/',
    per_page: 100
  });

  return data.stories.map(story => ({
    slug: story.slug
  }));
}

export default async function BlogPost({
  params: { slug }
}: {
  params: { slug: string };
}) {
  const story = await getBlogPost(slug);
  return <StoryblokStory story={story} />;
}
```

--------------------------------

### Register Components After Initialization

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/setComponents.md

Standard registration of components after the Storyblok SDK has been initialized.

```typescript
import { storyblokInit, apiPlugin, setComponents } from '@storyblok/react';
import Page from './components/Page';
import Teaser from './components/Teaser';
import Grid from './components/Grid';

storyblokInit({
  accessToken: 'your_token',
  use: [apiPlugin],
});

// Register components after initialization
setComponents({
  page: Page,
  teaser: Teaser,
  grid: Grid,
});
```

--------------------------------

### Basic Lookup

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/getComponent.md

Standard implementation for rendering a component based on the blok component name.

```typescript
import { getComponent } from '@storyblok/react';

function renderComponent(blok) {
  const Component = getComponent(blok.component);
  
  if (Component) {
    return <Component blok={blok} />;
  }
  
  return <div>Component not found</div>;
}
```

--------------------------------

### Render in Nested Components

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokStory.md

Initialize the Storyblok SDK and render stories across different parts of the application layout.

```typescript
// app/layout.tsx
import { storyblokInit, apiPlugin } from '@storyblok/react/rsc';
import Header from './components/Header';
import Footer from './components/Footer';
import Teaser from './components/Teaser';
import Page from './components/Page';

storyblokInit({
  accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
  use: [apiPlugin],
  components: {
    header: Header,
    footer: Footer,
    teaser: Teaser,
    page: Page,
  },
});

// app/page.tsx
import { getStoryblokApi, StoryblokStory } from '@storyblok/react/rsc';

async function getHeaderFooter() {
  const sbApi = getStoryblokApi();
  const { data: header } = await sbApi.get('cdn/stories/header', {
    version: 'published'
  });
  const { data: footer } = await sbApi.get('cdn/stories/footer', {
    version: 'published'
  });
  return { header: header.story, footer: footer.story };
}

async function getHome() {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get('cdn/stories/home', { version: 'published' });
  return data.story;
}

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const { header, footer } = await getHeaderFooter();

  return (
    <html>
      <body>
        <StoryblokStory story={header} />
        {children}
        <StoryblokStory story={footer} />
      </body>
    </html>
  );
}

async function HomePage() {
  const story = await getHome();
  return <StoryblokStory story={story} />;
}
```

--------------------------------

### SDK Components

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

React components for rendering Storyblok blocks, stories, and rich text content.

```APIDOC
## Components

- **StoryblokComponent**: Render Storyblok blocks dynamically.
- **StoryblokServerComponent**: Render blocks in RSC context.
- **StoryblokStory**: Story wrapper with live editing.
- **StoryblokRichText**: Render rich text documents.
- **StoryblokLiveEditing**: Live editing integration for RSC.
```

--------------------------------

### Load Components Dynamically

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/setComponents.md

Using Next.js dynamic imports to load components only when needed.

```typescript
import { setComponents } from '@storyblok/react';
import dynamic from 'next/dynamic';

const DynamicPage = dynamic(() => import('./components/Page'));
const DynamicTeaser = dynamic(() => import('./components/Teaser'));
const DynamicGrid = dynamic(() => import('./components/Grid'));

setComponents({
  page: DynamicPage,
  teaser: DynamicTeaser,
  grid: DynamicGrid,
});
```

--------------------------------

### Render Rich Text

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/INDEX.md

Render rich text documents with custom resolvers.

```typescript
<StoryblokRichText doc={richTextDoc} resolvers={{ ... }} />
```

--------------------------------

### useStoryblokState

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/types.md

A generic hook that manages story state with visual editing bridge integration.

```APIDOC
## useStoryblokState

### Description
Generic hook that manages story state with visual editing bridge integration.

### Signature
`type TUseStoryblokState = <T = void>(initialStory: ISbStoryData<T> | null, bridgeOptions?: StoryblokBridgeConfigV2) => ISbStoryData<T> | null`

### Parameters
- **T** (Generic) - Optional - Generic type for custom story content
- **initialStory** (ISbStoryData<T> | null) - Required - Pre-fetched story data
- **bridgeOptions** (StoryblokBridgeConfigV2) - Optional - Bridge configuration
```

--------------------------------

### Standalone Usage

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokLiveEditing.md

Manual implementation of StoryblokLiveEditing in a client-side component.

```typescript
// app/page.tsx
'use client';

import { useEffect, useState } from 'react';
import { getStoryblokApi, StoryblokServerComponent, StoryblokLiveEditing } from '@storyblok/react/rsc';
import type { ISbStoryData } from '@storyblok/react/rsc';

export default async function Home() {
  const sbApi = getStoryblokApi();
  const { data } = await sbApi.get('cdn/stories/home', { version: 'draft' });

  return (
    <>
      <StoryblokServerComponent blok={data.story.content} />
      <StoryblokLiveEditing story={data.story} />
    </>
  );
}
```

--------------------------------

### Handle Dynamic Routes

Source: https://github.com/storyblok/storyblok-react/blob/main/_autodocs/api-reference/StoryblokStory.md

Use dynamic route parameters to fetch and render specific story content based on the URL slug.

```typescript
// app/blog/[slug]/page.tsx
import { getStoryblokApi, StoryblokStory } from '@storyblok/react/rsc';
import type { ISbStoriesParams } from '@storyblok/react/rsc';

async function getBlogPost(slug: string) {
  const sbApi = getStoryblokApi();
  const sbParams: ISbStoriesParams = {
    version: 'published',
    resolve_relations: 'author'
  };
  const { data } = await sbApi.get(`cdn/stories/blog/${slug}`, sbParams);
  return data.story;
}

export default async function BlogPost(props: {
  params: Promise<{ slug: string }>;
}) {
  const params = await props.params;
  const story = await getBlogPost(params.slug);

  if (!story) {
    return <div>Post not found</div>;
  }

  return (
    <article>
      <h1>{story.name}</h1>
      <StoryblokStory story={story} />
    </article>
  );
}
```
Tokens:
Raw