Upgrade Process (scroll down to README)

.eslintrc

{
    ...
    "parser": "@babel/eslint-parser",
    ...
    "rules": {
        "prefer-promise-reject-errors": "off",
        "no-void": "off",
        "no-prototype-builtins": "off"
    }
}

.gitignore

*.zip

.gulpfile

/* IN THIS EXAMPLE THIS IS WHAT TYPICALLY IS SEEN IN BRIGHTSPOT. 
WE CAN NOW COMMENT THIS WHOLE THING OR REMOVE THE FILE. Every task here is  now done in webpack. 
- Assets folder, previewpage.... copied into bundle (now webpack)
- The special css turned into .hbs (now webpack)
- Observe for any special folders your project may have, so that you add them in the webpack equivalent
*/

// const Styleguide = require('brightspot-styleguide')
// const autoprefixer = require('autoprefixer')
// const gulp = require('gulp')
// const plugins = require('gulp-load-plugins')()
// const size = require('gulp-size')

// const styleguide = new Styleguide(gulp, { webpack: true, parent: '../../' })

// gulp.task(styleguide.task.extra('assets'), () => {
//   return gulp
//     .src(
//     [
//       'styleguide/PreviewPage.css',
//       'styleguide/assets/**',
//       'styleguide/examples/**/*.js'
//     ],
//       { base: '.' }
//     )
//     .pipe(gulp.dest(styleguide.path.build()))
// })

// 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()))
// })

.npmrc

# delete all contents or rather delete this file in each theme, as well as root dir

.nvmrc

V12

README.md

Upgrading a brightspot site

Preparation

Before actually upgrading the packages lets start prepariing some of the items that need be changed, these items are things such as disabling non updated themes in orded to work through the themes one at a time, as well as updates to the various linting configurations in order to align with the newer practices, and even stuff like not including zip bundle in project

Lets tell git to ignore Zip bundle in gitignore

in your project add an entrry to ignore *.zip

build.gradle

In your project root directory's build.gradle file:

• look for the line ext.brightspotGradlePluginVersion = and upgrade version to match ext.brightspotGradlePluginVersion = '4.2.9'
• look for the node version and update node as well as the yarn version

node {
    version = '12.22.3'
    yarnVersion = '1.22.1'
    download = true
}

Lets disable some themes (if needed), in order to update them one at a time

