Skip to content

Commit

Permalink
feat: move storyblok/nuxt-beta to this repo
Browse files Browse the repository at this point in the history 
BREAKING CHANGE: upgrade to Nuxt 3
  • Loading branch information
@alexjoverm
alexjoverm committed May 13, 2022
1 parent 39be552 commit 2f4487b
Show file tree
Hide file tree
Showing 25 changed files with 22,828 additions and 28,366 deletions.
0 .github/workflows/tests.yml → .github/workflows/release.yml
View file
File renamed without changes.
3 changes: 2 additions & 1 deletion .gitignore
View file
Expand Up @@ -8,4 +8,5 @@ node_modules
coverage
dist
lib/cypress/videos
lib/cypress/screenshots
lib/cypress/screenshots
.output
2 changes: 1 addition & 1 deletion .prettierignore
View file
@@ -1 +1 @@
**/module/plugin.js
**/templates/plugin.js
122 changes: 47 additions & 75 deletions README.md
View file
Expand Up @@ -3,15 +3,15 @@
<img src="https://a.storyblok.com/f/88751/1776x360/b8979e5c96/sb-nuxt.png" alt="Storyblok Logo">
</a>
<h1 align="center">@storyblok/nuxt</h1>
<p align="center">Nuxt 2 module for the <a href="http://www.storyblok.com?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt" target="_blank">Storyblok</a>, Headless CMS.</p> <br />
<p align="center">Nuxt 3 module for the <a href="http://www.storyblok.com?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt" target="_blank">Storyblok</a>, Headless CMS.</p> <br />
</div>

<p align="center">
<a href="https://npmjs.com/package/@storyblok/nuxt">
<img src="https://img.shields.io/npm/v/@storyblok/nuxt/latest.svg?style=flat-square" alt="Storyblok JS Client" />
<a href="https://npmjs.com/package/@storyblok/nuxt-2">
<img src="https://img.shields.io/npm/v/@storyblok/nuxt-2/latest.svg?style=flat-square" alt="Storyblok JS Client" />
</a>
<a href="https://npmjs.com/package/@storyblok/nuxt" rel="nofollow">
<img src="https://img.shields.io/npm/dt/@storyblok/nuxt.svg?style=flat-square" alt="npm">
<a href="https://npmjs.com/package/@storyblok/nuxt-2" rel="nofollow">
<img src="https://img.shields.io/npm/dt/@storyblok/nuxt-2.svg?style=flat-square" alt="npm">
</a>
</p>

Expand All @@ -27,11 +27,13 @@
</a>
</p>

