Vanilla framework documentation

Building with Vanilla

Here you will find information on how you can use different tools to build Vanilla into production CSS.


node-sass

To quickly get set up with node-sass, add the node-sass and vanilla-framework packages to your project dependencies:

yarn add node-sass vanilla-framework

In the script that builds the CSS in your package.json, you should include the path to node_modules when looking for @imports. In this example, we have called the build script "build-css":

"build-css": "node-sass --include-path node_modules src --output dist"

Make a folder src/, create a file inside called style.scss and import Vanilla:

@import vanilla-framework/scss/vanilla;
@include vanilla;

Now run yarn build-css, which will convert any Sass files in the src/ folder to CSS in the dist/ folder. In this case, src/style.scss will compile to dist/style.css, which can then be safely included in an HTML file. Your project's folder structure should now look something like this:

  • index.html
  • package.json
  • yarn.lock

To watch for changes in your Sass files, add the following script to your package.json:

"watch-css": "yarn build-css && node-sass --watch src/*.scss --output dist"

Now if you open an extra terminal and run yarn watch-css, the CSS will be rebuilt every time your Sass files are edited and saved.

For more options on configuring node-sass, for example minification and autoprefixing, refer to the README.md.


Webpack

Webpack is used to compile JavaScript modules, and can be used to inject Vanilla styles to the DOM. To get set up using Vanilla with Webpack, add the webpack and vanilla-framework packages to your project dependencies:

yarn add webpack webpack-cli vanilla-framework

You'll also need to install the required loaders for compiling and bundling Vanilla's Sass files:

yarn add node-sass css-loader sass-loader style-loader

Make a folder src/, create a file inside called style.scss and import Vanilla:

@import vanilla-framework/scss/vanilla;
@include vanilla;

Now, create a webpack.config.js file at your project's root, and write the following:

var path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  module: {
    rules: [
      {
        test: /\.(scss)$/,
        use: [
          {
            // Adds CSS to the DOM by injecting a `<style>` tag
            loader: 'style-loader'
          },
          {
            // Interprets `@import` and `url()` like `import/require()` and will resolve them
            loader: 'css-loader'
          },
          {
            // Loads a SASS/SCSS file and compiles it to CSS
            loader: 'sass-loader',
            options: {
              // Include the path to Vanilla
              includePaths: ['./node_modules']
            }
          }
        ]
      }
    ]
  }
};

Create a file called app.js inside the src/ folder, and write the following:

import './style.scss';

Add a build script to your package.json to run the webpack command:

"build": "webpack"

Now run the command with yarn build, which will bundle the code and put in a a dist/ folder. At the project root, create an index.html with the following code:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  <title>Vanilla using Webpack</title>
</head>
<body>
  <section class="p-strip--light is-bordered">
    <div class="row">
      <h1>Hello Vanilla!</h1>
      <p>This page has been built using Webpack!</p>
    </div>
  </section>
  <script src="./dist/bundle.js"></script>
</body>
</html>

Opening this index.html file should display a title in Vanilla styling, despite not having any CSS.

To enable hot module replacement, you need to add webpack-dev-server to your list of packages:

yarn add webpack-dev-server

And add a "start" script to your package.json to run it:

"start": "webpack-dev-server"

Now when you run yarn start, the Webpack development server will start at http://localhost:8080/ by default. It should show the same index.html file as before, however now you can edit the styles in src/style.scss and the page will automatically refresh to reflect the changes.

Your project's folder structure should now look something like this:

  • index.html
  • package.json
  • webpack.config.js
  • yarn.lock

For more options on configuring Webpack, for example minification and autoprefixing, refer to the docs.


Gulp

To get started with gulp-sass, add the following packages to your project:

yarn add gulp gulp-sass vanilla-framework

Create a file called gulpfile.js in your main directory and write:

var gulp = require('gulp');
var sass = require('gulp-sass');

gulp.task('build-css', function() {
  return gulp.src('./src/*.scss')
  .pipe(sass({ includePaths: ['./node_modules'] }))
  .pipe(gulp.dest('./dist'));
});

gulp.task('watch-css', function() {
  gulp.watch('./src/*.scss', ['build-css']);
});

Make a folder src/, create a file inside called style.scss and import Vanilla:

@import vanilla-framework/scss/vanilla;
@include vanilla;

Now run gulp build-css, which will convert any Sass files in the src/ folder to CSS in the dist/ folder. In this case, src/style.scss will compile to dist/style.css, which can then be safely included in an HTML file. Your project's folder structure should now look something like this:

  • gulpfile.js
  • index.html
  • package.json
  • yarn.lock

If you open an extra terminal and run gulp watch-css, the CSS will be rebuilt every time your Sass files are edited and saved.

For more options on configuring gulp-sass, for example minification and autoprefixing, refer to the README.md.


Git submodules

Creating a submodule in the git repo does not add all the code to the project but includes a reference and path to include the framework. You may find this method useful if you're planing to host on Github Pages.

Run this command at the root of your project (replacing vX.X.X with the release you wish to use)

git submodule add -b vX.X.X -- git@github.com:vanilla-framework/vanilla-framework.git _sass/vanilla-framework

By running the following command it will pull down the framework into the correct location.

git submodule update