• In your project's root directory, look for the file settings.gradle and in that file look for the lines which include and build your themes. These lines look like include(':myproject-theme-themename') & project(':myproject-theme-themename').projectDir = file('themes/myproject-theme-themename') where myproject-theme-themename is really the name and folder of your theme.
  • So now with that in mind, lets comment out those lines for the "all" themes (which are not already updated), and leave only the theme you are updating at the moment uncommented (and any which you've already updated). The goal here is to update the themes one at a time such that we can actually build the project, before moving to the next theme. _{^{Part of the reason is the old and new themes may need different versions of Node}}

Lets disable some themes (again, just like above step, but this time in the file site/build.grade

• Similar to the above steps in this file you'll see lines such as api project(':myproject-theme-themename')

.npmrc files - lets remove them. At least with the typical packages in modern brightspot you should no longer need this file

Not much info to explain. Literally delete or comment out the contents of file. This applies to both the one in root as well as the one in each theme

.eslintrc file - Lets configure this file to use some new things

• Here lets change the line "parser": "babel-eslint" to the line "parser": "@babel/eslint-parser" as that will be the new package.
• Make a mental note that we may need to add some rules to change some linting rules if we face some difficult to update errors when linting. Providing an example of the .eslintrc configurations youll need to update. _{^{Thats not the whole file, its just an example highlighting what you'll want to change.}}

.nvmrc file - Lets create one as ideally you should be using NVM for management of Node

• In the root file create a file called .nvmrc and its contents should be V12

.gulpfile file - Lets note whats in the gulpfile. Ideally you should be able to remove it in its entirety.

• This upgrade step list doesnt cover the scope of a potential upgrade with some extremely unique and custom gulp task that may need to be maintained. The tasks that arre common which we will be moving to webpack are, moving of any assets|static,or other files into bundle as well as the generation of any css files embedded as handlebars, which we commonly do in implementations of amp.

config.json file in the theme... A bit of cleanup

The lines "sources": [], & "vars": {}, were empty... Removing them... Not really part of the upgrade but lets clean that up, by removing those lines.

The webpack files in your theme directory

• There should be 4 files going forward in your theme directory.
  • webpack.profile.js - this one may be new to your project. Copy and paste the file below with the same name in your theme`s folder
  • webpack.dev.js
  • webpack.common.js
  • webpack.prod.js

The changes we need on these webpack files

• For the webpack.profile.js file as the old projects are likely missing it, simply add it. A copy of it is provided herein.
• For the webpack.dev.js file lets make the following tweaks
  • Observe the styleguide variable is now lowercase and the import is differrent
  • Observe the merge import is now written as a non default named import hence the { around it.
  • Moved the common require statement to the top for clarity.
  • The line Styleguide.webpackDevServerConfig(webpack, { is now styleguide.webpack('./styleguide', webpack, {
  • Remember those tasks from gulp I mentioned should be commented out? Look at the use of the copy plugin herein. That does the same copying into the bundle we were previously using webpack for.

• For the webpack.prod.js file lets make the following tweaks
  • Same as above for some of the var names.
  • Additionally now we have a new change to how we extract the CSS into files. Observe also there are some special lines to do the CSS conversion into an HBS file just like we were doing previously for amp. This takes care that portion we were previously handling via gulp (now in webpack)

• For the webpack.common.js file lets make the following tweaks
  • The main additions here is we remove eslint-loader and instead, in plugins run the copy and eslint plugins, to imitate those that setup gulp was doing previously where it was moving the asset directories and such.

Lets prepare the styleguides menu (previously _pages.config.json)

• Look for _pages.config.json and lets rename it to _navigation.config.json
• Other than the name it needs some minor tweaks. Observe the changes with the following before and after.
  • The top level pages should now be navigation
  • The htmlextension is now the json extension just like the files in styleguide
  • The key name is now displayName
  • The key content is now page
  • Also use explicit example rather than any wildcards (not shown in example below however) BEFORE

{
 "pages": [
   {
     "name": "Globals",
     "pages": [
       {
         "name": "Typography",
         "content": "/_resource/TypographyPage.html"
       }
     ]
   }
 ]
}

AFTER

{
  "navigation": [
    {
      "displayName": "Globals",
      "pages": [
        {
          "displayName": "Typography",
          "page": "/_resource/TypographyPage.json"
        }
      ]
    }
  ]
}

finally we can start the actual upgrade updating the package.json

On to the next part

Updates to package.json

This is the last real part of preparing the upgrade. In some ways this step IS the upgrade.

• In the following diff do observe that we are updating various modules. There are some things I want to highlight
  • Brightspot styleguide version is newer, which of course is the main bit of this process
  • We added @babel/eslint-parser and removed the older equivalent
  • We added the copy-webpack-plugin which is whats helping us achieve the copy tasks previously done in gulp
  • We removed gulp. It is no longer needed (your project could vary, but ideally if you have any tasks that need gulp, the advise would be to convert those to webpack as well)
  • (optional) we added web components package. We use it to include the script <script src="{{cdn "/webcomponents-loader/webcomponents-loader.js"}}"></script> (copied into that path via webpack conifg) instead of hardcoding the polyfill into the Page-head.hbs file. This may not be applicable to your project, but if it is, its worth mentioning, and worth updating as its easier to keep that up to date this way vs a hardcoded script.
  • LAST BUT ALSO MOST IMPORTANT (this cannot be seen in image but I included a snippet below in the file package.json). The scripts portion was all uupdated to use the new webpack configs and more. Replace your scripts with these new ones.

Installing the packages

• Once all the aboove its done we are now ready to install the update.
  • Make sure you arre on node version 12
  • On your theme directory run yarn install (If you encounter any issues you can delete the node_modules dir as well as yarn.lock file, and run yarn cache clean and try again... Its a clean start in a sense)

Running the (UPGRADED) styleguide

We've updated the dependencies, but some things will still need to be updated in the FE templates and js.

That being said lets run the styleguide.

Run it using yarn server:styleguide in your terminal while in the theme directory (this is that script in the package.json)

• The build process should be much faster now, and visit localhost:8080 on your browser.
  • Unless you are super lucky the expectation is now you should see styleguide starting to run, but... (onto next section)

What to expect, and what

Now you are likely seeing some errors. If all things arre going as expected, these are lots of js errors, in your terminal regarding linting rules. The quickest way to get through these is:

• Run yarn format to have the formatted quickly format your js based on its expectations.
• You may still have some errors that need to be manually uupdated. Go ahead and do so.
• Additionally you can go back to the eslint.rc file, and add rules, shouulud there be some rules that arre easier fixed by disabling some lint rules (example of such rules provided)

The end

Once all the aboove steps have been done, styleguide should be rendering fine.

Potential gotchas

• In ImageSizes.config, an error I found in some projects is mispelling keys in the image sizes such as previewwidth which should be previewWidth now throws an error.
• In the new _navigation.config.json the hideTabs throws error. I've removed those entries
• In projects that were using displayName to rename a content type (the actual content or module, and not a style) that now throws an error. Removing such usages of displayName.

ConfigJSON_SampleDiff.png

ImageSizes_POTENTIAL_ERROR_NOW_CAUGHT.png

PackageJSON_SampleDiff.png

Webpack.common_SampleDiff.png

build.gradle

package.json

webpack.common.js

webpack.dev.js

Webpack.dev_SampleDiff.png

webpack.prod.js

Webpack.prod_SampleDiff.png

webpack.profile.js