diff --git a/.changeset/nervous-deers-leave.md b/.changeset/nervous-deers-leave.md new file mode 100644 index 000000000..08b3facbc --- /dev/null +++ b/.changeset/nervous-deers-leave.md @@ -0,0 +1,5 @@ +--- +"docs": patch +--- + +added internals documentation, removed some pages, restructured home page and added icons directory diff --git a/apps/docs/.vitepress/config.ts b/apps/docs/.vitepress/config.ts index 8d1e37182..176ca8614 100644 --- a/apps/docs/.vitepress/config.ts +++ b/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" }, ], }, { diff --git a/apps/docs/src/.assets/framework-icons/github-white.png b/apps/docs/src/.assets/framework-icons/github-white.png new file mode 100644 index 000000000..75de79955 Binary files /dev/null and b/apps/docs/src/.assets/framework-icons/github-white.png differ diff --git a/apps/docs/src/.assets/framework-icons/github.png b/apps/docs/src/.assets/framework-icons/github.png new file mode 100644 index 000000000..936dd5fe4 Binary files /dev/null and b/apps/docs/src/.assets/framework-icons/github.png differ diff --git a/apps/docs/src/.assets/framework-icons/nuxt.png b/apps/docs/src/.assets/framework-icons/nuxt.png new file mode 100644 index 000000000..79187fcde Binary files /dev/null and b/apps/docs/src/.assets/framework-icons/nuxt.png differ diff --git a/apps/docs/src/.assets/framework-icons/stackblitz.png b/apps/docs/src/.assets/framework-icons/stackblitz.png new file mode 100644 index 000000000..3abe2b715 Binary files /dev/null and b/apps/docs/src/.assets/framework-icons/stackblitz.png differ diff --git a/apps/docs/src/.assets/framework-icons/tailwind.png b/apps/docs/src/.assets/framework-icons/tailwind.png new file mode 100644 index 000000000..1014c8478 Binary files /dev/null and b/apps/docs/src/.assets/framework-icons/tailwind.png differ diff --git a/apps/docs/src/.assets/framework-icons/typescript.png b/apps/docs/src/.assets/framework-icons/typescript.png new file mode 100644 index 000000000..380a34be3 Binary files /dev/null and b/apps/docs/src/.assets/framework-icons/typescript.png differ diff --git a/apps/docs/src/.assets/framework-icons/vue.png b/apps/docs/src/.assets/framework-icons/vue.png new file mode 100644 index 000000000..400e27b66 Binary files /dev/null and b/apps/docs/src/.assets/framework-icons/vue.png differ diff --git a/apps/docs/src/framework/api-defaults.md b/apps/docs/src/framework/api-defaults.md deleted file mode 100644 index 17d50afc7..000000000 --- a/apps/docs/src/framework/api-defaults.md +++ /dev/null @@ -1,9 +0,0 @@ -# API Defaults - -::: warning Work in progress -This page is currently work in progress and will be updated soon. -::: - -API defaults are used to define default values that are passed to the API "per composable". - -When fetching products, it is likely that you always want to fetch the same data or "pre-filter" using the same parameters. To prevent repeating yourself all the time, you can use the API defaults configuration. diff --git a/apps/docs/src/framework/asynchronous-components.md b/apps/docs/src/framework/asynchronous-components.md deleted file mode 100644 index b9b209513..000000000 --- a/apps/docs/src/framework/asynchronous-components.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -head: - - - meta - - name: og:title - content: Asynchronous Components - - - meta - - name: og:description - content: "How to deal with asynchronicity in components" - - - meta - - name: og:image - content: "https://frontends-og-image.vercel.app/**Async**%20Components?fontSize=150px" ---- - -# Asynchronous Components - -::: warning Work in progress -This page is currently work in progress and will be updated soon. -::: - -In order to fetch components or data asynchronously and display placeholders while the content is loading, we recommend using Vue 3's `Suspense` component - -```vue-html - - - - - - - -``` diff --git a/apps/docs/src/framework/error-handling.md b/apps/docs/src/framework/error-handling.md deleted file mode 100644 index b98964d97..000000000 --- a/apps/docs/src/framework/error-handling.md +++ /dev/null @@ -1,5 +0,0 @@ -# Error Handling - -::: warning Work in progress -This page is currently work in progress and will be updated soon. -::: diff --git a/apps/docs/src/framework/internal-structure.md b/apps/docs/src/framework/internal-structure.md new file mode 100644 index 000000000..3f4e035bb --- /dev/null +++ b/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. + + + +## api-client + +
+ This package depends on Typescript +
+ +The API client provides a common interface to access the Shopware API. It can be used standalone in any JavaScript project. + +## types + +
+ This package depends on Typescript +
+ +The types package contains TypeScript types for all Shopware objects and API endpoints. + +## helpers + +
+ This package depends on Typescript +
+ +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 + +
+ This package depends on Typescript + This package depends on Vue.js 3 +
+ +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 + +
+ This package depends on Typescript + This package depends on Vue.js 3 +
+ +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 + +
+ This package depends on Typescript + This package depends on Vue.js 3 + This package depends on Nuxt 3 +
+ +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 + +
+ This package depends on Typescript + This package depends on Vue.js 3 + This package depends on Nuxt 3 + This package depends on UnoCSS / Tailwind.css +
+ +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. diff --git a/apps/docs/src/framework/requirements.md b/apps/docs/src/framework/requirements.md index 9d72e27b3..c550c7535 100644 --- a/apps/docs/src/framework/requirements.md +++ b/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. + + + +## 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. -::: diff --git a/apps/docs/src/getting-started/templates/blank-template.md b/apps/docs/src/getting-started/templates/blank-template.md index f00e140f8..53cd87029 100644 --- a/apps/docs/src/getting-started/templates/blank-template.md +++ b/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 - + Alternatively, set up the blank template manually by running the following commands in a new directory: diff --git a/apps/docs/src/getting-started/templates/demo-store-template.md b/apps/docs/src/getting-started/templates/demo-store-template.md index 6b6a513cc..e704c5006 100644 --- a/apps/docs/src/getting-started/templates/demo-store-template.md +++ b/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 - + Alternatively, set up the blank template manually by running the following commands in a new directory: diff --git a/apps/docs/src/index.md b/apps/docs/src/index.md index 9ff396d7f..c04625fad 100644 --- a/apps/docs/src/index.md +++ b/apps/docs/src/index.md @@ -6,9 +6,13 @@ +
+ Shopware Frontends is Shopware's Vue.js framework for building custom storefronts. - + + +
## 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**. ---- - - +