> Try out the **[LIVE DEMO](https://stackblitz.com/edit/nuxt-2-sdk-demo?file=pages%2Findex.vue&terminal=dev)** on Stackblitz and play with code yourself!
### Live Demo

If you are in a hurry, check out our official **[live demo](https://stackblitz.com/edit/nuxt-3-sdk-demo?file=pages/index.vue)** on Stackblitz.

## 🚀 Usage

_Note: This module is for Nuxt 2. [Check out `@storyblok/nuxt-beta` for Nuxt 3](https://github.com/storyblok/storyblok-nuxt-beta)_.
_Note: This module is for Nuxt 3. [Check out `@storyblok/nuxt-2` for Nuxt 2](https://github.com/storyblok/storyblok-nuxt-2)_.

> If you are first-time user of the Storyblok, read the [Getting Started](https://www.storyblok.com/docs/guide/getting-started?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt) guide to get a project ready in less than 5 minutes.
Expand All @@ -44,15 +46,30 @@ npm install @storyblok/nuxt
# yarn add @storyblok/nuxt
```

Initialize the module by adding it to buildModules section of `nuxt.config.js` and replace the accessToken with API token from Storyblok space:
Add following code to buildModules section of `nuxt.config.js` and replace the accessToken with API token from Storyblok space.

```js
{
import { defineNuxtConfig } from "nuxt";

export default defineNuxtConfig({
buildModules: [
["@storyblok/nuxt", { accessToken: "<your-access-token>" }]
// ...
["@storyblok/nuxt/module", { accessToken: "<your-access-token>" }],
];
}
]
});
```

You can also use the `storyblok` config if you prefer:

```js
import { defineNuxtConfig } from "nuxt";

export default defineNuxtConfig({
buildModules: ["@storyblok/nuxt"],
storyblok: {
accessToken: "<your-access-token>"
}
});
```

#### Options
Expand All @@ -61,7 +78,7 @@ When you initialize the module, you can pass all [_@storyblok/vue_ options](http

```js
// Defaults
["@storyblok/nuxt/module", {
["@storyblok/nuxt", {
{
accessToken: "<your-access-token>",
bridge: true,
Expand All @@ -71,13 +88,13 @@ When you initialize the module, you can pass all [_@storyblok/vue_ options](http
}]
```

## Getting started
### Getting started

### 1. Creating and linking your components to Storyblok Visual Editor

To link your Vue components to their equivalent you created in Storyblok:

- First, you need to load them globally. If you use Nuxt 2.13+, you can just place them on the `~/components/storyblok` directory, otherwise you can load them globally (for example, by [using a Nuxt plugin](https://stackoverflow.com/questions/43040692/global-components-in-vue-nuxt)).
- First, you need to load them globally. You can just place them on the `~/storyblok` directory and will be discovered automagically, otherwise you set another directory can load them manually (for example, by [using a Nuxt plugin](https://stackoverflow.com/questions/43040692/global-components-in-vue-nuxt)).

- For each components, use the `v-editable` directive on its root element, passing the `blok` property that they receive:

Expand All @@ -88,7 +105,7 @@ To link your Vue components to their equivalent you created in Storyblok:
- Finally, use `<StoryblokComponent>` which available globally in the Nuxt app:

```html
<StoryblokComponent blok="blok" />
<StoryblokComponent :blok="blok" />
```

> The `blok` is the actual blok data coming from [Storblok's Content Delivery API](https://www.storyblok.com/docs/api/content-delivery/v2?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt).
Expand All @@ -97,14 +114,11 @@ To link your Vue components to their equivalent you created in Storyblok:

#### Composition API

> To use Nuxt 2 with Composition API, make sure you installed the [@nuxtjs/composition-api](https://composition-api.nuxtjs.org/) plugin.
The simplest way is by using the `useStoryblok` one-liner composable, which uses the [useFetch from @nuxtjs/composition-api](https://composition-api.nuxtjs.org/lifecycle/useFetch) under the hood:
The simplest way is by using the `useStoryblok` one-liner composable (it's autoimported):

```html
<script setup>
import { useStoryblok } from "@storyblok/nuxt";
const { story, fetchState } = useStoryblok("vue", { version: "draft" });
const story = await useStoryblok("vue", { version: "draft" });
</script>

<template>
Expand All @@ -116,23 +130,15 @@ Which is the short-hand equivalent to using `useStoryblokApi` and `useStoryblokB

```html
<script setup>
import { onMounted, ref, useFetch } from "@nuxtjs/composition-api";
import { useStoryblokBridge, useStoryblokApi } from "@storyblok/nuxt";
const story = ref(null);
const { fetch } = useFetch(async () => {
const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get(`cdn/stories/vue/test`, {
version: "draft",
});
story.value = data.story;
const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get("cdn/stories/vue", {
version: "draft"
});
fetch();
story.value = data.story;
onMounted(async () => {
if (story.value && story.value.id)
useStoryblokBridge(story.value.id, (evStory) => (story.value = evStory));
onMounted(() => {
useStoryblokBridge(story.value.id, (evStory) => (story.value = evStory));
});
</script>

Expand All @@ -141,42 +147,11 @@ Which is the short-hand equivalent to using `useStoryblokApi` and `useStoryblokB
</template>
```

#### Options API

You can still use the `useStoryblokApi` and `useStoryblokBridge` as follows:

```html
<script>
import { useStoryblokBridge, useStoryblokApi } from "@storyblok/nuxt";
export default {
asyncData: async ({ app }) => {
const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get("cdn/stories/vue", {
version: "draft",
});
// OR: const { data } = await app.$storyapi.get("cdn/stories/vue", { version: "draft" });
return { story: data.story };
},
mounted() {
useStoryblokBridge(this.story.id, (newStory) => (this.story = newStory));
},
};
</script>

<template>
<StoryblokComponent v-if="story" :blok="story.content" />
</template>
```

> _As you see in the comment, you can also use `app.$storyapi` if that's more comfortable for you. It's injected into Nuxt context and available in the components instance via `this.$storyapi` as well._
### API

#### useStoryblok(slug, apiOptions, bridgeOptions)

Check the available [apiOptions](https://github.com/storyblok/storyblok-js-client#class-storyblok) (passed to `storyblok-js-client`) and [bridgeOptions](https://www.storyblok.com/docs/Guides/storyblok-latest-js?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt) (passed to the Storyblok Bridge).
Check the available [apiOptions](https://github.com/storyblok/storyblok-js-client#class-storyblok) (passed to `storyblok-js-client`) and [bridgeOptions](https://www.storyblok.com/docs/Guides/storyblok-latest-js?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt-beta) (passed to the Storyblok Bridge).

#### useStoryblokApi()

Expand All @@ -186,25 +161,22 @@ Returns the instance of the `storyblok-js-client`.

Use this one-line function to cover the most common use case: updating the story when any kind of change happens on Storyblok Visual Editor.

#### $storyapi

Equivalent to the client that `useStoryblokApi` returns, but accessible in the Nuxt context and components instance.

## 🔗 Related Links

- **[Live Demo on Stackblitz](https://stackblitz.com/edit/nuxt-2-sdk-demo?file=pages%2Findex.vue&terminal=dev)**
- **[Nuxt.js Hub](https://www.storyblok.com/tc/nuxtjs?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt)**: Learn how to develop your own Nuxt.js applications that use Storyblok APIs to retrieve and manage content.
- **[Storyblok & Nuxt.js on GitHub](https://github.com/search?q=org%3Astoryblok+topic%3Anuxt)**: Check all of our Nuxt.js open source repos.
- **[Live Demo on Stackblitz](https://stackblitz.com/edit/nuxt-3-sdk-demo?file=pages%2Findex.vue&terminal=dev)**
- **[Nuxt.js Hub](https://www.storyblok.com/tc/nuxtjs?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt-beta)**: Learn how to develop your own Nuxt.js applications that use Storyblok APIs to retrieve and manage content;
- **[Storyblok & Nuxt.js on GitHub](https://github.com/search?q=org%3Astoryblok+topic%3Anuxt)**: Check all of our Nuxt.js open source repos;
- **[Storyblok CLI](https://github.com/storyblok/storyblok)**: A simple CLI for scaffolding Storyblok projects and fieldtypes.

## ℹ️ More Resources

### Support

- Bugs or Feature Requests? [Submit an issue](/../../issues/new);

- Do you have questions about Storyblok or you need help? [Join our Discord Community](https://discord.gg/jKrbAMz).

### Contributing

Please see our [contributing guidelines](https://github.com/storyblok/.github/blob/master/contributing.md) and our [code of conduct](https://www.storyblok.com/trust-center#code-of-conduct?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt).
Please see our [contributing guidelines](https://github.com/storyblok/.github/blob/master/contributing.md) and our [code of conduct](https://www.storyblok.com/trust-center#code-of-conduct?utm_source=github.com&utm_medium=readme&utm_campaign=storyblok-nuxt-beta).
This project use [semantic-release](https://semantic-release.gitbook.io/semantic-release/) for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check [this question](https://semantic-release.gitbook.io/semantic-release/support/faq#how-can-i-change-the-type-of-commits-that-trigger-a-release) about it in semantic-release FAQ.

0 comments on commit 2f4487b

Please sign in to comment.