docs: update the Theme document (vuestorefront#6608)

Author: filipsobol

packages/core/docs/.vuepress/config.js

@@ -165,7 +165,7 @@ module.exports = {
         children: [
           ['/integrate/extending-vue-storefront', 'Extending Vue Storefront'],
           ['/integrate/extending-integrations', 'Extending integrations'],
-          ['/integrate/integration-guide', 'Integrating eCommerce platform'],
+          ['/integrate/integration-guide', 'Integrating e-commerce platform'],
           ['/integrate/cms', 'Integrating CMS platform'],
           ['/integrate/cache-driver', 'Integrating cache driver']
         ]

packages/core/docs/getting-started/layouts-and-routing.md

@@ -113,6 +113,41 @@ export default {
 };
 ```
 
+## Changing base path
+
+There are cases when your store is served under a specific path, eg. `example.com/shop/`. To make Vue.js router aware of this, you need to update the configuration in the `nuxt.config.js`:
+
+```javascript
+// nuxt.config.js
+
+export default {
+  router: {
+    base: "/shop/"
+  }
+};
+```
+
+Unfortunately not all links in your application will detect this. You can fix it, by wrap all relative links and paths to assets in `addBasePath` helper.
+
+```vue
+<template>
+  <SfImage :src="addBasePath('/imageA.webp')" />
+  <SfBanner :image="addBasePath('/bannerB.png')" />
+</template>
+
+<script>
+import { addBasePath } from '@vue-storefront/core';
+
+export default {
+  setup() {
+    return {
+      addBasePath
+    };
+  }
+};
+</script>
+```
+
 ## Navigating between pages
 
 To navigate between pages within your application, use the [NuxtLink](https://nuxtjs.org/docs/features/nuxt-components/#the-nuxtlink-component) component, instead of the traditional `<a>` tag. While you can use the `<a>` tag for external links, using the `<NuxtLink />` for internal links will ensure that you make use of the Single-Page Navigation capabilities that Nuxt.js provides.

packages/core/docs/getting-started/theme.md

@@ -1,132 +1,105 @@
 # Theme
 
-## Storefront UI
+A project without any theme would just show a blank page, but if you have seen any of Vue Storefront demos or created a project using our CLI, you know that's not the case. So what makes it look like it does?
 
-<center>
-<img src="../images/theme/storefront-ui.jpg" />
-</center>
+This page will describe what makes the default theme, how to customize it, and what tricks we use to improve the performance.
 
-Almost every component in our default theme uses components whose names start with `Sf`. These come from [Storefront UI](http://storefrontui.io/) - a design system and library of Vue.js components dedicated to e-commerce, maintained by the Vue Storefront core team. It comes with [Storybook](https://storybook.storefrontui.io/) to help you customize and test the components.
+## What's makes a default theme
 
-The library is fully customizable. It can be used in different contexts and with different designs.
-It's excellent for the multi-tenancy model as a shared UI library that can be customized differently for each tenant.
+Although, at first glance, it might look like all of our e-commerce integrations use the same exact theme, it's not the case. All of them are built upon the same base theme and modify it to work well and cover features of a given platform. This means that some integrations might have more pages, different UI elements, or additional Nuxt.js modules or plugins.
 
-To learn more about Storefront UI, please check its [Documentation](https://docs.storefrontui.io/).
+For this reason, in this section, we will focus only on the common parts of all themes.
 
-::: tip Want to use another UI library? No problem!
-If you don't want to use Storefront UI, feel free to remove it from your project. It's just a UI layer, and the project can work with any other UI library or a custom code.
-:::
+### Preinstalled modules and libraries
 
-## Customizing the theme
+Every new Vue Storefront project comes with a set of preinstalled Nuxt.js modules and plugins, as well as Vue.js libraries. These packages offer a variety of features from cookie handling to form validation and are used by the base theme. You can remove some of them, but only if you decide to create a custom theme from scratch.
 
-### Changing existing pages, components, and layouts
+#### Nuxt.js modules and plugins
 
-To update the existing components, you need to identify them first. Vue.js Devtools helps us in that. Open the tool and click on the `Select` button above the component tree, then click on the DOM element you want to update. One of the components in the tree should get highlighted. You can look for the component with the same name in the `layout`, `pages`, or `components` directories and update it to your needs. However, there are few exceptions to this rule.
+- [`@nuxt/typescript-build`](https://typescript.nuxtjs.org/) - for TypeScript support,
+- [`@nuxtjs/pwa`](https://pwa.nuxtjs.org/) - for PWA functionalities,
+- [`@nuxtjs/composition-api`](https://composition-api.nuxtjs.org/) - for Composition API support,
+- [`@nuxtjs/style-resources`](https://www.npmjs.com/package/@nuxtjs/style-resources) - for importing SASS variables globally,
+- [`nuxt-i18n`](https://i18n-legacy.nuxtjs.org/) - for internationalization (translations and price formatting),
+- [`nuxt-purgecss`](https://purgecss.com/guides/nuxt.html) - for removing unused CSS from the final build,
+- [`cookie-universal-nuxt`](https://www.npmjs.com/package/cookie-universal-nuxt) - for handling cookies on the server (SSR) and client (browser).
 
-#### `Sf` components
+#### Vue.js libraries
 
-If the name of the component starts with `Sf` (indicating that it comes from Storefront UI), you should refer to the direct **parent** component. The behavior and look of such components can be changed by passing different properties and using slots. Refer to the StorefrontUI documentation linked above for more information.
+- [`vee-validate`](https://vee-validate.logaretm.com/v3) - for frontend form validation,
+- [`vue-scrollto/nuxt`](https://www.npmjs.com/package/vue-scrollto) - for smooth scrolling to HTML elements,
+- [`vue-lazy-hydration`](https://www.npmjs.com/package/vue-lazy-hydration) - for delaying hydration and improving performance.
 
-#### `LazyHydrate` and `Anonymous Component` components
+### Storefront UI
 
-These two components come from the `vue-lazy-hydration` library and are wrappers around other components. In Vue Storefront, they are used to improve the performance by deferring the hydration process (when components become interactive) and don't affect the look of other components.
+<figure style="text-align: center">
+  <img
+    src="../images/storefront-ui.webp"
+    alt="StorefrontUI logo and default theme"
+  />
+  <figcaption style="font-size: 0.9rem">(Click to zoom)</figcaption>
+</figure>
 
-If you encounter one of these components, you should refer to the direct **child** component.
+Almost every page in our default theme uses components whose names start with `Sf`. These come from the [Storefront UI](http://storefrontui.io/) — a design system and library of Vue.js components dedicated to e-commerce, maintained by the Vue Storefront team. Every component can be heavily customized using [props](https://vuejs.org/v2/guide/components-props.html) and [slots](https://vuejs.org/v2/guide/components-slots.html).
 
-### Router base property
+Please check [Storefront UI documentation](https://docs.storefrontui.io/) to learn more and interactively customize and test the components.
 
-There is an option to set base URL for your store.
+::: tip Want to use another UI library? No problem!
+If you don't want to use Storefront UI, feel free to remove it from your project. It's just a UI layer, and the project can work with any other UI library or a custom code.
+:::
 
-This can be useful if you need to serve your store as a different context root, from within a bigger Web site.
+## How to customize the theme
 
-Add following configuration to `nuxt.config.js`
-```javascript
-// nuxt.config.js
+Every default theme will need customization at some point. Regardless of how complex the changes are, we recommend reusing as much from the default theme as possible. This will not only save you time but will likely reduce the number of bugs, thanks to the time we spend on stabilization and testing.
 
-export default {
-  router: {
-    base: "/myShop/"
-  }
-};
-```
+### Updating layouts, pages, and components
 
-:::warning Be careful
-When using base router property you need to wrap all assets relative links in addBasePath(), this will automatically add base path to them and prevent redirects. (example below)
-:::
+To update the existing component, you need to identify it first, and Vue.js Devtools is invaluable in this. Open the Vue.js Devtools, right-click the DOM element you want to update, and select `Inspect Vue component`. One of the components in the tree in Vue.js Devtools should get highlighted. You can look for the component with the same name in the `layout`, `pages`, or `components` directories and update it to your needs. However, there are a few exceptions to this rule described below.
 
+#### `Sf` components
 
+If the component's name starts with `Sf`, it means that it comes from [StorefrontUI](https://storefrontui.io/) library. The look and behavior of such components are controlled using props and slots passed from the direct **parent** component.
 
-```javascript
-//use addBasePath on relative url
-<SfImage :src="addBasePath(`/homepage/imageA.webp`)" />
-<SfBanner :image="addBasePath('/homepage/bannerA.png')" />
-
-//In theme file import addBasePath from vue-storefront core
-import { addBasePath } from '@vue-storefront/core';
-
-setup() {
-  return {
-    // if you want to use it in template you need to exprt it
-    addBasePath
-  }
-}
-```
+#### `LazyHydrate` and `Anonymous Component` components
 
-## Updating styles
+These two components come from the [vue-lazy-hydration](https://github.com/maoberlehner/vue-lazy-hydration) library and are wrappers around other components. They are used to improve the performance by deferring the hydration process (making components interactive) and don't affect the look of other components. The behavior of such components is controlled using props passed from the direct **parent** component.
 
-There are few ways of updating the default styles. Below we describe the most optimal ways for the most common cases.
+### Updating styles
 
-### Adding global styleheet
+There are a few ways of updating the default styles. Below we describe the most optimal methods for the most common cases.
+
+#### Adding global styleheet
 
 To add global styles applied to all pages, use the [css property](https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-css/) in `nuxt.config.js`.
 
-### Adding stylesheet to specific layout, page, or component
+#### Adding stylesheet to specific layout, page, or component
 
-To add a stylesheet to a specific component, use `@import` regardless if you are using CSS, SCSS, or LESS.
+To add a stylesheet to a specific component, use `@import` regardless of whether you are using CSS, SCSS, or LESS.
 
 ```vue
 <style>
 @import "@/assets/stylesheet.css";
 </style>
 ```
 
-### Using variables, mixins, and function in components
+#### Using variables, mixins, and function in components
 
-Usually, to access style variables, mixins, and functions, we have to import them in every component separately. Thanks to [@nuxtjs/style-resources](https://github.com/nuxt-community/style-resources-module#readme) module, we can register them in `nuxt.config.js` and access them without extra `@import` statements.
+Usually, to access style variables, mixins, and functions, we import them in every component separately. Thanks to the [@nuxtjs/style-resources](https://github.com/nuxt-community/style-resources-module#readme) module, we can register them in `nuxt.config.js` and access them without extra `@import` statements.
 
 :::danger Be careful
-Stylesheets in `styleResources` should **only** contain variables, mixins, and functions. During the build process, the components import these stylesheets. Any styles declared in them are added to every component, which can significantly hurt the performance and application size.
+Stylesheets in `styleResources` should **only** contain variables, mixins, and functions. During the build process, the components import these stylesheets. Any **styles** declared in them are added to every component, significantly impacting the performance and application size.
 :::
 
 We use this approach to have access to StorefrontUI helpers in all components:
 
-```js
+```javascript
 // nuxt.config.js
+
 export default {
   styleResources: {
-    scss: [require.resolve('@storefront-ui/shared/styles/_helpers.scss', { paths: [process.cwd()] })]
+    scss: [
+      require.resolve('@storefront-ui/shared/styles/_helpers.scss', { paths: [process.cwd()] })
+    ]
   },
 };
 ```
-
-## Preinstalled modules and libraries
-
-Below you can find a list of the most important Nuxt Modules and libraries that come preinstalled with the default theme:
-
-### Nuxt.js modules
-
-- `@nuxtjs/pwa`;
-- `nuxt-i18n`;
-- `@vue-storefront/nuxt`;
-  - `@nuxtjs/composition-api`;
-  - `@nuxt/typescript-build`;
-  - `@nuxtjs/style-resources`;
-  - `nuxt-purgecss`;
-- `@vue-storefront/nuxt-theme`;
-  - `vue-lazy-hydration`;
-
-### Libraries
-
-- [`@storefront-ui/vue`](https://storefrontui.io);
-- [`vee-validate`](https://vee-validate.logaretm.com/v3);
-- [`lodash`](https://lodash.com/);

packages/core/docs/images/storefront-ui.webp

@@ -1,4 +1,4 @@
-# Integrating eCommerce platform
+# Integrating e-commerce platform
 
 :::danger Don't forget to reload the application
 The application does not reload automatically after saving the changes in Server Middleware. Due to this, you have to restart the application manually. We are working on enabling Hot Reloading in future updates.
@@ -10,7 +10,7 @@ If you want to integrate with Vue Storefront, don't hesitate to get in touch wit
 
 ## Introduction
 
-Integrating an eCommerce platform with Vue Storefront sounds scary. Luckily, many of our partners and community members with different seniority levels have successfully done it. We are sure that even without prior experience with Vue Storefront, you can too.
+Integrating an e-commerce platform with Vue Storefront sounds scary. Luckily, many of our partners and community members with different seniority levels have successfully done it. We are sure that even without prior experience with Vue Storefront, you can too.
 
 This document will guide you through the process of creating integration and explain the concepts behind Vue Storefront.
 
@@ -25,7 +25,7 @@ Before we get started, make sure that:
 
 ## Project structure
 
-To make it easy to get started, we created an [eCommerce integration boilerplate](https://github.com/vuestorefront/ecommerce-integration-boilerplate).
+To make it easy to get started, we created an [e-commerce integration boilerplate](https://github.com/vuestorefront/ecommerce-integration-boilerplate).
 
 It's a monorepo, which is a single repository containing multiple related projects. Each directory inside `packages` contains one project. There are three projects:
 
@@ -35,7 +35,7 @@ It's a monorepo, which is a single repository containing multiple related projec
 
 ### API client
 
-`api-client` is the **_server layer_** that extends our [Server Middleware](../architecture/server-middleware.html). It creates an API client (like `Apollo` for GraphQL or `Axios` for plain HTTP) that communicates with your eCommerce platform. It acts as a proxy between the users and the platform.
+`api-client` is the **_server layer_** that extends our [Server Middleware](../architecture/server-middleware.html). It creates an API client (like `Apollo` for GraphQL or `Axios` for plain HTTP) that communicates with your e-commerce platform. It acts as a proxy between the users and the platform.
 
 Here, you will create new endpoints that accept parameters sent from the frontend and use them to fetch or submit data to the platform.
 
@@ -78,7 +78,7 @@ API of your platform should have endpoints for most of these operations unless s
 
 ### Fork boilerplate repository
 
-Now that we explained the basics, let's start creating an integration. Open the [eCommerce integration boilerplate repository](https://github.com/vuestorefront/ecommerce-integration-boilerplate) and click the `Use this template` button. This creates a copy of a repository and allows you to make changes without affecting the original project. Enter the name of the new repository and click `Create repository from template`.
+Now that we explained the basics, let's start creating an integration. Open the [e-commerce integration boilerplate repository](https://github.com/vuestorefront/ecommerce-integration-boilerplate) and click the `Use this template` button. This creates a copy of a repository and allows you to make changes without affecting the original project. Enter the name of the new repository and click `Create repository from template`.
 
 Once the new repository is ready, clone it locally.
 
@@ -106,7 +106,7 @@ Since we are mocking all functionalities in the boilerplate, different parts of
 
 ## Connect to the platform
 
-Let's start by creating an API client that will communicate with the eCommerce platform. As mentioned above, the `api-client` does precisely that, so this is the project to update.
+Let's start by creating an API client that will communicate with the e-commerce platform. As mentioned above, the `api-client` does precisely that, so this is the project to update.
 
 ### Structure of the `api-client` project
 
@@ -117,7 +117,7 @@ You will see only two files and one empty directory when you open the `packages/
 
 ### Add API client
 
-API client is a library that handles sending requests to the eCommerce platform and parsing its responses.
+API client is a library that handles sending requests to the e-commerce platform and parsing its responses.
 
 :::warning
 Examples below use `axios` to handle HTTP requests. However, you can use other libraries if your platform uses GraphQL or has dedicated clients.
@@ -164,7 +164,7 @@ module.exports = {
       location: '@sloth/api/server', // name of your api-client package followed by `/server`
       configuration: {
         api: {
-          url: '' // URL of your eCommerce platform
+          url: '' // URL of your e-commerce platform
         }
       }
     }
@@ -246,7 +246,7 @@ As mentioned in [Project structure](#project-structure) section, `api-client` is
 While this might be true for simple scenarios, it doesn't scale well. Some of the benefits of using such proxy are:
 
 - **Caching** - selected responses can be cached to improve the performance significantly. While it's possible to do caching in the browser, each customer would have to make at least one request to a given endpoint.
-- **Lower cost** - when responses are cached, fewer requests are sent to the eCommerce platform. Depending on the provider, it might reduce the cost.
+- **Lower cost** - when responses are cached, fewer requests are sent to the e-commerce platform. Depending on the provider, it might reduce the cost.
 - **Smaller bundle** - with all the clients installed and configured on the server, the final bundle sent to the browsers can be much smaller. This is especially true for APIs based on GraphQL.
 - **Security** - API configuration, secrets, and keys are stored on the server and are not sent to the browser.