Here you will find information on how you can use different tools to build Vanilla into production HTML and CSS.
To get set up with Sass, add the sass and vanilla-framework packages to your project dependencies:
yarn add 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": "sass -w --load-path=node_modules src:dist --style=compressed"
Make a folder src/, create a file inside called style.scss and import Vanilla:
@import "vanilla-framework";
@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:
To watch for changes in your Sass files, add the following script to your package.json:
"watch-css": "yarn build-css && sass --load-path=node_modules -w src:dist --style=compressed"
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.
A variety of Vanilla's components and patterns are offered as Jinja macros, which may be useful to you if you build sites using the Jinja templating engine. These macros can help abstract away some of the complexity of Vanilla's HTML, making producing complex page layouts simpler and faster.
In order to pull Vanilla's macros into your project, you may need to expose them to your webserver or templating engine. An example of this using Flask and Jinja might look like the following:
from flask import Flask
from jinja2 import ChoiceLoader, FileSystemLoader
app = Flask(__name__)
# ChoiceLoader attempts loading templates from each path in successive order
loader = ChoiceLoader([
FileSystemLoader('templates'),
FileSystemLoader('node_modules/vanilla-framework/templates/')
])
# Loader supplied to jinja_loader overwrites default jinja_loader
app.jinja_loader = loader
After making the macros available to your webserver/templating engine, see the individual component/pattern docs for import and usage instructions.
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';
@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/app.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',
}
]
}
]
}
};
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 lang="en">
<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">
<div class="row--25-75">
<div class="col">
<h1>Hello Vanilla!</h1>
<p>This page has been built using Webpack!</p>
</div>
</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 serve --open"
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:
To provide the same browser support as Vanilla, you should also include autoprefixer in the build pipeline via postcss-loader.
For more options on configuring Webpack, for example minification and autoprefixing, refer to the Webpack documentation.
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;
@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:
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.
To provide the same browser support as Vanilla, you should also include autoprefixer in the build pipeline via gulp-autoprefixer.
For more options on configuring gulp-sass, for example minification and autoprefixing, refer to the gulp-sass documentation.
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 -- git@github.com:canonical/vanilla-framework.git _sass/vanilla-framework && cd _sass/vanilla-framework && git checkout vX.X.X
By running the following command it will pull down the framework into the correct location.
git submodule update