@kimonokit/storyblok-angular

Features

• 🔄 Real-time Visual Editor integration
• 🎯 Dynamic component loading
• 📝 Rich text rendering
• 🌐 Full TypeScript support
• 🚀 SSR (Server-Side Rendering) compatible
• 🔌 API client included

Installation

npm install @kimonokit/storyblok-angular

Quick Start

1. Import the StoryblokModule in your app.module.ts:

import { StoryblokModule } from "@kimonokit/storyblok-angular";

@NgModule({
  imports: [
    StoryblokModule.forRoot({
      accessToken: "your_access_token",
      bridge: true, // Enable Visual Editor
    }),
  ],
})
export class AppModule {}

2. Create your components and register them with Storyblok:

import { Component } from "@angular/core";
import { StoryblokComponent } from "@kimonokit/storyblok-angular";

@Component({
  selector: "app-teaser",
  template: `
    <div [storyblokEditable]="blok">
      <h2>{{ blok.headline }}</h2>
      <p>{{ blok.description }}</p>
    </div>
  `,
})
export class TeaserComponent {
  blok: any;
}

// Register your component
StoryblokDynamicComponent.registerComponent("teaser", TeaserComponent);

3. Use the StoryblokService to fetch content:

import { Component, OnInit } from "@angular/core";
import { StoryblokService } from "@kimonokit/storyblok-angular";

@Component({
  selector: "app-page",
  template: `
    <div *ngIf="story" [storyblokEditable]="story.content">
      <storyblok-component [blok]="story.content"></storyblok-component>
    </div>
  `,
})
export class PageComponent implements OnInit {
  story: any;

  constructor(private storyblok: StoryblokService) {}

  ngOnInit() {
    // Get your story
    this.storyblok.getStory("home").subscribe((story) => (this.story = story));

    // Listen for changes in Visual Editor
    this.storyblok.onStoryChange().subscribe((story) => {
      if (story) {
        this.story = story;
      }
    });
  }
}

API Reference

StoryblokService

The main service for interacting with Storyblok:

// Fetch a single story
storyblok.getStory(slug: string, params?: any): Observable<StoryblokStory>

// Fetch multiple stories
storyblok.getStories(params?: any): Observable<StoryblokStory[]>

// Listen for Visual Editor changes
storyblok.onStoryChange(): Observable<StoryblokStory | null>

// Render rich text
storyblok.renderRichText(data: any): string

// Access the underlying API client
storyblok.apiClient: StoryblokClient

StoryblokConfig

Configuration options when initializing the module:

interface StoryblokConfig {
  accessToken: string;
  version?: "draft" | "published";
  bridge?: boolean;
  richTextSchema?: any;
  apiOptions?: {
    region?: "us" | "eu" | "ap" | "ca" | "cn";
    cache?: any;
    [key: string]: any;
  };
}

Directives

• [storyblokEditable]: Makes a component editable in the Visual Editor
• <storyblok-component>: Dynamic component renderer

Region Configuration

For spaces created in regions other than EU, specify the region in the configuration:

StoryblokModule.forRoot({
  accessToken: "your_access_token",
  apiOptions: {
    region: "us", // 'us', 'eu', 'ap', 'ca', or 'cn'
  },
});

Rich Text Rendering

You can customize rich text rendering by providing a schema:

StoryblokModule.forRoot({
  accessToken: "your_access_token",
  richTextSchema: {
    // Your custom schema
  },
});

TypeScript Support

The SDK includes TypeScript definitions for all Storyblok interfaces:

import { StoryblokStory, StoryblokComponent } from "@kimonokit/storyblok-angular";

interface MyStoryContent extends StoryblokComponent {
  title: string;
  description: string;
}

// Use with generics
const story: StoryblokStory<MyStoryContent>;

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

Support

• 🐛 For bug reports and feature requests, open an issue
• 📚 For documentation, visit Storyblok Docs

License

This project is licensed under the MIT License - see the LICENSE file for details.