feat!: making livepreview stable and removing useStoryblok function

[dipankarmaikap]

This PR stabilizes the experimental Live Preview feature and introduces breaking changes. The useStoryblok hook is now deprecated and replaced by the new getLiveStory function. Below are the key updates and usage examples.

Breaking Changes

1. Removal of useStoryblok:
   The useStoryblok hook has been deprecated in favor of getLiveStory. This function simplifies the implementation of live preview in your Astro application.

2. Named Export for storyblok:
   The storyblok initialization is now exported as a named export instead of a default export. Update your astro.config.mjs imports accordingly.

---

Usage Example

Configure Storyblok in astro.config.mjs using the named export:

import { storyblok } from '@storyblok/astro';

export default {
  integrations: [
    storyblok({
      accessToken: 'OsvN....',
      bridge: {
        resolveRelations: ['featured-articles.posts'],
      },
      enableFallbackComponent: true,
      livePreview: true,
    }),
  ],
};

Page Example

Here’s how you can use getLiveStory in a page:

---
// pages/[...slug].astro
import {
  getLiveStory,
  useStoryblokApi,
  type ISbStoryData,
} from '@storyblok/astro';
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro';
import BaseLayout from '../layouts/Layout.astro';

const { slug } = Astro.params;
let story: ISbStoryData | null = null;

const liveStory = await getLiveStory(Astro);
if (liveStory) {
  story = liveStory;
} else {
  const sbApi = useStoryblokApi();
  const { data } = await sbApi.get(`cdn/stories/${slug || 'home'}`, {
    version: 'draft',
    resolve_relations: ['featured-articles.posts'],
  });
  story = data?.story;
}
---

<BaseLayout>
  {story && <StoryblokComponent blok={story.content} />}
</BaseLayout>

Listening for Live Preview Updates

When the live preview updates content in the Storyblok editor, a custom event (storyblok-live-preview-updated) is triggered. Applications can listen for this event as follows:

<script>
  document.addEventListener("storyblok-live-preview-updated", () => {
    console.log("Live preview: body updated");
  });
</script>

Closing Issues

This PR addresses and closes the following issue(s):

• Closes Live Preview: dispatch an event after DOM is updated #864
• Closes script for loadStoryblokBridge is injected twice #943
• Closes useStoryblok not working with Astro Server Islands #907
• Closes Wrong Return type for useStoryblok() #895

[alexjoverm]

Hey @dipankarmaikap this is a great PR, thanks! The named export is ideal for bundling as is set as a standard, and I like how the getLiveStory it's particularly adapted for Astro's api needs.

I added you a comment about a typo.

Also, can we add some tests on the new feature/changes? I know some parts of this SDK might not be too easy to test, mostly due to Astro integration. However, as a general developing practice, we should always ensure that what we publish is decently tested, at least with some minimal tests.

[alexjoverm]

@dipankarmaikap I think there is a typo on the filename, do you mean helpers?

[JakiChen]

heyyyy, @dipankarmaikap, @alexjoverm I'm not sure if that's more straightforward：It is to directly allow users to access liveStory through locals

• Or it can solve the problem that Astro needs to be manually configured directly as a context.

• Or simply provide a LiveStorkyblokComponents?

Finally, thanks to the team's efforts and improvements, this is the most user-friendly headless CMS I've experienced so far

---
// pages/[...slug].astro
import {
  getLiveStory,
  useStoryblokApi,
  type ISbStoryData,
} from '@storyblok/astro';
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro';
import BaseLayout from '../layouts/Layout.astro';

const { slug } = Astro.params;
let story: ISbStoryData | null = null;

if (Astro.locals.liveStory) {
  story = liveStory;
} else {
  const sbApi = useStoryblokApi();
  const { data } = await sbApi.get(`cdn/stories/${slug || 'home'}`, {
    version: 'draft',
    resolve_relations: ['featured-articles.posts'],
  });
  story = data?.story;
}
---

<BaseLayout>
  {story && <StoryblokComponent blok={story.content} />}
</BaseLayout>