From d4db9d62ab14fc6b385cc0dac00fd8e764fb765e Mon Sep 17 00:00:00 2001 From: Stefan Hauke Date: Tue, 1 Nov 2022 14:30:59 +0100 Subject: [PATCH] docs: extend PurgeCSS integration documentation (#1313) * fix "check sentence newline" script to accept "i.e." and "e.g." as being not sentence ends --- docs/check-sentence-newline.js | 2 +- docs/concepts/styling-behavior.md | 5 ++++ docs/guides/customizations.md | 13 +++++++---- docs/guides/optimizations.md | 38 ++++++++++++++++++++++++++++++- 4 files changed, 52 insertions(+), 6 deletions(-) diff --git a/docs/check-sentence-newline.js b/docs/check-sentence-newline.js index 20d9b62e6f..110271a3bd 100644 --- a/docs/check-sentence-newline.js +++ b/docs/check-sentence-newline.js @@ -15,7 +15,7 @@ files.forEach(file => { if (/^(>|#|\||\s*-|\s*[0-9]+\.)/.test(line)) { return line; } else { - return line.replace(/((?!i\.e)\.) ([A-Z0-9])/g, '$1\n$2'); + return line.replace(/((? **Note:** You should @@ -164,6 +164,7 @@ The lookup starts with the file `style.scss` in the theme specific folder. > - not delete the standard theme folders to prevent merge conflicts when migrating the PWA (changes in standard files but deleted in your project). When styling is done on component level, all styling is encapsulated to exactly this component (default behavior). +On component level, theme-specific overrides for `.scss` files work as expected. You can re-use variables from the global styling on component level by importing only the styling file that defines the theme variables, e.g. @@ -173,10 +174,14 @@ You can re-use variables from the global styling on component level by importing > **Note:** Be aware that Visual Studio Code will not resolve all import references correctly but it works in the build PWA version anyways. +> **Note:** For bundled styles optimization PurgeCSS is used. Please read [the additional documentation](./optimizations.md#purgecss) regarding the usage and configuration of PurgeCSS in the Intershop PWA. + +### Static Assets + To add static assets (images, favicon, manifest file), create a theme specific folder in `src/assets/themes/` and adjust the theme specific references in the `*.scss` files accordingly. -The `index.html` does not support the theme specific overrides, see [Theme Specific Overrides](../guides/customizations.md#theme-specific-overrides). -Therefore, any theme specific references have to be changed directly in this file. +The `index.html` does not support theme specific overrides, see [Theme Specific Overrides](../guides/customizations.md#theme-specific-overrides). +For this file, any theme specific differences are handled via [theme.service.ts](../../src/app/core/utils/theme/theme.service.ts). ### Dependencies diff --git a/docs/guides/optimizations.md b/docs/guides/optimizations.md index 41cdd20924..5a02a56393 100644 --- a/docs/guides/optimizations.md +++ b/docs/guides/optimizations.md @@ -27,7 +27,43 @@ If the PWA is built using `production` configuration. (Either by building with ` - Webpack [SplitChunksPlugin](https://webpack.js.org/plugins/split-chunks-plugin/) is instructed to produce only `main`, `vendor`, `polyfills` and one `common` bundle for the code for optimized compression and download of the application. - All `data-testing` attributes are removed from the HTML templates to reduce output. - [PurgeCSS](https://purgecss.com) is used to remove unused CSS classes from the CSS output. - [Configuration](https://purgecss.com/configuration.html), especially [safelisting](https://purgecss.com/safelisting.html) certain classes, can be done on the plugin configuration or directly in your CSS with a special comment. + +## PurgeCSS + +> PurgeCSS is a tool to remove unused CSS. It can be part of your development workflow. When you are building a website, you might decide to use a CSS framework like TailwindCSS, Bootstrap, MaterializeCSS, Foundation, etc... But you will only use a small set of the framework, and a lot of unused CSS styles will be included. + +> This is where PurgeCSS comes into play. PurgeCSS analyzes your content and your CSS files. Then it matches the selectors used in your files with the one in your content files. It removes unused selectors from your CSS, resulting in smaller CSS files. + +While the described function for deleting unused CSS styles is very helpful, the mechanism for determining which styles are used is not without problems. +PurgeCSS can only analyze the strings in the actual source code of the project for used styles. + +So, styles that get added to the rendered HTML by third-party libraries (e.g. Bootstrap, Swiper) would not be found. +The same applies for styles used in server-loaded content (e.g. CMS, product descriptions). +Also style selectors that are dynamically generated would not be found. + +### Safelisting + +To solve this problem PurgeCSS provides different [options for safelisting](https://purgecss.com/safelisting.html) specific styles. +This can either be done in the plugin configuration or directly in your SCSS/CSS files with special comments. + +The PurgeCSS plugin configuration can be found in the project's [`webpack.custom.ts`](https://github.com/intershop/intershop-pwa/blob/3.1.0/templates/webpack/webpack.custom.ts#L231-L246). +This method is used and recommended to include required styles of the third-party libraries used, which would otherwise be purged. +For the different [configuration options](https://purgecss.com/configuration.html), refer to the PurgeCSS documentation. + +To protect styles defined in the Intershop PWA project source code, Intershop recommends safelisting them directly in your SCSS/CSS with [special comments](https://purgecss.com/safelisting.html#in-the-css-directly). +To include nested SCSS definitions, use `/* purgecss start ignore */` and `/* purgecss end ignore */`. + +### Development + +When using the standard way of developing the PWA with `ng s`, PurgeCSS is not activated and styling should work as expected. +This way missing styling issues because of PurgeCSS often first show up in deployed environments. +To test or develop with enabled PurgeCSS, the development server needs to be started with `ng s -c=b2b,production` (or your desired theme instead of `b2b`). + +In this startup process the following line can be read, indicating the usage of PurgeCSS similar to the deployed builds: + +``` +serve@b2b,production: setting up purgecss CSS minification +``` # Further References