docs: create nuxt essentials guide (#7336)

docs/content/guides/2.alokai-essentials/1.index.md

@@ -21,4 +21,12 @@ Learn how to build Alokai application with Next.js
 
 #description
 Learn how to build Alokai application with React Native
+::
+
+<br />
+
+::card{title="Alokai with Nuxt" icon="tabler:brand-nuxt" to="/guides/alokai-essentials/alokai-nuxt" }
+
+#description
+Learn how to build Alokai application with Nuxt
 ::

docs/content/guides/2.alokai-essentials/3.alokai-nuxt/1.index.md

@@ -0,0 +1,63 @@
+---
+title:
+layout: default
+---
+
+# Alokai Nuxt Guide
+
+Welcome to the Alokai Nuxt guide. This guide will help you get started with building your first Alokai application from the ground up.
+
+This guide that will allow you to understand how elements of Alokai stack play together by building a small version of a production storefront from scratch. We will cover everything from creating a new Alokai project to building a simple application that uses the Alokai products.
+
+## What You Will Learn
+
+- How to create a new Alokai project
+- How to build a simple Alokai application
+- How to use the Alokai products
+
+## Framework of Choice
+
+This guide will focus on [Nuxt](https://nuxt.com/) as the frontend framework of choice. Nuxt is a popular Vue.js framework that makes it easy to build server-rendered applications. It is a great choice for building Alokai applications because it is easy to use and has a large community of developers.
+
+Alokai, thanks to its modular [Architecture](/general/basics/architecture), can be used with any frontend framework.
+If you are interested in using Alokai with other frontend frameworks, check out our [guides](/guides) section for more information.
+
+## Enterprise vs Open Source
+
+Alokai comes in two editions: Enterprise and Open Source. This guide will focus on the Enterprise edition, but the same principles apply to the Open Source edition.
+
+You can find all available Alokai integrations in the [integrations](/integrations) section.
+
+## Prerequisites
+
+Before you start, you will need to have the following installed on your machine:
+
+- Node.js - we recommend using the latest LTS version - [download](https://nodejs.org/)
+- Package manager - we will use npm in this guide - [download](https://www.npmjs.com/get-npm)
+
+The guide was created and tested using the following versions our our packages:
+```json
+{
+    "@vsf-enterprise/sapcc-api": "^9.0.1",
+    "@vsf-enterprise/sapcc-types": "^3.0.2",
+    "@vsf-enterprise/unified-api-sapcc": "^4.0.0",
+    "@vue-storefront/middleware": "^5.2.0",
+    "@storefront-ui/nuxt": "^2.5.3",
+    "@vue-storefront/nuxt": "^6.2.0",
+    "@vsf-enterprise/sap-commerce-webservices-sdk": "^6.0.1",
+}
+```
+
+Let's get started!
+
+::card{title="Next: Create Alokai Nuxt project" icon="tabler:number-1-small" }
+
+#description
+Setup new Nuxt Alokai project and learn more about our architecture, products, and all of the ways that the Alokai ecosystem can help you build better storefronts.
+
+#cta
+:::docs-button{to="/guides/alokai-essentials/alokai-nuxt/create-project"}
+Start building
+:::
+::
+

docs/content/guides/2.alokai-essentials/3.alokai-nuxt/2.create-project.md

@@ -0,0 +1,72 @@
+---
+title: Create Alokai Project
+layout: default
+navigation:
+  icon: tabler:number-1-small
+---
+
+# Create new Alokai Nuxt Project
+
+For the base of our project, we will use the Alokai Nuxt starter project. This project is a great starting point for building an Alokai application with Nuxt. It includes everything you need to get started, including a basic project structure, configuration files, and a set of pre-configured tools.
+
+You can find the Alokai Nuxt starter project on GitHub.
+
+**Nuxt Starter Project** - [https://github.com/vuestorefront-community/nuxt-starter](https://github.com/vuestorefront-community/nuxt-starter)
+
+This is a bare minimum monorepo setup created with [Turbo](https://turbo.build/repo). During this guide, we will use the `nuxt-starter` project to create a new Alokai project. We will install all the necessary dependencies and configure the project to work with Alokai.
+
+## Prerequisites
+
+For this guide we will use SAP Commerce Cloud as the backend, but you can use any backend of your choice. Make sure you have your SAP Commerce Cloud instance up, running and accessible via REST API. 
+
+## Get the Alokai Nuxt Starter Project
+
+To create a new Alokai project with Nuxt, you will need to clone the `nuxt-starter` project from GitHub. You can do this by running the following command in your terminal:
+
+```bash
+git clone [email protected]:vuestorefront-community/nuxt-starter.git
+```
+
+Once you have cloned the `nuxt-starter` project, navigate to the project directory and install the project dependencies by running the following command:
+
+```bash
+cd nuxts-starter
+npm install
+```
+
+This will install all the necessary dependencies for the project.
+
+## Prepare the Project
+
+Now that you have the `nuxt-starter` project set up, you need to prepare the project to allow for both the Nuxt application and the Alokai Middleware to run in the monorepo.
+
+Let's first configure the `middleware` application. Run the following Turbo command to install the `middleware` application:
+
+```bash
+npx turbo gen workspace
+```
+
+It will prompt you to give a `name` to your workspace, as well as the name of the application. We will use `middleware` as the name of the application. In this case the `name` is the name of the workspace used by Turbo to manage the monorepo.
+
+![Generating new workspace](./images/nuxt-starter-2.webp)
+
+Once the workspace is generated, you will see a new `middleware` directory in the `apps` directory.
+
+Great, our workspace is ready. Now we can move on to the next step and configure the `middleware` application.
+
+## Summary
+
+In this section, we have learned how to create a new Alokai project with Nuxt. We have cloned the `nuxt-starter` project from GitHub and installed all the necessary dependencies. We have also prepared the project to allow for both the Nuxt application and the Alokai Middleware to run in the monorepo.
+
+In the next section, we will configure the `middleware` application and run it alongside the Nuxt application.
+
+::card{title="Next: Install and Configure Alokai Middleware" icon="tabler:number-2-small" }
+
+#description
+Learn what the Alokai Middleware is and how to install and configure it in your Alokai project.
+
+#cta
+:::docs-button{to="/guides/alokai-essentials/alokai-nuxt/install-middleware"}
+Next
+:::
+::

docs/content/guides/2.alokai-essentials/3.alokai-nuxt/3.install-middleware.md

@@ -0,0 +1,208 @@
+---
+title: Install Alokai Middleware
+layout: default
+navigation:
+  icon: tabler:number-2-small
+---
+
+# Install and Configure Alokai Middleware
+
+In the last section, we have installed the Nuxt application and created a new Alokai project. In this section, we will install and configure the Alokai Middleware.
+
+The Alokai Middleware is a Node.js application that acts as a bridge between the frontend application and the backend. It is responsible for handling all the API requests and responses, as well as managing the state of the application.
+
+In this guide, we will install the Alokai Middleware and configure it to work with SAP Commerce Cloud.
+
+## Install Alokai Middleware
+
+Navigate to a newly generated `middleware` directory and install the project dependencies by running the following command:
+
+```bash
+cd apps/middleware
+npm install @vue-storefront/middleware consola ts-node-dev
+```
+
+This will install all the necessary dependencies for the `middleware` application.
+
+## Install Alokai SAP Commerce Cloud Integration
+
+So far, we have installed the `middleware` application. But in order for it to run and communicate with SAP Commerce Cloud, we need to install the `@vsf-enterprise/sapcc-api` package. This package is a Alokai integration for SAP Commerce Cloud.
+
+SAP Commerce Cloud integration is part of our Enterprise offering. To access this package, you will need to have Alokai license to access to our private npm registry.
+
+:::info
+If you don't have access to our private npm registry, please [contact our sales team](https://vuestorefront.io/contact/sales).
+:::
+
+In the root of your project, open `.npmrc` file and add the following line:
+
+```bash
+@vsf-enterprise:registry=https://registrynpm.storefrontcloud.io
+auto-install-peers=true
+```
+
+Now you can install the `@vsf-enterprise/sapcc-api` package by running the following command from `apps/middleware` directory:
+
+```bash
+npm install @vsf-enterprise/sapcc-api
+```
+You can also install the types by running the following command:
+
+```bash
+npm install @vsf-enterprise/sapcc-types
+```
+
+## Configure Alokai Middleware
+
+Now that you have installed the `middleware` application and the SAP Commerce Cloud integration, you need to configure the `middleware` application to work with SAP Commerce Cloud. 
+
+To do this, you will need to create a new configuration file in the `apps/middleware` directory. Create a new file called `middleware.config.ts` and add the following code:
+
+```typescript
+require('dotenv').config();
+
+export const integrations = {
+  sapcc: {
+    location: '@vsf-enterprise/sapcc-api/server',
+    configuration: {
+      OAuth: {
+        uri: process.env.SAPCC_OAUTH_URI,
+        clientId: process.env.SAPCC_OAUTH_CLIENT_ID,
+        clientSecret: process.env.SAPCC_OAUTH_CLIENT_SECRET,
+        tokenEndpoint: process.env.SAPCC_OAUTH_TOKEN_ENDPOINT,
+        tokenRevokeEndpoint: process.env.SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
+        cookieOptions: {
+          'vsf-sap-token': { secure: process.env.NODE_ENV !== 'development' }
+        }
+      },
+      api: {
+        uri: process.env.SAPCC_API_URI,
+        baseSiteId: process.env.DEFAULT_BASE_SITE_ID,
+        catalogId: process.env.DEFAULT_CATALOG_ID,
+        catalogVersion: process.env.DEFAULT_CATALOG_VERSION,
+        defaultLanguage: process.env.DEFAULT_LANGUAGE,
+        defaultCurrency: process.env.DEFAULT_CURRENCY
+      }
+    }
+  }
+};
+```
+
+This configuration file will be used to configure the `middleware` application to work with SAP Commerce Cloud. It includes all the necessary configuration options for the SAP Commerce Cloud integration. 
+
+You will also need to create a new `.env` file in the `apps/middleware` directory and add the following environment variables:
+
+```bash
+SAPCC_OAUTH_URI=
+SAPCC_OAUTH_CLIENT_ID=
+SAPCC_OAUTH_CLIENT_SECRET=
+SAPCC_OAUTH_TOKEN_ENDPOINT=
+SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT=
+SAPCC_API_URI=
+
+DEFAULT_BASE_SITE_ID=
+DEFAULT_CATALOG_ID=
+DEFAULT_CATALOG_VERSION=
+DEFAULT_LANGUAGE=
+DEFAULT_CURRENCY=
+```
+
+Replace the environment variables with your SAP Commerce Cloud credentials.
+
+This will install the `dotenv` package, which is used to load environment variables from a `.env` file into `process.env`.
+
+## Run Alokai Middleware
+
+Our `middleware` application is now fully configured and ready to run. To start the `middleware` application, we need to create an entry point file in the `apps/middleware` directory. Create a new file called `index.ts` in the `apps/middleware/src` directory:
+
+```bash
+mkdir src
+touch src/index.ts
+```
+
+Add the following code to the `index.ts` file:
+
+```typescript
+import { createServer } from "@vue-storefront/middleware";
+import { integrations } from "../middleware.config";
+
+const port = Number(process.env.API_PORT) || 8181;
+
+runApp();
+
+async function runApp() {
+  const app = await createServer(
+    { integrations },
+    {
+      cors: {
+        origin: true,
+        credentials: true,
+      },
+    }
+  );
+
+  app.listen(port, "", () => {
+    console.log(`API server listening on port ${port}`);
+  });
+}
+
+```
+
+This code will create a new server instance and start the `middleware` application. It will also configure the CORS settings to allow requests from `http://localhost:3000`.
+
+The last step is to run the `middleware` application. In order to help you with that, we will use a `"dev"` script in the `package.json` file. Add the following script to the `package.json` file:
+
+```json
+"scripts": {
+  "dev": "ts-node-dev src/index.ts",
+}
+```
+
+Now you can run the `middleware` application by running the following command from the root directory. Go to the root directory and run the following command:
+
+```bash
+npm run dev
+```
+
+This will start both the Nuxt application and the `middleware` application.
+
+![Nuxt and Middleware Running](./images/nuxt-starter-3.webp)
+
+Let's start the app!
+
+Open your terminal and run the following command:
+
+```bash
+npm run dev
+```
+
+To test if the `middleware` application is running correctly, open http://localhost:8181/sapcc/getProducts or run the following command in your terminal:
+
+```bash
+curl http://localhost:8181/sapcc/getProducts
+```
+
+This will send a request to the `middleware` application and return a response from SAP Commerce Cloud.
+
+![SAP CC response](./images/nuxt-starter-4.webp)
+
+::info
+You can find complete implementation in the [`install-middleware` branch](https://github.com/vuestorefront-community/nuxt-starter/tree/install-middleware)
+::
+
+## Summary
+
+In this section, we have installed and configured the Alokai Middleware. We have installed all the necessary dependencies for the `middleware` application and configured it to work with SAP Commerce Cloud. We have also created a new configuration file and added all the necessary environment variables.
+
+In the next section, we will install and configure the Alokai SDK in the Nuxt application. 
+
+::card{title="Next: Install and Configure Alokai SDK" icon="tabler:number-3-small" }
+
+#description
+Let's install and configure the Alokai SDK in the Nuxt application and learn how to use the Alokai products.
+
+#cta
+:::docs-button{to="/guides/alokai-essentials/alokai-nuxt/install-sdk"}
+Next
+:::
+::