|
| 1 | +# Story Starter |
| 2 | + |
| 3 | +The Story Starter is a [Space Plugin](https://www.storyblok.com/docs/plugins/custom-application) 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 | +<img src="./assets/storyblok-extensions.png" alt="Storyblok Extensions" width="200" /> |
| 33 | + |
| 34 | +2. Click the "New Extension" button in the top right corner and enter the necessary information. |
| 35 | + |
| 36 | +<img src="./assets/new-extensions.png" alt="New Extension" width="600" /> |
| 37 | + |
| 38 | +And then you can find the information. |
| 39 | + |
| 40 | +<img src="./assets/oauth.png" alt="OAuth information" width="600" /> |
| 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 the index URL and the redirection URL. The redirection URL ends with `/api/connect/callback`. |
| 49 | + |
| 50 | +<img src="./assets/urls-for-oauth.png" alt="Configure URLs for oauth" width="300" /> |
| 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 | +<img src="./assets/install-link.png" alt="Install Link" width="600" /> |
| 57 | + |
| 58 | +6. Start developing by running `yarn dev:nuxt`, and open it on Storyblok. |
| 59 | + |
| 60 | +<img src="./assets/open-extension.png" alt="Open the extension" width="200" /> |
| 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 | +<img src="./assets/deploy-subdir.png" alt="Vercel Deployment" width="600" /> |
| 69 | + |
| 70 | +You should configure the same environment variables on the hosting platform as well. |
0 commit comments