Skip to content

Commit f146bc8

Browse files
committed
docs: add README to story starter
1 parent d2222b9 commit f146bc8

10 files changed

+76
-0
lines changed

story-starter/.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.idea
2+
**/node_modules

story-starter/README.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Story Starter
2+
3+
The Story Starter is a Space Plugin template that appears on the sidebar of your Storyblok space. It offers essential features for retrieving stories, enabling users to select specific ones, and performing actions. You can implement the actions you want to perform in `stories.config.ts`.
4+
5+
## Getting Started
6+
7+
> [!NOTE]
8+
> Currently, the Story Starter is written only in Nuxt. However, please inform us if you would like to have a Next.js version. Feel free to create a GitHub issue to make the request.
9+
10+
```sh
11+
npx giget@latest gh:storyblok/space-tool-plugins/story-starter YOUR-PROJECT-NAME
12+
```
13+
14+
This repository is developed using [pnpm](https://pnpm.io/). However, you can also use Yarn or NPM.
15+
16+
```sh
17+
cd YOUR-PROJECT-NAME
18+
19+
pnpm install && pnpm run dev:nuxt
20+
# or
21+
yarn install && yarn run dev:nuxt
22+
# or
23+
npm install && npm run dev:nuxt
24+
```
25+
26+
## Configuration
27+
28+
You need to create a Storyblok extension that will provide you with OAuth credentials. Then, you should add this information to your `.env` file and your hosting platform.
29+
30+
1. You can find the "Extensions" menu under either the Partner Portal or the My Organization.
31+
32+
![Storyblok Extensions](./assets/storyblok-extensions.png)
33+
34+
2. Click the "New Extension" button in the top right corner and enter the necessary information.
35+
36+
![New Extension](./assets/new-extensions.png)
37+
38+
And then you can find the information.
39+
40+
![OAuth information](./assets/oauth.png)
41+
42+
3. Configure the following environment variables in `<ROOT-OF-YOUR-PROJECT>/starters/nuxt/.env`.
43+
44+
- `CLIENT_ID=`: Client Identifer
45+
- `CLIENT_SECRET=`: Client Secret
46+
- `BASE_URL=`: When using this starter, you should expose your local development server. To do this, we suggest using services like [ngrok](https://ngrok.com/). Let's say your hostname is `https://PUT-YOURS.ngrok.io`. Set that as your `BASE_URL`.
47+
48+
4. Configure your extension on Storyblok with base URL and oauth callback URL.
49+
50+
![Configure URLs for oauth](./assets/urls-for-oauth.png)
51+
52+
Ensure that "Production" is the section that contains information about the production deployment, while "Preview" refers to your development environment, such as exposing localhost through ngrok.
53+
54+
5. Open the "Install Link" in a new tab and install it in your space for the development and test.
55+
56+
![Install Link](./assets/install-link.png)
57+
58+
6. Start developing by running `yarn dev:nuxt`, and open it on Storyblok.
59+
60+
![Open the extension](./assets/open-extension.png)
61+
62+
7. Open the `starters/nuxt/stories.config.ts` file and implement your own actions. You can refer to the existing sample implementation for guidance.
63+
64+
8. Deploying
65+
66+
The starter is set up as a monorepo, and most hosting platforms support it seamlessly. For instance, Vercel recognizes it as a Nuxt project and automatically configures the root directory for you.
67+
68+
![Vercel Deployment](./assets/deploy-subdir.png)
69+
70+
You should configure the same environment variables on the hosting platform as well.
61.9 KB
Loading

story-starter/assets/install-link.png

60.2 KB
Loading
70.8 KB
Loading

story-starter/assets/oauth.png

81.2 KB
Loading
51.3 KB
Loading
45.9 KB
Loading
122 KB
Loading

story-starter/package.json

+4
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
"version": "0.0.1",
44
"description": "",
55
"private": true,
6+
"workspaces": [
7+
"starters/*",
8+
"packages/*"
9+
],
610
"scripts": {
711
"dev:nuxt": "pnpm -F nuxt dev"
812
},

0 commit comments

Comments
 (0)