PatternPack

PatternPack is designed to accelerate the creation of web application pattern libraries. When configured properly it will generate a static site pattern library. The patternpack-example-library demonstrates exactly how to do this and is a good place to learn how to use PatternPack.

Getting Started

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install patternpack --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('patternpack');

A basic gruntfile.js for PatternPack should look like:

module.exports = function (grunt) {
  grunt.initConfig({
    patternpack: {
      run: {},
      build: {},
      release: {}
    }
  });

  grunt.loadNpmTasks('patternpack');

  grunt.registerTask('default', ['patternpack:run']);
}

Running grunt with this will auto-generate all necessary files on initial run.

To learn more about PatternPack, check out the Guides and Resources. We also have a Slack channel available.

PatternPack Task

Run this task with the grunt patternpack command.

Task options may be specified according to the grunt Configuring tasks guide. However the files and targets are not used at this time.

Options

src

Type: string
Default: ./src

The path at which the patterns can be located. This is base path to all the pattern in the pattern library.

build

Type: string
Default: ./html

The path at which the patterns library will be generated. This is the base path where the working pattern library will be created, and can be reviewed during development.

release

Type: string
Default: ./release

The path at which the pattern library will published. This is the base path where the released pattern library assets can be found by consuming applications.

task

Type: string
Default: ""
Allowed Values: "", default, build, integrate, release, release-patch, release-minor, release-major

The action that PatternPack will take when run.

"" default: builds the pattern library and runs a local webserver. build: builds the pattern library. release: alias for release-patch. release-patch: patch increment to the package version, then performs a release. release-minor: minor increment to the package version, then performs a release. release-major: major increment to the package version, then performs a release.

A release performs the following actions

• Increments the package version
• Copies the current build to the release location
• Commits the changes with the version number as the message

assets

Type: string
Default: ./src/assets

A folder to house any additional assets to be shared across projects (e.g., fonts, icons, images, etc.).

theme

Type: string
Default: patternpack-example-theme

The name of the npm package (or the path) which contains the PatternPack theme. Custom themes can be npm modules or simply files that exist within a pattern library. By default PatternPack is configured to use the patternpack-example-theme

data

Type: string Default: ./data

Allows you to pass JSON or YML data files from this directory into your pages. By default, it would be exposed as {{filename}}. To learn more look at the Assemble's documentation on supplying data to templates.

logo

Type: string
Default: /theme-assets/images/logo.svg

Note: if you are using a custom options.theme value, this option is not necessary

If you're using the default theme, you can pass in a custom logo to be used with your library. It should be the path to your logo file relative to the build directory (./html/ if you didn't configure options.build). It's recommended to put the logo inside of the ./src/assets/images directory, and then pass in a value of /assets/images/yourLogo.png.

The logo will be resized via CSS to a max-height of 30px.

css.preprocessor

Type: string
Default: sass Allowed Values: sass, less, none, ""

The type of css preprocessor to run.

sass: runs the sass preprocessor on assets/sass/options.css.fileName.scss less: runs the less preprocessor on assets/less/options.css.fileName.less "" none: does not run any css preprocessor

css.fileName

Type: string
Default: patterns

The final CSS file you will create that will import all your patterns and any other CSS you write. You will manually create this file which will be automatically watched during development and have your configured CSS preprocessor and autoprefixer run on it. Do not add an extension to this file name.

It must live in your configured assets directory under a sass or less subdirectory (e.g., src/assets/sass/patterns.scss).

css.autoprefixer

Type: array
Default: browsers: ['last 2 versions']

Pass in options to PostCSS Autoprefixer. See the available options.

publish.library

Type: boolean
Default: true

Indicates whether a full pattern library will be generated.

publish.patterns

Type: boolean
Default: false

Indicates whether standalone patterns will be generated.

This option can be useful if you would like to integrate patterns directly into another application. For example when the patterns includes components or interations that are only available in the context of the application (such as AngularJS directives).

patternStructure

Type: Array
Default:

[
  { "name": "Atoms", "path": "atoms" },
  { "name": "Molecules", "path": "molecules" },
  { "name": "Pages", "path": "pages" }
]

Specifies the hierarchy used to organize patterns. The default configuration represents the atomic design hierarch, but this can be overriden with any preferred structure.

name: The friendly name that is displayed in the pattern library. path: The location at which the patterns can be found. This path is relative to the src path.

The order of the items in the Array determines the order in which they will be displayed in the pattern library.

server

See the options in grunt-connect

For example:

  server: {
    port: 5555
  }

integrate

Type: string
Default: none

Configures a directory where library builds will copy when running the patternpack:integrate command. Note that it is not recommended to configure this in your gruntfile when sharing across a team. Instead, use the .patternpackrc method below.

