chore: add new performance-oriented docs (vuestorefront#6636)

Author: filipsobol

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

@@ -174,7 +174,12 @@ module.exports = {
         title: 'Performance',
         collapsable: true,
         children: [
-          ['/performance/performance', 'Performance basics'],
+          ['/performance/intro', 'Introduction'],
+          ['/performance/improving-core-web-vitals', 'Improving Core Web Vitals'],
+          ['/performance/optimizing-html-and-css', 'Optimizing HTML and CSS'],
+          ['/performance/optimizing-images', 'Optimizing images'],
+          ['/performance/optimizing-javascript', 'Optimizing JavaScript'],
+          ['/performance/other-optimizations', 'Other optimizations'],
           ['/performance/ssr-cache', 'SSR cache']
         ]
       },

packages/core/docs/performance/improving-core-web-vitals.md

@@ -0,0 +1,101 @@
+# Improving Core Web Vitals
+
+Web Vitals are unified and simplified metrics created by Google to help site owners understand the quality of experience they are delivering to their users. Core Web Vitals are the subset of Web Vitals focused on three aspects of the user experience - loading (LCP), interactivity (FID), and visual stability (CLS).
+
+[Read more about Web Vitals](https://web.dev/vitals/).
+
+## Largest Contentful Paint (LCP) :orange_book:
+
+The Largest Contentful Paint (LCP) represents the time needed to display the biggest element visible to the user within the initial viewport. To improve the LCP metric, you need to start loading that element as fast as possible. If it needs an asset like JavaScript, CSS, image, or font, use the "preloading". It's a technique for telling a browser to download a resource before it discovers it's needed.
+
+For example, you might have a font that the browser can discover late (because it first needs to download and parse the CSS file), but you know that it's critical to your website. You can preload it, so once the browser parses the CSS and finds out that the font is needed, it will already have it downloaded.
+
+[Read more about preloading critical assets](https://web.dev/preload-critical-assets/).
+
+Below we describe two ways of preloading resources in Nuxt.js, depending on your needs.
+
+::: warning Be careful
+Preloading too many resources can have the opposite effect and impact the performance.
+
+Try to limit the number of resources preloaded to just those visible on the initial viewport. **If you prioritize everything, you don't prioritize anything**.
+:::
+
+### Preloading resource on every page
+
+If you want to preload a resource on every page, e.g., the font used across the whole website, use the `head` property in the `nuxt.config.js` file.
+
+:::tip
+If you are using Google Fonts, we recommend loading them using the [@nuxtjs/google-fonts](https://google-fonts.nuxtjs.org/) package. It offers reasonable defaults and performance-oriented options.
+:::
+
+```javascript
+// nuxt.config.js
+
+export default {
+  head: {
+    link: [
+      {
+        rel: 'preload',
+        as: 'style',
+        href: '.../stylesheet.css'
+      }
+    ]
+  }
+};
+```
+
+### Preloading resource on a specific page
+
+If you want to preload a resource on a specific page, e.g., a hero image used only on the homepage, use the `head` method in the Vue.js component.
+
+::: tip
+If you use the [@nuxt/image](https://image.nuxtjs.org/) package, you don't have to use the `head` method. Instead you can add ["preload" attribute](https://image.nuxtjs.org/components/nuxt-img#preload) to the `<nuxt-img>` component.
+:::
+
+```vue
+<script>
+export default {
+  head() {
+    return {
+      link: [
+        {
+          rel: 'preload',
+          as: 'image',
+          href: '...',
+        }
+      ]
+    }
+  }
+};
+</script>
+```
+
+### How to identify what is the Largest Contentful Paint
+
+The easiest way to learn which element is the Largest Contentful Paint is to use the Core Web Vital test on the [WebPageTest](https://www.webpagetest.org/webvitals) page. Enter the website URL, select one of the recommended locations and browsers, and click the `Start Test` button.
+
+Another option is to run Lighthouse in Chrome DevTools, described on [Google Developers](https://developers.google.com/web/tools/lighthouse#devtools) website.
+
+## Cumulative Layout Shift (CLS) :orange_book:
+
+Cumulate Layout Shift is an important user-centric metric for measuring visual stability, which shows if page had any unexpected movement.
+
+[Read more about CLS](https://web.dev/cls/)
+
+When the browser parses the HTML, it will reserve the space for images based on their `width` and `height` attributes. When they are not defined, the browser will not do that, and when the image is loaded, it will have to make space for it by moving all other content causing layout shift.
+
+### Always declare image width and height
+
+To prevent layout shifts, always use the image `width` and `height` attributes to let the browser know how much space it needs to save. Remember to do it for all images, including header logos.
+
+::: tip
+If you are using the [@nuxt/image](https://image.nuxtjs.org/) package, you can use the same attributes in the `<nuxt-img>` component.
+:::
+
+```html
+<img
+  src="..."
+  width="128"
+  height="128"
+  >
+```

packages/core/docs/performance/intro.md

@@ -0,0 +1,24 @@
+# Introduction to Web Performance
+
+Web performance is important subject in modern web. Google study over millions of page impressions found that when a site meets the recommended thresholds for the Core Web Vitals metrics, users are at least 24% less likely to abandon a page before it finishes loading. You can read more [on Chromium blog](https://blog.chromium.org/2020/05/the-science-behind-web-vitals.html).
+
+On the following pages you will find list of good practices that will help you optimize your website performance.
+
+## The indicators
+
+We marked some sections with the indicator below to show how impactful each problem can be:
+
+:orange_book: - Most important. When fixed, the usability of your website should noticeably improve.
+
+:ledger: - Nice to have. Fixing them could improve the performance.
+
+:blue_book: - Optional fixes, which might help in some cases.
+
+## Additional resources
+
+Other great resources that helped us in writing these suggestions:
+
+* [web.dev](https://web.dev/)
+* [sitesped.io](https://www.sitespeed.io/)
+* [Jakub Andrzejewski blog post](https://dev.to/theandrewsky/performance-checklist-for-vue-and-nuxt-cog)
+* [wpostats.com/](https://wpostats.com/)

packages/core/docs/performance/optimizing-html-and-css.md

@@ -0,0 +1,87 @@
+# Optimizing HTML and CSS
+
+Large render-blocking CSS files and extensive DOM can significantly impact page performance. Below we share some tips on how to prevent that.
+
+## Remove unused styles :ledger:
+
+Removing unused styles reduces the amount of data needed to be sent through the network and the rendering time because the browser has fewer styles to process.
+
+The `@vue-storefront/nuxt` package present in every Vue Storefront project has a `purgeCSS` option that does this exact thing.
+
+```javascript{6-13}
+// nuxt.config.js
+
+export default {
+  buildModules: [
+    ['@vue-storefront/nuxt', {
+      performance: {
+        purgeCSS: {
+          enabled: true,
+          paths: [
+            '**/*.vue'
+          ]
+        }
+      }
+    }]
+  ]
+};
+```
+
+`purgeCSS` option (_disabled by default_) uses [nuxt-purgecss](https://github.com/Developmint/nuxt-purgecss) plugin to remove unused CSS and accepts the same options, with two differences:
+
+* with `enabled: false`, the plugin will not be registered at all, not only be disabled
+
+* `**/*.vue` is added to `paths` array to detect all `.vue` files in your project, including those from `_theme` directory. Without this, the plugin would also remove some styles used on the page.
+
+If you decide to enable this plugin, we recommend using `enabled: process.env.NODE_ENV === 'production'`, to keep development mode as fast as possible.
+
+::: warning
+Because PurgeCSS looks for whole class names in files, it may remove styles for dynamic classes. If you're using a dynamic class, make sure you use whole names instead of concatinating variables (eg. `isDev ? 'some-style-dev' : 'some-style-prod'` instead of `some-style-${ isDev ? 'dev' : 'prod' }`. If this can't be avoided, add them to `whitelist` array.
+:::
+
+## Use HTTP2 Push :blue_book:
+
+HTTP2 Push is a performance technique to reduce latency by loading resources even before the browser knows it will need them.
+
+Consider a website with three resources:
+
+* index.html,
+* styles.css,
+* scripts.js.
+
+First, the browser will load and parse index.html. While parsing, it will find information about styles.css and script.js, sending a request to the server to get them. Because we know that the page needs those two files, we can use HTTP2 Push to send them to the client immediately without waiting for the client to request them.
+
+```javascript{6-8}
+// nuxt.config.js
+
+export default {
+  buildModules: [
+    ['@vue-storefront/nuxt', {
+      performance: {
+        httpPush: true
+      }
+    }]
+  ]
+};
+```
+
+The `httpPush` option (_enabled by default_) leverages [http2](https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-render#http2) option in Nuxt.js. It's configured to automatically push all JavaScript files needed for the current page. If you want to override this behavior, you can disable this option and use the Nuxt.js configuration instead.
+
+If you can't use HTTP2, you can disable this option. In this case, Nuxt.js will still `preload` these scripts, which is only slightly slower than the HTTP2 push.
+
+## Avoid extensive DOM size :ledger:
+
+Large DOM will increase memory usage, cause longer style calculations, and produce costly layout reflows. In your components, try to make as flat structure as possible and avoid nesting HTML elements. Check if the library you use doesn't create complex HTML structures. There are cases when a simple button generates 1000 lines of code.
+
+## Don't load print stylesheets :blue_book:
+
+Loading a specific stylesheet for printing slows down the page, even when not used. You can include the print styles inside your other CSS file(s) by using an `@media` query targeting type print.
+
+
+```css
+@import url("fineprint.css") print;
+```
+
+## Don't import SCSS files from StorefrontUI :ledger:
+
+`@vue-storefront/nuxt` module automatically detects if you have the `@storefront-ui/vue` package installed and, registers [@nuxtjs/style-resources](https://github.com/nuxt-community/style-resources-module) module. It automatically registers all variables, mixins, and functions from StorefrontUI, which means you don't have to import them. Importing SCSS files from StorefrontUI might duplicate some styles, significantly increasing your bundle size and impacting performance.

packages/core/docs/performance/optimizing-images.md

@@ -0,0 +1,74 @@
+# Optimizing images
+
+Images are likely the most straightforward resource to optimize. Yet if you forget to do it for at least one of them, your website might become a few megabytes heavier.
+
+On this page, we will share some tips on how you can prevent that.
+
+## Use the `@nuxt/image` package :orange_book:
+
+Using the [`<nuxt-img>`](https://image.nuxtjs.org/components/nuxt-img) component from the [@nuxt/image](https://image.nuxtjs.org/) package is likely the single best thing you can do to stop worrying about images. It offers features for most of the things mentioned in the following sections. Using most of them only requires you to pass a single attribute.
+
+It offers image resizing, converting formats, preloading, and integrations with the most popular image transformation services.
+
+```html
+<nuxt-img
+  src="/hero-image.png"
+  format="webp"
+  quality="80"
+  width="200"
+  height="100"
+  loading="lazy"
+/>
+```
+
+## Compress images using next-generation formats :orange_book:
+
+The most common performance bottlenecks are images that are not compressed and weigh multiple times more than they should. For this reason, you should always compress images, and luckily nowadays, there are plenty of lossless and lossy file types supported in modern browsers.
+
+If you have just a few static images on your website, you can manually compress them using a website like [Squoosh.app](https://squoosh.app/). However, if you have more images or want it to happen automatically, you can use the `@nuxt/image` package mentioned above.
+
+## Don't declare images in CSS :ledger:
+
+Images declared in the CSS files are often downloaded much later than those in HTML because the browser has to download and parse the CSS file before knowing that it has to load and display an image.
+
+If the image is also the biggest element visible to the user within the initial viewport, it will also negatively impact the [Largest Contentful Paint](/performance/improving-core-web-vitals.html#largest-contentful-paint-lcp) time.
+
+```diff
+- <style>
+- .hero {
+-   background-image: url("/hero-image.png")
+- }
+- </style>
+
++ <div class="hero">
++   <img src="/hero-image.png">
++ </div>
+```
+
+## Lazy load offscreen images :orange_book:
+
+Lazy loading is a technique used to prevent or delay the loading of non-critical resources until they are needed. You can use this mechanism for different types of resources, but in the case of images, our goal is to lazily load everything that is not visible to the user within the initial viewport. All other images can be loaded when the user scrolls down the page.
+
+Use the `loading="lazy"` attribute to load an image lazily. It also works for the `<nuxt-img>` component.
+
+```html
+<img src="..." loading="lazy">
+<nuxt-image src="..." loading="lazy" />
+```
+
+If you want to load resources other than images lazily, check out the [vue-lazyload](https://www.npmjs.com/package/vue-lazyload) package.
+
+## Scale images on the server, not browser :orange_book:
+
+Don't download big images to scale them down in the browser because it results in downloading data and processing that you could have avoided. Instead, use a tool or service that creates multiple versions of the same image server-side and serves the appropriate one depending on the size.
+
+Here's the example using the `<nuxt-img>` component that will handle this automatically.
+
+```html
+<nuxt-img
+  src="/hero-image.png"
+  width="300"
+  height="300"
+  sizes="sm:100vw md:50vw lg:400px"
+/>
+```