Skip to content

Upgrading

Jump to bottom
Brian Muenzenmeyer edited this page Apr 27, 2018 · 30 revisions

Upgrading Pattern Lab Node

To upgrade the Node version of Pattern Lab do the following:

3.X Instructions

Whether or are directly consuming @pattern-lab/patternlab-node or using an edition, the upgrade steps are the same.

To upgrade an edition, assuming no major changes have occurred, run:

npm update or npm update @pattern-lab/patternlab-node

Note the change to scoped packages under the pattern-lab npm organization!

Upgrading from Pattern Lab 2.X to 3.X

There is no automated upgrade path from Pattern Lab 2.X to 3.X.

  • patternlab-config.json is altered to specify template files via configuration
  • patternlab-config.json now utilized uikits both as top-level key and by side-effect, alters the paths objects for both source and public keys
  • You may now be missing patternengine-node-mustache, as it may not be shipped with core any longer. Suggest installing https://github.com/pattern-lab/patternengine-node-mustache/releases/tag/v2.0.0-alpha.1 or greater. npm install @pattern-lab/patternengine-node-mustache or whichever is most current.
  • Since core is now responsible for asset copying and watches, any Edition tasks you have can likely be gutted. Use the API documentation as a guide.
  • The first parameter for build and patternsonly, a callback function, is removed in favor of them both returning promises.
  • postinstall.js is removed. If you were expecting plugins and starterkits to be automatically loaded upon npm install, this magic is no longer the case. Explicitly install these using the API, CLI or even manually.
  • Pattern files that use the [filename][@patternstate].[extension] shorthand may no longer render correctly when included multiple times as a partial. Suggest using the companion [pattern.md] state: [patternstate] frontmattter instead.

2.X Instructions

It's highly recommended to use an edition of Pattern Lab Node, which comes prepackaged with all dependencies, including this core library, and should enable simple core library upgrades.

To upgrade an edition, assuming no major changes have occurred, run:

npm update

Upgrading from Pattern Lab 1.X to 2.X

There is no automated upgrade path from Pattern Lab 1.X to 2.X.

  1. Install an edition of Pattern Lab Node
  2. Move the following files:
  • 1.X source/* to 2.X source/
  • 1.X source/_patterns/00-atoms/00-meta/* to 2.X source/_meta/ (you can then delete source/_patterns/00-atoms/00-meta/)
    • in the file 00-meta/_00-head.mustache replace {% pattern-lab-head %} with {{{ patternLabHead }}}
    • in the file 00-meta/_01-foot.mustache replace {% pattern-lab-foot %} with {{{ patternLabFoot }}}
  • 1.X source/_data/annotations.js to 2.X source/_annotations/
  1. Remap the paths configured in the edition's patternlab-config.json file with yours, if needed.

Any problems, please open an issue

1.X Instructions

1.X is no longer supported.

  1. Important: Make a back-up of source/ and patternlab-config.json and your Gruntfile|Gulpfile.
  2. Download the latest release of the Node version of Pattern Lab and run npm install from your project directory, or use npm update patternlab-node if you originally installed Pattern Lab via npm.
  3. Restore files in source/ and patternlab-config.json if needed.
  4. Be mindful of whether you need to merge any customizations to patternlab-config.json or your Gruntfile|Gulpfile

Note patternlab-config.json was named config.json until version 1.2.0

If you encounter trouble - make sure your npm devDependencies are up to date. Assuming you have the latest package.json file, you can delete the contents of ./node_modules and run npm cache clear before running npm install to pull down everything anew.

Dependency Notes

If running Pattern Lab Node as a dependency

  • Gulpfile\Gruntfile changes occurred in v1.1.0 and v1.1.2. Check out the diffs if you need to merge your configuration.
1.X Addenda:

  • Upgrading to [v.1.3.0](https://github.com/pattern-lab/patternlab-node/releases/tag/v1.3.0_ requires a new dependency, so make sure to run npm update or npm install to get JSON5.

  • Upgrading to v1.2.0 includes a bunch of file re-arranging, and therefore it's more important than ever to take a fresh copy of the source code. Here's the whole diff. Notable changes, if you should attempt to merge manually:

    • Renaming config.json to patternlab-config.json
    • Migration of ./source/_patternlab-files/* to locations under ./core/
    • Optional inclusion of two new mustache files
      • ./source/_patterns/00-atoms/00-meta/_00-head.mustache
      • ./source/_patterns/00-atoms/00-meta/_00-foot.mustache

  • Upgrading to v1.1.0 requires:

    • Major changes have occurred in the shipped Gruntfile|Gulpfile. It's recommended to take the new versions's file and manually merge any customizations you have. The good news is configurable paths make for a ton more flexibility into the future.
    • Add the following to the config.json:
    "paths" : {
  "source" : {
    "root": "./source/",
    "patterns" : "./source/_patterns/",
    "data" : "./source/_data/",
    "styleguide" : "./core/styleguide/",
    "patternlabFiles" : "./source/_patternlab-files/",
    "js" : "./source/js",
    "images" : "./source/images",
    "fonts" : "./source/fonts",
    "css" : "./source/css/"
  },
    • All .scss files have been removed from the filesystem and Gruntfile|Gulpfile. They caused confusion of sorts and added complexity for little benefit, as the styleguide doesn't change significantly and the shipped pattern styling is not intended to be used. With the roadmap point to other kits, for patterns and the styleguide, this feels like good preparation and aligned with the theme of this release to be about future-consumption.

  • Upgraded to v0.14.0 requires:

    • Adding the following to config.json:

"styleGuideExcludes": [ "templates", "pages" ] ```

  • Upgrading to v0.13.0 requires:
    • Overwriting /source/_patternlab-files/styleguide.mustache
    • Overwriting /source/_patternlab-files/viewall.mustache
  • Upgrading to v0.12.0 requires overwriting: source/_patternlab-files/partials/ishControls.mustache
  • Upgrading to v0.10.X or v0.11.0 requires:
    • Add "baseurl" : "" to config.json
    • Overwrite source/_patternlab-files/pattern-header-footer/footer.html
    • Overwrite source/_patternlab-files/styleguide.mustache
    • Overwrite source/_patternlab-files/viewall.mustache
Clone this wiki locally