@mands/mns-fe-pattern-library

FESK Pattern Library

Welcome to the FESK Pattern Library. This npm module is designed to allow consumers to easily include M&S styles and layouts through elements, components, modules and templates in their projects.

• Usage
• Style guide usage
• Setting up
• Running the app
• Development
• [Running the tests](#running the tests)
• CI and Deployment
• How to
• Quick Links To Relevant Repositories

Usage

To install the module:

npm install @mands/mns-fe-pattern-library

In order for the project to use the styles, include sassPath config in your build config file. For example, if you are using webpack add the following to your webpack.config.js

    const patternLibrary = require('@mands/mns-fe-pattern-library');

    [{
        loader: 'sass-loader',
        options: {
            outputStyle: 'expanded',
            sourceMap: true,
            sourceMapContents: true,
            includePaths: [patternLibrary.sassPath]
        }
    }]

To implement specific parts of the pattern library visit fesk-pattern-library-dev.eu-gb.mybluemix.net for more detailed implementation information.

Style guide usage

The style guide is purely a SASS library to provide global styling for:

• accessibility
• colors
• grid
• iconography
• normalization
• typography
• utilities

These are all located in lib/mns-fe-styles and as lib is set as a sass path you can @import parts of this using mns-fe-styles as the first part of the path. e.g @import 'mns-fe-styles/colors'. You can also import everything using @import 'mns-fe-styles/all'. It is important that you only import parts of the style guide styles once in your application otherwise you will get duplication in your CSS output.

Setting up

First time installation

Within the fesk-pattern-library repository run:

npm install

The fesk-pattern-library repository is shrink-wrapped (find more on Shrinkwrapping here - https://docs.npmjs.com/cli/shrinkwrap). Hence the dependencies would be downloaded from npm-shrinkwrap.json instead of from package.json.

Find more here - https://github.com/DigitalInnovation/fesk-documentation/blob/master/how_tos/shrinkwrap_npm_dependencies.md

Running the app

Run locally

When this is running locally it will run Liniting checks, unit tests and will automatically reload the application when making live code changes both client and server side.

npm run dev

Run production

This is how the application is started after deployment to an environment. This requires the bundled assets.

npm start

Run bundle

If you need to create a bundle locally.

npm run bundle

Development

Lazy Loading

FESK is equipped with lazyloading of images.

1. Import the lazyloading script into your javascript:

   import '../../lib/lazysizes.min';
   

2. Render it with handlebars:

   res.render('productList', {
       cssBundle: getAssetsPromise.then(bundles => bundles['productList.css']),
       jsBundle: getAssetsPromise.then(bundles => bundles['productList.js']),
       commonjsBundle: getAssetsPromise.then(bundles => bundles['common.js']),
       lazysizesBundle: getAssetsPromise.then(bundles => bundles['lib/lazysizes.min.js']),
       title: 'productList',
   });
   

3. In your view:

   <div class="product__image">
       <noscript>
           <img alt="" src="{{{fullImageUrl}}}" itemprop="image"/>
       </noscript>
       <img class="lazyload" data-srcset="{{{fullImageUrl}}}?wid=135&fmt=pjpeg 135w, {{{fullImageUrl}}}?wid=270&fmt=pjpeg&qlt=45 270w,
                    {{{fullImageUrl}}}?wid=245&fmt=pjpeg 245w, {{{fullImageUrl}}}?wid=490&fmt=pjpeg&qlt=45 490w,
                    {{{fullImageUrl}}}?wid=335&fmt=pjpeg&qlt=90 335w, {{{fullImageUrl}}}?wid=670&fmt=pjpeg&qlt=45 670w,
                    {{{fullImageUrl}}}?wid=218&fmt=pjpeg 218w, {{{fullImageUrl}}}?wid=436&fmt=pjpeg&qlt=50 436w,
                    {{{fullImageUrl}}}?wid=264&fmt=pjpeg&qlt=80 264w, {{{fullImageUrl}}}?wid=528&fmt=pjpeg&qlt=35 528w"
            sizes="auto"
            src="{{{fullImageUrl}}}&fmt=pjpeg" alt="" itemprop="image"/>       
   </div>
   

Running the tests

JS Linting

To lint all JS files in the src/ directory and webpack config files.

npm run lint:js

SASS Linting

To check linting issues in all .scss and .sass files in src directory.

npm run lint:sass

A config file named .sass-lint.yml is added at the root folder which contains the list of files included for lint test and rules. This overrides the default config file which is available with same name in node_module.

Unit testing

To run all unit test files that end in .test.js

npm run test:unit

Accessibility testing

To run pa11y-ci tests against all the patterns in the library, first start the dev server then:

npm run test:accessibility

An example of running the tests against a single URL:

npm run test:accessibility http://localhost:3000/patterns/components/banner/

CI and Deployment

Concourse

We have extensive Concourse documentation which can be found here!

Deployment

Concourse

Before you can deploy your pipeline you will need to update TEAM_NAME in /ci/deploy-ci-dachs.sh to your concourse team name.

In majority of the cases deployment should be done via Concourse following the steps listed below:

1. Run ./deployment/deploy-ci.sh target hash providing two arguments:

   • target: target environments (dev or prod). Please note: multiple environments can be supplied if necessary
   • hash: hash of the last commit which should be included in the release

2. This will create a new tag in the project repo's master branch which will be picked up by the Concourse pipeline.

3. At this point you should be able to go to Concourse and see how the build is progressing.

Please note: this style of deployment can ONLY be done on master, it is not possible to deploy from a branch.

Emergency local deployment

Emergency local deployment is created for the cases where Concourse is unavailable but deployment needs to proceed. To run emergency deploy the following prerequisites must be met.

1. Checkout commit you want to deploy to your local machine.

2. Run ./deployment/deploy-emergency.sh target hash providing two arguments:

   • target: is the environment you wish to deploy to
   • hash: is the git hash of the commit you wish to deploy

   As with deployment from Concourse, this will create a tag on your current branch as a record of deployment.

How to

How to make a new page

1. Create a new handlebars template in the views directory.

2. In src/server/routes create a new directory with the handlers and routes you need. Don't forget to load them in src/server/routes/index.js

3. If you want client-side JavaScript and CSS, create a directory in src/client. Add an entry point to the JavaScript file in webpack.config.js. Require the SCSS file in the javascript file in order for it to be recognised by the build system.

   /src
       /client
           /examplePage
               examplePage.js
               examplePage.scss
       /server
           /routes
               /examplePage
                   handlers.js
                   handlers.test.js
                   routes.js
           /views
               examplePage.hbs
       index.js      <-- Edit        
   webpack.config.js  <-- Edit
   

How to add a new pattern

1. Decide whether the new pattern is an element, component or module.

2. Select an appropriate name for the pattern.

3. Then:

   npm run new:pattern [location of pattern] [name of pattern]
   

   The location of the pattern assumes that the path will continue from ./lib/mns-fe-patterns/* For example, if I wanted to create an element called house:

   npm run new:pattern elements house
   

4. If the generation is successful, you will find your pattern with the skeleton files:

   • house/
     • data.json
     • markup.hbs
     • base.scss
     • test.js
   • house.scss

5. NOTE: The generator is not capable of adding directories to paths therefore it is imperative to ensure that all directories listed in the path already exist. For example, if I had a folder of elements but wanted to create the house pattern in a subfolder called houses, the build would fail without the creation of the houses directory prior to the generation of the house pattern.

mns-fe-deployment changes

At current state a set of changes need to be made every time you update mns-fe-deployment.

1. Delete pipelines/build-test-deploy-sit3 folder.

2. Rename pipelines/publish-to-npm/publish-to-npm.optional.yml to publish-to-npm.optional.pipe.yml.

3. In dashboard.yml delete repo-sit-3 and repo-prod resources.

4. Copy contents of pipelines/publish-to-npm/resources.optional.yml into dashboard.yml.

Quick Links To Relevant Repositories

• mns-fe-starter-kit
  • Boilerplate application
• mns-fe-foundation
  • Framework
• fesk-documentation
  • FESK documentation

Automatic publishing with Semantic Release

The pipeline is configured to use the semantic release tool (https://github.com/semantic-release/semantic-release) with the eslint default rules.

• When a PR is merged to master the commit messages are analysed and the npm version number is automatically incremented
• This allows better control over the release process
• Commits can be made without necessarily publishing a package to npm
• When we do publish to npm, the version of the published package now accurately reflects the changes made
• When a merge contains multiple commits the highest rule will be used

The following keywords are allowed:

 ESLint Rules:
 
 Breaking = Major Release
 Fix      = Patch Release
 Update   = Minor Release
 New      = Minor Release
 
    

There may be times when you would like to publish a version manually as shown below:

 export GH_TOKEN=<String>
 export NPM_TOKEN=<String>

 npm run semantic-release 
     

These tokens can be retrieved from the vault:

  gh-token  = fesk-pattern-library.git_token (GitHub auth token)
  npm-token = fesk-pattern-library.npm_token (NPM token)

If you would like to test the commit analyser without actually releasing a new version use the --dry-run flag

npm run semantic-release -- --dry-run

Contact

Team Pegasus

• Email: [e-mail]
• Slack: #fe-starter-kit
• Jira: https://jira.devops.mnscorp.net/projects/FESK