feat(space-next): add next.js starter for Space plugin (#82)

* feat(space-next): add next.js starter for Space plugin

* feat(space-next): support App Bridge (#83)

* feat(space-next): support App Bridge

* add more examples

* update README

* fix: incomplete implemention using Next.js middleware

* Revert "fix: incomplete implemention using Next.js middleware"

This reverts commit 6a113a6.

* update .env.example

.github/workflows/pr-title.yml

@@ -16,6 +16,7 @@ jobs:
             story
             tool-next
             tool-nuxt
+            space-next
             space-nuxt-base
             space-nuxt-base-ui
             space-nuxt-starter

space-plugins/nextjs-starter/.env.local.example

@@ -0,0 +1,3 @@
+CLIENT_ID=
+CLIENT_SECRET=
+BASE_URL=

space-plugins/nextjs-starter/.gitignore

@@ -0,0 +1,48 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.idea/
+
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+
+.env.local

space-plugins/nextjs-starter/README.md

@@ -0,0 +1,131 @@
+# Storyblok Space Starter x Next.js
+
+This is a starter template for Storyblok Space Plugins, created with Next.js (Pages Router) and [@storyblok/app-extension-auth](https://github.com/storyblok/app-extension-auth).
+
+## Getting Started
+
+```shell
+npx giget@latest gh:storyblok/space-tool-plugins/space-plugins/nextjs-starter YOUR-PROJECT-NAME
+```
+
+## How to run
+
+Navigate to your project folder and install dependencies by running:
+
+```shell
+cd YOUR-PROJECT-NAME
+
+yarn install # pnpm install or npm install
+```
+
+Set up a secure tunnel to proxy your request to/from `localhost:3000`, for example, with [ngrok](https://ngrok.com/):
+
+```shell
+ngrok http 3000
+```
+
+Note down your assigned URL; this will be your `baseUrl` for the application.
+
+### Create a new Storyblok Extension
+
+There are two ways on how you can create a Space Plugin inside Storyblok. Depending on your plan and use case, choose one of the following options:
+
+#### Partner Portal
+
+1. Open [Storyblok's Partner Portal Extension View](https://app.storyblok.com/#/partner/apps)
+2. Click On **New Extension**
+3. Fill in the fields `name` and `slug`
+4. Select `Sidebar` as extension type
+5. Click on **Save**
+
+#### Organization
+
+1. Open [Storyblok's Organization Extension View](https://app.storyblok.com/#/me/org/apps)
+2. Click On **New Extension**
+3. Fill in the fields `name` and `slug`
+4. Select `Sidebar` as extension type
+5. Click on **Save**
+
+### Configuration
+
+Once the extension has been created, a new entry will appear inside the extension list. Open it and navigate to the `OAuth 2.0 and Pages` tab.
+
+Configure the following properties based on the previous steps:
+
+- **Index to your page**: `{baseUrl}`
+- **Redirection endpoint**: `{baseUrl}/api/connect/callback`
+
+### Configure Starter Environment Variables
+
+Rename the file `.env.local.example` to `.env.local`. Open the file and set the environmental variables:
+
+- `CLIENT_ID`: the client ID from the extension's settings page.
+- `CLIENT_SECRET`: the client secret from the extension's settings page.
+- `BASE_URL`: The `baseUrl` from your secure tunnel.
+
+Start the application by running:
+
+```shell
+yarn dev # pnpm dev or npm run dev
+```
+
+### App Bridge
+
+App Bridge is an extra authentication layer recently introduced for Space Plugins and Tool Plugins. This starter assumes you've enabled App Bridge on the Settings page. Documentation on App Bridge will come in the near future, but you don't need to know about its inner process. This starter addresses a large portion of this aspect out of the box.
+
+<img src="./docs/app-bridge.png" alt="App Bridge" width="600" />
+
+If you don't want to use App Bridge, you can use [the legacy template](https://github.com/storyblok/custom-app-examples/tree/main/app-nextjs-starter).
+
+### App Bridge in Depth
+
+App Bridge authentication starts on the frontend by sending a postMessage to `app.storyblok.com`. In the `src/pages/index.tsx` file, you can find the following code:
+
+```jsx
+const { completed } = useAppBridge({ type: 'space-plugin', oauth: true });
+
+return (
+	<div>
+		{completed && (
+			<div>
+				<UserInfo />
+				<Test />
+			</div>
+		)}
+	</div>
+);
+```
+
+The code above handles both App Bridge authentication and OAuth.
+
+1. If you need to use Storyblok's Management API:
+
+After completing both authentications, the `<UserInfo />` component is rendered. This component sends a request to `/api/user_info`. The OAuth token is automatically included in the request as a cookie, and the endpoint retrieves the session using `await getAppSession(req, res)`. It then fetches user information from Storyblok's Management API using the OAuth token.
+
+2. If you don't need the Management API but still want to validate the request on the backend:
+
+When the `<Test />` component is rendered, it makes a request to `/api/test`. We attach the App Bridge token as a header. The endpoint verifies the token using `await verifyAppBridgeHeader(req)`. Only if the token is verified can you perform any desired action.
+
+### Extension Installation
+
+Finally, install the application to your space:
+
+1. Navigate to the extension's settings page.
+2. Open the **General Tab**.
+3. Open the **Install Link** in a new browser tab.
+4. Select a space the Space Plugin should be installed to.
+5. Open the selected space from Step 4.
+6. Click `Apps > <Your Extension Name>` on the sidebar.
+
+The installation process is only done once per space. After the installation is finished, you will be able to navigate to the Apps section on the sidebar and access the Space Plugin.
+
+## Production
+
+When deploying your Space Plugin, please remember to adjust the extension settings inside the Storyblok App to point to the correct **Index to your page** and **Redirection endpoint**.
+
+## Read More
+
+For more detailed information on Storyblok extensions, read the following guides:
+
+- [Space Plugin](https://www.storyblok.com/docs/plugins/custom-application)
+- [OAuth 2.0 Authorization Flow](https://www.storyblok.com/docs/plugins/authentication-apps)

space-plugins/nextjs-starter/next.config.js

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+	reactStrictMode: true,
+};
+
+module.exports = nextConfig;

space-plugins/nextjs-starter/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "tool-nextjs-starter",
+	"version": "0.1.0",
+	"private": true,
+	"scripts": {
+		"dev": "next dev",
+		"build": "next build",
+		"start": "next start",
+		"lint": "next lint"
+	},
+	"dependencies": {
+		"@storyblok/app-extension-auth": "2.0.0",
+		"jsonwebtoken": "^9.0.2",
+		"next": "13.4.19",
+		"react": "18.2.0",
+		"react-dom": "18.2.0",
+		"typescript": "5.2.2"
+	},
+	"devDependencies": {
+		"@types/jsonwebtoken": "^9.0.6",
+		"@types/node": "20.5.9",
+		"@types/react": "18.2.21",
+		"@types/react-dom": "18.2.7"
+	}
+}