Styleguide Upgrade Guide

Step 1: Check that your theme(s) is/are flattened

In older projects, there is a possibility that the theme has not been “flattened.” Flattening is the process in which we remove multi-inheritance from .hbs files, essentially disconnecting the themes from one another.

To determine if your theme is flattened, navigate to your theme’s styleguide/_config.json and look for this line.

    "sources": [
        {
            "source": "/node_modules/brightspot-express/styleguide",
            "hidden": true
        }
    ],

Warning

If this is present in your project, you should consider this a blocker to your upgrade. See the section below entitled, "How to Flatten a Theme."

Below is a link to the upgrade docs in our delivery notes.
https://perfectsense.github.io/delivery-notes/upgrades/brightspot-styleguide.html

Step 2: Styleguide Upgrade

Below is a link to the upgrade docs in our delivery notes.

Brightspot Styleguide

Note

Use "@brightspot/styleguide" 4.7.8 to pick up parallel screenshots during the build. This may require upgrading Node and/or Yarn. This version is compatible with Brightspot 4.5

Building Additional CSS Files (Some special ones like AMP)

This may also apply for special .less files which are included as .hbs files.

Some projects may have special CSS output rules output for Google AMP, or may have additional CSS files created. With AMP especially, the difference is that the styles are written just like the All.less styles, but are output as a handlebars file, so that the other handlebars templates can inline the styles directly onto the page.

Example of a gulp task for building AMP styles

gulp.task(styleguide.task.extra('amp'), () => {
  return gulp
    .src(['styleguide/Amp.less'], { base: 'styleguide' })
    .pipe(plugins.less())
    .pipe(
      plugins.postcss([
        autoprefixer('last 2 versions'),
        require('postcss-amp'),
        require('postcss-remove-media-query-ranges')({
          max: 767,
          removeMin: true
        })
      ])
    )
    .pipe(plugins.cleanCss())
    .pipe(plugins.rename({ extname: '.min.css.amp.hbs' })) // using the .hbs extension so that we can abuse the existing `include` helper to inline the styles
    .pipe(size({ title: `AMP CSS (shouldn't exceed 75k)` }))
    .pipe(gulp.dest(styleguide.path.build()))
})

Because in webpack less files and all bundles use a js file as the entry point, add an empty Amp.js, and then register that as an entry in webpack common.

// webpack.common.js - In webpack common for example we will need to add a new entry for this new Amp.js 
entry: {
    'styleguide/All.min.js': './styleguide/All.js',
    'styleguide/Amp.min.js': './styleguide/Amp.js'
  },

// Amp.js - The new Amp.js file will be used simply to control and compile the less file
import './Amp.less'

// webpack.prod.js - In webpack prod you may find the following entry that looks like the following. This is the equivalent of that gulp task above. 
// The pathData.chunk.name is pretty much the key you added in webpack.common.js for the new entry.
// This step is not needed for new styles, except for those like amp, which then need be renamed to `.hbs` file extension
plugins: [
  new MiniCssExtractPlugin({
    filename: pathData => {
      if (
        pathData.chunk.name === 'styleguide/Amp.min.js'
      ) {
        return pathData.chunk.name.replace('.js', '') + '.css.hbs'
      } else {
        return pathData.chunk.name.replace('.js', '') + '.css'
      }
    }
  })
],

// OBSERVE THE RULES BELOW. The Rule for All.less is pretty standard. 
// The Amp rule however in this case has been customized with some special postcss settings. 
// This is a good reference for gulp tasks that may do some special post css settings as is the case with this example 
// (observe the original gulpfile version above and youll find the same settings)
module: {
    rules: [
      {
        test: path.resolve(__dirname, './styleguide/All.less'),
        use: [
          MiniCssExtractPlugin.loader,
          'css-loader',
          'postcss-loader',
          'less-loader'
        ]
      },
      {
        test: path.resolve(__dirname, './styleguide/Amp.less'),
        use: [
          MiniCssExtractPlugin.loader,
          'css-loader',
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  "postcss-amp",
                  ["postcss-remove-media-query-ranges", {
                    max: 767,
                    removeMin: true
                  }],
                  'cssnano'
                ],
              },
            },
          },
          'less-loader'
        ]
      }
    ]
  }

How to Flatten a theme

Set your node version to the original node version set in the project.
From your theme directory, run gulp flatten-templates (Gulp should still be available as this should be the first step in a Styleguide upgrade)
1. If gulp is currently present in your project, add it with the following command: npm install -g [email protected]
Assuming no failures from the previous task, your theme is now flattened.
As a final verification, search through your project for the #element or #elementName keywords. These are old .hbs keywords, and their presence indicates that the flattening script failed. This is unlikely, but if it does occur, please raise a support ticket.

Caution

This process will create a very large diff. We recommend that theme flattening occur as its own task with a proper development and QA cycle. This will help with debugging your upgrade if there are front-end issues.

Code styling changes

Due to the large amount of changes that can be introduced with a Styleguide upgrade, disable forced formatting. Reducing the footprint of an upgrade branch is particularly important when active development is ongoing in the codebase. The number of files changed is usually highly correlated with merge conflict frequency with other active development. One important area to reduce the overall file change footprint with code style enforcement accommodations. To the extent possible, this procedure will limit the necessary changes to Styleguide files and attempt to preserve as much of the existing style conventions as possible.

.estlintrc configuration

After you’ve successfully done yarn install, you will be making changes to the eslint configuration to enforce the default eslint rules without the Prettier plugin for this upgrade. This ensures that Prettier does not interfere with your project during the upgrade.

In your .eslintrc, change the line "parser": "babel-eslint" to the line "parser": "@babel/eslint-parser" , as that will be the new package. Also, add the following keys (env and rules) if they do not already exist. The rules key will be used to disable eslint rules that your current files might not be following. (In many upgrades, you may encounter errors prior to this step, and these errors will tell you which rules to disable).

{
    "env": {
        "browser": true,
        "es6": true
    },
    "extends": [
        "eslint:recommended"
    ],
    "parser": "@babel/eslint-parser",
    "parserOptions": {
        "allowImportExportEverywhere": true,
        "sourceType": "module",
        "requireConfigFile": false
    },
    "rules": {
      "indent": 0,
      "someOtherRuleYouWantToDisable": 0
    }
}

Once you have the .eslintrc configuration set up, execute yarn format within your theme directory to run ESLint rules from "eslint:recommended". This will likely result in linting errors in your JavaScript files. Identify the linting rule violations by reviewing error messages, such as no-unused-vars, at the end of each error line as shown below.

eslint errors

After running yarn format, you may see errors similar to those below:

Example error:

/{project}-theme-default/styleguide/core/form/input/Input.js
  13:43  error  'event' is defined but never used  no-unused-vars

/{project}-theme-default/styleguide/dfp/GoogleDfp.js
  136:9  error  Use a regular expression literal instead of the 'RegExp' constructor  prefer-regex-literals

/{project}-theme-default/styleguide/core/search/SearchResultsModule.js
  1:11  error  'URLSearchParams' is already defined as a built-in global variable  no-redeclare

Resolution:

Under the "rules" key in your .eslintrc, add the names of the violated rules, like this:

"rules": {
    "no-useless-return": "off",
    "no-var": "off",
    "no-void": "off",
}

Continue this process to add other rule names for the linting errors in your files until you no longer encounter lint rule errors. You can look at the rules reference for more information on each rule: https://eslint.org/docs/latest/rules/