Usage Examples

Basic usage

This is an example of the most minimal configuration possible for PatternPack. If the default conventions are followed, minimal grunt configuration is required.

patternpack: {
  run: {},
  build: {},
  integrate: {},
  release: {},
  "release-patch": {},
  "release-minor": {},
  "release-major": {}
}

Custom task names

This example shows how task names can be customized. Configuring the the task option specifies what action PatternPack will take when the custom task is called.

patternpack: {
  customDev: {
    task: 'default' // builds the application and runs the server
  },
  customBuild: {
    task: 'build' // builds the application
  },
  customRelease: {
    task: 'release' // releases the current build
  }
}

Custom file locations

This example demonstrates how to configure PatternPack to point to different file locations for the patterns, and then output the resulting pattern library to a custom location.

patternpack: {
  options: {
    src: './path/to/patterns',
    build: './path/to/pattern-library',
    release: './path/to/release'
  }
}

Custom pattern structure

Using the patternStructure option, you are able to configure the categories you will put your patterns in. In this case components, modules, templates and pages.

patternpack: {
  options: {
    patternStructure: [
      { "name": "Components", "path": "components" },
      { "name": "Modules", "path": "modules" },
      { "name": "Templates", "path": "tmpl" }
      { "name": "Pages", "path": "pages" }
    ]
  }
}

In this configuration PatternPack would look for patterns in:

src/
  components
  modules
  tmpl
  pages

Where src/ is configured in options.src.

User-specific settings override

An individual developer can override any option in the patternpack task by creating a .patternpackrc file. This is a JSON file that would mirror the contents of the patternpack.options portion of your task. It's recommended to add the .patternpackrc file to your .gitignore

For example, to override the server configuration, set up a .patternpackrc file:

{
  "server": {
    "port": 1234
  }
}

Note that this file should be conforming JSON, so all strings should be wrapped in double quotes.

All available options

This example shows all options with their default options.

{
  release: "./dist",
  build: "./html",
  src: "./src",
  assets: "./src/assets",
  css: {
    preprocessor: "sass",
    fileName: "project",
    autoprefixer: {
      browsers: ["last 2 versions"]
    }
  }
  integrate: "../patternpack-example-app/node_modules/patternpack-example-library",
  theme: "./node_modules/patternpack-example-theme",
  logo: "./theme-assets/images/logo.svg",
  publish: {
    library: true,
    patterns: false
  },
  patternStructure: [
    { name: "Atoms", path: "atoms" },
    { name: "Molecules", path: "molecules" },
    { name: "Pages", path: "pages" }
  ],
  server: {
    port: 1234
  }
}

Modular Tasks

PatternPack makes some of its bundled functionality available in modular tasks. They are helpful if you are trying to add custom functionality to your pattern library.

These are available as a part of your patternpack task in your gruntfile.js:

patternpack: {
  options: {
    ...
  },
  build: {},
  "build-styles": {},
  "build-pages": {},
  integrate: {},
},

patternpack:build

This does a complete rebuild of your styles and website into your build directory (/html/). The only difference from this to patternpack:run is that no webserver/livereload is spun up.

1. Cleans your build directory
2. Builds your CSS (patternpack:build-styles)
3. Globs the Sass/LESS in your component directories
4. Builds all your Sass/LESS
5. Runs Autoprefixer
6. Copies your CSS to your build directory
7. Builds your site pages into your build directory (patternpack:build-pages)

patternpack:build-styles

This does a rebuild of your CSS into your build directory.

1. Globs the Sass/LESS in your component directories
2. Builds all your Sass/LESS
3. Runs Autoprefixer

patternpack:build-pages

This rebuilds your website pages into your build directory.

PatternPack Workflow

Pattern Library Development

When developing new patterns for a pattern library, PatternPack provides the patternpack:default and patternpack:build tasks to assist with the process. The patternpack:default task is primarily used for interactive development. It hosts a simple webserver for reviewing changes, and will automatically compile CSS and markdown into patterns as changes are made.

The patternpack:build task does not run the webserver or monitor for changes. It is best used for manual updates and inspection of the pattern library. It is also useful to call as part of a customized build process.

Pattern Library Release

In order to release a new version of a pattern library you create with PatternPack, the following sequence of commands should be executed.

$ grunt patternpack:release
$ git push --follow-tags

grunt patternpack:release generates the pattern library, increments the version, copies the pattern library to the release location, commits the code and tags the git repo with the new version number. git push --follow-tags pushes the code changes to the origin and the newly added tag.

Once released your application should be able to reference the newly tagged version of the pattern library to utilize the new patterns.