Merge branch 'docs/internals-documentation' into 'main'

docs: internals documentation and restructuring (SWF-162)

See merge request product/engineering/platform-group/pwa/frontends!234

.changeset/nervous-deers-leave.md

@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+added internals documentation, removed some pages, restructured home page and added icons directory

apps/docs/.vitepress/config.ts

@@ -32,15 +32,10 @@ export const sidebar = [
     text: "FRAMEWORK",
     items: [
       { text: "Requirements", link: "/framework/requirements" },
+      { text: "Internal Structure", link: "/framework/internal-structure" },
       { text: "Shopping Experiences", link: "/framework/shopping-experiences" },
       { text: "Styling", link: "/framework/styling" },
       { text: "Context Composables", link: "/framework/context-composables" },
-      {
-        text: "Asynchronous Components",
-        link: "/framework/asynchronous-components",
-      },
-      { text: "API Defaults", link: "/framework/api-defaults" },
-      { text: "Error Handling", link: "/framework/error-handling" },
     ],
   },
   {

apps/docs/src/framework/internal-structure.md

@@ -0,0 +1,93 @@
+---
+head:
+  - - meta
+    - name: og:title
+      content: Shopware Frontends Internal Structure
+  - - meta
+    - name: og:description
+      content: "Details about the internal structure of Shopware Frontends"
+  - - meta
+    - name: og:image
+      content: "https://frontends-og-image.vercel.app/Internal%20Structure?fontSize=150px"
+---
+
+# Internal Structure
+
+The internal structure of Shopware Frontends is designed to provide flexibility, reusability and abstraction. Shopware Frontends is a framework that is build with JavaScript and TypeScript.
+
+Some of its components are based on Vue.js and Nuxt.js. The framework is designed to be used mostly with Vue.js and Nuxt.js, but it is not limited to these technologies. You can use it with any other JavaScript framework or library.
+
+This section deals with the different packages and their abstractions. It is sorted by reusability / abstraction level from high to low and shows the main dependencies of each component respectively.
+
+<PageRef title="shopware/frontends packages" sub="Explore all Shopware Frontends packages on GitHub" icon="../.assets/framework-icons/github.png" page="https://github.com/shopware/frontends/tree/main/packages" target="_blank" />
+
+## api-client
+
+<div class="flex mt--4 mb-4 gap-2">
+    <img src="../.assets/framework-icons/typescript.png" alt="This package depends on Typescript" title="This package depends on Typescript" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+</div>
+
+The API client provides a common interface to access the Shopware API. It can be used standalone in any JavaScript project.
+
+## types
+
+<div class="flex mt--4 mb-4 gap-2">
+    <img src="../.assets/framework-icons/typescript.png" alt="This package depends on Typescript" title="This package depends on Typescript" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+</div>
+
+The types package contains TypeScript types for all Shopware objects and API endpoints.
+
+## helpers
+
+<div class="flex mt--4 mb-4 gap-2">
+    <img src="../.assets/framework-icons/typescript.png" alt="This package depends on Typescript" title="This package depends on Typescript" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+</div>
+
+Helpers are functions that can be used for formatting, data manipulation and other stateless tasks within any JavaScript project. They are not tied to any other components.
+
+## composables
+
+<div class="flex mt--4 mb-4 gap-2">
+    <img src="../.assets/framework-icons/typescript.png" alt="This package depends on Typescript" title="This package depends on Typescript" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+    <img src="../.assets/framework-icons/vue.png" alt="This package depends on Vue.js 3" title="This package depends on Vue.js 3" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+</div>
+
+The composables are a set of Vue.js composition functions that can be used in any Vue.js project. They provide state management, UI logic and data fetching and are the base for all guides in our [building section](../getting-started/navigation.md).
+
+## vue3-plugin
+
+<div class="flex mt--4 mb-4 gap-2">
+    <img src="../.assets/framework-icons/typescript.png" alt="This package depends on Typescript" title="This package depends on Typescript" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+    <img src="../.assets/framework-icons/vue.png" alt="This package depends on Vue.js 3" title="This package depends on Vue.js 3" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+</div>
+
+The Vue 3 plugin allows you to set up a Vue 3 project with Shopware Frontends. It provides the [composables](#composables) and [api-client](#api-client) packages.
+
+## nuxt3-module
+
+<div class="flex mt--4 mb-4 gap-2">
+    <img src="../.assets/framework-icons/typescript.png" alt="This package depends on Typescript" title="This package depends on Typescript" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+    <img src="../.assets/framework-icons/vue.png" alt="This package depends on Vue.js 3" title="This package depends on Vue.js 3" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+    <img src="../.assets/framework-icons/nuxt.png" alt="This package depends on Nuxt 3" title="This package depends on Nuxt 3" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+</div>
+
+The Nuxt 3 module allows you to set up a Nuxt 3 project with Shopware Frontends. It provides the [composables](#composables) and [api-client](#api-client) packages.
+
+If you want to use these packages with a different Vue.js framework, see the guide for using Shopware Frontends in a [custom project](../getting-started/templates/custom-project.md) or use the [vue3-plugin](#vue3-plugin).
+
+## cms-base
+
+<div class="flex mt--4 mb-4 gap-2">
+    <img src="../.assets/framework-icons/typescript.png" alt="This package depends on Typescript" title="This package depends on Typescript" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+    <img src="../.assets/framework-icons/vue.png" alt="This package depends on Vue.js 3" title="This package depends on Vue.js 3" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+    <img src="../.assets/framework-icons/nuxt.png" alt="This package depends on Nuxt 3" title="This package depends on Nuxt 3" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+    <img src="../.assets/framework-icons/tailwind.png" alt="This package depends on UnoCSS / Tailwind.css" title="This package depends on UnoCSS / Tailwind.css" class="w-8 aspect-square hover:scale-125 transition hover:drop-shadow-md" />
+</div>
+
+The CMS base is a Nuxt module that provides an implementation of all CMS components in Shopware [based on utility-classes](./styling.md) using unocss/Tailwind.css syntax. It is useful for projects that want to use the CMS components but design their own layout.
+
+Head to our [Content Pages](../getting-started/content-pages.md#use-the-cms-base-package) guide to learn more.
+
+## Templates & Examples
+
+Our GitHub repository also contains reference implementations for different frameworks and use cases. You can find them in the [templates](https://github.com/shopware/frontends/tree/main/templates) and [examples](https://github.com/shopware/frontends/tree/main/examples) folders. These examples are not directly part of the framework, but can be useful for learning how to use Shopware Frontends.

apps/docs/src/framework/requirements.md

@@ -1,9 +1,44 @@
+---
+head:
+  - - meta
+    - name: og:title
+      content: Shopware Frontends Requirements
+  - - meta
+    - name: og:description
+      content: "Which Node.js version, package manager, IDE and extensions should you use to get started with Shopware Frontends?"
+  - - meta
+    - name: og:image
+      content: "https://frontends-og-image.vercel.app/Requirements?fontSize=150px"
+---
+
 # Environment requirements
 
-[[toc]]
+Shopware Frontends requires a Node.js runtime environment. Besides that, for development you can use your favourite package manager.
+
+## Shopware API
+
+Shopware Frontends does not differ between provisioning of the Shopware API. Both, cloud and self-managed Shopware 6 instances are supported.
+
+Every development instance / setup template is pre-configured with a public demo API. That way you don't have to set up a Shopware instance yourself.
+
+<PageRef title="Install Shopware 6" sub="Set up Shopware 6 for development" page="https://developer.shopware.com/docs/guides/installation/overview" target="_blank" />
+
+## IDE
+
+For an ideal development experience, we recommend using [VSCode](https://code.visualstudio.com/download) with the following extensions
+
+- Vue Language Features (`Vue.volar`)
+- Prettier - Code Formatter (`esbenp.prettier-vscode`)
+- TS and JS Language Features (`vscode.typescript-language-features`)
+
+If you are using the `demo-store-template`, we also recommend the following extension
+
+- UnoCSS (`antfu.unocss`)
 
 ## Node.js
 
+Shopware Frontends requires a Node.js runtime environment.
+
 Supported versions:
 
 - **v16.x** LTS
@@ -12,7 +47,7 @@ Supported versions:
 :::tip
 Use [Node Version Manager](https://github.com/nvm-sh/nvm) to manage a Node.js version locally.
 
-_Supported_ signifies the framework is developed, run, and tested on mentioned versions.
+"Supported" signifies the framework is developed, run, and tested on mentioned versions.
 :::
 
 ## Package manager
@@ -26,29 +61,3 @@ Supported managers:
 :::info
 `npm` package manager is available out of the box with Node.js installed. Other managers need manual installation.
 :::
-
-## Examples
-
-### Installation
-
-```bash
-pnpm i
-# or
-npm install
-# or
-yarn
-```
-
-### Run dev server
-
-```bash
-pnpm dev
-# or
-npm run dev
-# or
-yarn dev
-```
-
-:::info
-Other available commands (like `build`) are available in `scripts` section of `package.json` file.
-:::

apps/docs/src/getting-started/templates/blank-template.md

@@ -6,7 +6,7 @@ The blank template contains no UI or markup - it's just a blank Nuxt3 applicatio
 
 ## Setup & run
 
-<PageRef target="blank" title="Run on Stackblitz" page="https://stackblitz.com/github/shopware/frontends/tree/main/templates/vue-blank" sub="Open the Blank Template with our browser IDE in a new window" icon="https://blog.stackblitz.com/img/favicon.png?hash=3817f5a9d1"/>
+<PageRef target="blank" title="Run on Stackblitz" page="https://stackblitz.com/github/shopware/frontends/tree/main/templates/vue-blank" sub="Open the Blank Template with our browser IDE in a new window" icon="../../.assets/framework-icons/stackblitz.png"/>
 
 Alternatively, set up the blank template manually by running the following commands in a new directory:
 

apps/docs/src/getting-started/templates/demo-store-template.md

@@ -10,7 +10,7 @@ The **Demo Store Template** is not suitable for production stores. It is under c
 
 ## Setup & run
 
-<PageRef target="blank" title="Run on Stackblitz" page="https://stackblitz.com/github/shopware/frontends/tree/main/templates/vue-demo-store" sub="Open the Demo Store Template with our browser IDE in a new window" icon="https://blog.stackblitz.com/img/favicon.png?hash=3817f5a9d1"/>
+<PageRef target="blank" title="Run on Stackblitz" page="https://stackblitz.com/github/shopware/frontends/tree/main/templates/vue-demo-store" sub="Open the Demo Store Template with our browser IDE in a new window" icon="../../.assets/framework-icons/stackblitz.png"/>
 
 Alternatively, set up the blank template manually by running the following commands in a new directory:
 

apps/docs/src/index.md

@@ -6,9 +6,13 @@
     <img src=".assets/shopware-frontends-logo-dark.png" class="hidden dark:block">
 </div>
 
+<div class="text-center">
+
 Shopware Frontends is Shopware's Vue.js <strong>framework</strong> for building custom storefronts.
 
-<PageRef title="Why Shopware Frontends?" sub="Which problems does it solve" page="/why-shopware-frontends" />
+<PageRef title="Get Started 🚀" sub="Start building your first Shopware Frontends project" page="../getting-started/templates" />
+
+</div>
 
 ## How it works
 
@@ -26,7 +30,7 @@ A big part (and a risk factor) of every custom storefront project is the impleme
 
 - Routing
 - Shopping worlds (Shopware CMS) integration
-- Translation handling
+- Product searches and filters
 - Price formatting
 - Authentication & state handling
 
@@ -36,6 +40,4 @@ It also comes with TypeScript support.
 
 You can decide to start from scratch and use no template at all, but we recommend looking at our [Templates](./getting-started/templates.md) which are based on **Nuxt.js** and **Tailwind CSS**.
 
----
-
-<PageRef page="../getting-started/templates" title="Getting Started" sub="Get started with Shopware Frontends" />
+<PageRef title="Internal Structure" sub="Details about the internal structure of Shopware Frontends" page="/framework/internal-structure" />