pl-migrate-example

Pattern Lab 2.X to 3.X

Watch the screencast

This repository documents the steps necessary to take a working example of Pattern Lab Node 2.X (Gulp Edition) and upgrade to the lastest Pattern Lab Node 3.X Alpha.

Setup

1. Windows 10
2. node -v = 8.9.4
3. $ gulp -v =
   • CLI version 2.0.1
   • Local version 4.0.0
4. Downloaded https://github.com/pattern-lab/edition-node-gulp/releases/tag/v1.3.4 and extracted into this repo.
5. npm install @pattern-lab/starterkit-mustache-demo --save
6. npm install
7. gulp patternlab:loadstarterkit --kit="@pattern-lab/starterkit-mustache-demo"
8. gulp patternlab:serve - confirm demo output

Overall game-plan

1. Install new dependencies

   • npm install --save @pattern-lab/cli @pattern-lab/core @pattern-lab/engine-mustache @pattern-lab/uikit-workshop

2. Remove old dependencies:

   • npm uninstall browser-sync patternlab-node styleguidekit-assets-default styleguidekit-mustache-default

3. Let's discuss each addition and removal.

   • The new core library.

   • + "@pattern-lab/core": "^3.0.0-alpha.16",
     - "patternlab-node": "^2.0.0"

   • Added the default engine explicitly.

   • + "@pattern-lab/engine-mustache": "^2.0.0-alpha.8",

   • Added the new command line interface for increased capabilities.

   • + "@pattern-lab/cli": "0.0.1-alpha.23",

   • Combined styleguidekits into a single entity, uikits.

   • - "styleguidekit-assets-default": "^3.0.0",
     - "styleguidekit-mustache-default": "^3.0.0",
     + "@pattern-lab/uikit-workshop": "1.0.0-alpha.7",

   • Removed browser-sync. Core now serves Pattern Lab output internally.

   • - "browser-sync": "^2.0.0",

4. Update patternlab-config.json - referring to https://github.com/pattern-lab/patternlab-node/blob/dev/packages/edition-node-gulp/patternlab-config.json when in doubt.

   • Remove following keys. All have been replaced with better conventions.

   • - cleanOutputHtml
     - debug
     - ignored-directories
     - ignored-extensions
     - ishMinimum
     - ishMaximum
     - patternStates

   • Add following keys. See the configuration documentation for more information about each key.

   • + "ishViewportRange": {
     +    "s": [240, 500],
     +    "m": [500, 800],
     +    "l": [800, 2600]
     + },
     + "logLevel": "info",
     + "serverOptions": {
     +    "wait": 1000
     + },
     + "theme": {
     +    "color": "dark",
     +    "density": "compact",
     +    "layout": "horizontal"
     + },
     + "uikits": [
     +    {
     +      "name": "uikit-workshop",
     +      "outputDir": "",
     +      "enabled": true,
     +      "excludedPatternStates": [],
     +      "excludedTags": []
     +    }
     +  ]

   • Alter following keys.

   •  "paths": {
        "source": {
          "root": "./source/",
          "patterns": "./source/_patterns/",
          "data": "./source/_data/",
          "meta": "./source/_meta/",
          "annotations": "./source/_annotations/",
     -    "styleguide": "./node_modules/styleguidekit-assets-default/dist/",
     +    "styleguide": "dist/",
     -    "patternlabFiles": "./node_modules/styleguidekit-mustache-default/views/",
     +    "patternlabFiles": {
     +      "general-header": "views/partials/general-header.mustache",
     +      "general-footer": "views/partials/general-footer.mustache",
     +      "patternSection": "views/partials/patternSection.mustache",
     +      "patternSectionSubtype": "views/partials/patternSectionSubtype.mustache",
     +      "viewall": "views/viewall.mustache"
     +    },
          "js": "./source/js",
          "images": "./source/images",
          "fonts": "./source/fonts",
     -    "css": "./source/css/"
     +    "css": "./source/css"
        },
        "public": {
     -    "root": "./public/",
     -    "patterns": "./public/patterns/",
     -    "data": "./public/styleguide/data/",
     -    "annotations": "./public/annotations/",
     -    "styleguide": "./public/styleguide/",
     -    "js": "./public/js",
     -    "images": "./public/images",
     -    "fonts": "./public/fonts",
     -    "css": "./public/css"
     +    "root": "public/",
     +    "patterns": "public/patterns/",
     +    "data": "public/styleguide/data/",
     +    "annotations": "public/annotations/",
     +    "styleguide": "public/styleguide/",
     +    "js": "public/js",
     +    "images": "public/images",
     +    "fonts": "public/fonts",
     +    "css": "public/css"
        }
      },

5. Update the gulpfile.js

   • Gulp development has stagnated. Gulp v3 and v4 are valid deployment targets. Your gulpfile will need to change depending on your target.
   • If you find yourself wanting to upgrade from v3 to v4 - here is a handy gulp update guide.
   • Due to breadth of changes, no diff supplied. See the commit.
   • Most changes (deletions) related to core now managing the watching / copying / and hosting of assets.
   • Callbacks exist as well as events to integrate with your workflow.

6. Test. Run gulp patternlab:serve