avalanche

avalanche is a modular front-end framework which can be extended with npm packages. The goal is to provide a workflow to manage the complexity of big front-end projects.

Getting started

Quick start

• Install npm and gulp on your system (if not already installed).
• Install avalanche globally npm install -g avalanchesass.
• Run avalanchesass --template="project" --name="Your project name" to create a new avalanche project in the current directory.
• Run npm install inside your newly created project directory.
• Run gulp to start the build process.

Extend avalanche

The high modularity of avalanche requires that every part of the system is a distinct package. There are multiple package types:

• Function: custom SASS functions
• Base: base styles like typography and other global default styles (mostly unclassed HTML elements)
• Object: non-cosmetic styles (such as the famous media object)
• Component: concrete, implementation-specific piece of UI
• Utility: utility classes that do specific things (for example clearfix)

You can find various available packages on npm
To extend your installation with a preconfigured package open your package.json file, add the package to your dependencies and run npm install afterwards.

"dependencies": {
  "avalanchesass_base_default": "^3.0.0",
  "avalanchesass_base_form": "^3.0.0",
  "avalanchesass_base_typography": "^3.0.0",
  "avalanchesass_object_media": "^3.0.0",
  "normalize-scss": "^4.0.3"
}

Working with avalanche

Extend packages

If you wan’t to make changes to a class defined by a package it is recommended to create a custom package with the name _PACKAGE_NAME_extend.scss in the scss directory of your project.

Example

Extending the .c-button class of the button component:

• Create a file _button_extend.scss in scss/component.
• Define the .c-button class and override or change it’s properties.
• You can also remove properties by setting their value to initial and adding a /*!remove*/ comment at the end of the line.

.c-button {
  padding: initial;/*!remove*/
  text-transform: uppercase;
}

Attention: removing properties and merging extended classes, will only happen in the minified version of the CSS code. But the styling of your site will be the same: setting a property value to initial has the same effect as removing the property from the original class. Extending the original class by defining it a second time, uses the default cascading behavior of CSS.

Override package variables

Most packages define there own default variables which you can override to change the CSS output. There are two ways how to override variables of external and custom packages:

1. Similar to the extending of packages, you can create a separate file in which you define the variables you want to override (for example _button_variable.scss).
2. If you prefer to have one big file with all the variables inside, you can also override package variables inside the _variable.scss file in your projects scss directory.

CLI

avalanchesass --template="" [--type=""] [--name=""] [--path=""]

Options

• --template mandatory
  possible values: project | package | package-custom
• --type optional
  possible values: Function | Base | Object | Component | Utility
  default value: Component
• --name optional
  possible values: "Your Project Name"
  default value: "Avalanche Project"
• --path optional
  possible values: /path/to/somewhere
  default value: current working directory

Examples

Create a project
avalanchesass --template="project" --name="Project Name"

Create a Component package
avalanchesass --template="package" --type="Component" --name="Package Name"

Create a custom Object package assuming you are in the project diretory
avalanchesass --template="package-custom" --type="Object" --name="Package Name" --path="scss/object"

BEM

avalanche uses the BEM syntax. To make the meaning of the classes more transparent every BEM class name is namespaced. The BEM syntax helps to prevent side effects in CSS and the informative nature of the naming convention makes it ideal for teams and larger projects.

.c-block {}
.c-block__element {}
.c-block--modifier {}

.c-menu {}
.c-menu__link {}
.c-menu--horizontal {}

Style guide

avalanche uses mdcss to automatically generate a style guide from CSS comments in markdown syntax (avalanche style guide DEMO).

Please follow the official mdcss documentation on how to format comments in your SCSS code for the style guide.

To generate the style guide run gulp style_guide. You can also run gulp watch:style_guide instead of the default gulp task to start the build process. This automatically generates the style guide on every change you make to your code base.

CSS extraction

HTTP/2 is coming and changes the way how we should build websites. With HTTP/2 it can be faster to load multiple small files (but only those which are really needed) instead of one big file (with a potential overhead). Example: the pager component isn’t used on most of your pages but the styles are loaded on every request because they are concatenated into one big file.

With CSS extraction you can split your styles into multiple separate CSS files. This makes it possible to load just the styles you need. Amongst other things there are the following advantages using this technique:

• Increased cache granularity (avoids invalidating a whole sprite or concatenated bundle when just a single part changes)
• Parallel downloading of files that before were bundled into one file
• Less energy/memory usage in the client

By default every avalanche package is prepared for CSS extraction. Run gulp styles:extract to create the CSS files - you can find them in dist-extract. Or you can start a watch task with CSS extraction enabled: gulp watch:extract.

To make your custom packages CSS extraction ready, you have to add special placeholder comments.

/* extract component_PACKAGE_NAME.css */
.c-PACKAGE_NAME { … }
/* end extract component_PACKAGE_NAME.css */

To prevent naming collisions it is recommended to add the package type as a prefix to the name of the desired resulting CSS file. If you define two or more extraction sections with the same name, those are combined into one file.

It is recommended to also add placeholder comments for the package type. Because extraction sections with the same name are combined you end up with separate files per package type.

/* extract component.css */
/* extract component_PACKAGE_NAME.css */
.c-PACKAGE_NAME { … }
/* end extract component_PACKAGE_NAME.css */
/* end extract component.css */

About

Author

Markus Oberlehner
Twitter: https://twitter.com/MaOberlehner

License

GPL v2 (http://www.gnu.org/licenses/gpl-2.0.html)