Setting up a Vue.js app with Poi is quite an easy and pleasant experience, a lot of magic going on. But what if we need to customize it?
Poi makes it easy and exposes different ways to be customized.
Config File
You can create a poi.config.js in the same level as package.json which Poi will understand by convention. If you’d like, you can change the path by using the --config [path]
option in the CLI.
The config file has a similar structure to Webpack’s. Some options are directly the options of a Webpack plugin.
Let’s see some common customizations we can do.
HTML output
Poi uses html-webpack-plugin under the hood. If you check out the default template, you’ll see that title and description are configurable, so you can customize those:
poi.config.js
module.exports = { html: { title: 'Coolgator', description: 'Cool and hungry alligator' } };
You could use data from package.json, which is a common pattern:
poi.config.js
const pkg = require('./package.json'); module.exports = { html: { title: 'Coolgator', description: pkg.description } };
However, the default template is quite limited for customization. Not to worry though, you can use your own template. Create an index.ejs in the same level as the poi.config.js file and let’s add a list of <icon>
s:
index.ejs
<head> ... <% htmlWebpackPlugin.options.icons.forEach(function(icon) { %> <link rel="icon" sizes="icon.size" href="<%= icon.url %>"> <% }); %> ... </head>
Then add the icons
property:
poi.config.js
const pkg = require('./package.json'); module.exports = { html: { title: 'Coolgator', description: pkg.description, icons: [ { size: '32x32', url: 'http://via.placeholder.com/32x32' } ] } };
Folder structure
You could customize name of the output directory:
poi.config.js
module.exports = { dist: 'buildy' // defaults to 'dist' };
With filename
, you can set how the files will be named. Here you can use Webpack’s [name]
, [hash]
, [id]
, [ext]
and all the special name variables. The defaults are:
poi.config.js
module.exports = { filename: { js: '[name].[hash:8].js', css: 'style.css', images: 'assets/images/[name].[ext]', fonts: 'assets/fonts/[name].[ext]', chunk: '[id].chunk.js' } };
Using staticFolder
you can change the folder name used to copy the raw files to dist:
poi.config.js
module.exports = { staticFolder: 'assets' };
Env variables
Within the env
property, we can define our custom variables:
poi.config.js
module.exports = { env: { VERSION: '2.3' } };
They become available in the code:
const version = process.env.VERSION;
And in the template:
<meta name="version" content="<%= htmlWebpackPlugin.options.env.VERSION %>" />
Autoprefixer
Use the autoprefixer
to modify the settings for the PostCSS autoprefixer plugin:
poi.config.js
module.exports = { autoprefixer: { browsers: ['ie > 9', 'last 4 versions'] } };
Using SCSS
To use a preprocessor, you just need to install the loader and possible dependencies.
For instance, in order to import a .scss file, we need to install:
$ npm install node-sass sass-loader --save-dev
Configuration in package.json
Poi can also be customized by using the poi
property in your project’s package.json file:
package.json
{ "poi": { "dist": "buildy", "staticFolder": "assets" } ... }
Wrapping up
Poi is easily customizable while at the same time preventing you from sinking in a sea of configuration. Here I’ve just shown the most common ones. Feel free to go to the docs to see what else you can do. But remember, it’s better to stick to conventions whenever possible.