Jekyll is nice and reliable static site generator; however when it comes to using modern Javascript, Jekyll does not seem to have a clear solution or convention. After all, I decided to set up Webpack minimally because it is the cleanest solution to me after trying other solutions by trial and error. Things went well so I just wanted to talk about what I did.
My goals
- Use ES6+ Javascript.
- Manage vendor libraries through Yarn.
- Keep config minimal.
Dependencies
In my environment:
❯ jekyll --version
jekyll 4.0.0
❯ node --version
v12.16.1
❯ ruby --version
ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-darwin19]
❯ yarn --version
1.22.4
Get started
At first, the Webpack config file came across as cryptic and scary, but focusing on one section at a time and reading documentations well, it is actually pretty simple. Also, once configured, I can reuse it for other projects without thinking much about details because I know it is working.
Install webpack, loaders, some useful plugins:
yarn add --dev \
@babel/core \
@babel/preset-env \
babel-loader \
css-loader \
cssnano \
node-sass \
postcss-loader \
sass-loader \
style-loader \
uglifyjs-webpack-plugin \
webpack-cli \
webpack
App structure plan
I get Webpack to load my files from _webpack directory and output bundles to assets directory.
Run these for creating necessary directories and files:
mkdir -p _webpack/{js,scss}
touch _webpack/main.{js,scss}
touch webpack.config.js
Then the app structure will be like this:
.
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _data
├── _includes
├── _layouts
├── _pages
├── _posts
├── _site
├── _webpack
│ ├── js
│ ├── main.js
│ ├── main.scss
│ └── scss
├── assets
│ ├── images
│ └── main-bundle.js
├── index.html
├── node_modules
├── package.json
├── Procfile.dev
├── webpack.config.js
└── yarn.lock
Here is a basic setup.
const path = require('path');
const UglifyJsPlugin = require('uglifyjs-webpack-plugin');
module.exports = {
entry: {
main: path.join(__dirname, '_webpack', 'main'),
},
output: {
path: path.resolve(__dirname, 'assets'),
filename: '[name]-bundle.js',
},
resolve: {
extensions: ['.json', '.js', '.jsx'],
modules: ['node_modules'],
},
optimization: {
minimizer: [
new UglifyJsPlugin({
cache: true,
parallel: true,
sourceMap: true,
}),
],
},
module: {
rules: [
{ test: /\.js$/, exclude: /node_modules/, loader: 'babel-loader' },
{
test: /\.scss$/,
use: [
{
loader: 'css-loader',
options: {
importLoaders: 1,
},
},
{
loader: 'postcss-loader',
options: {
plugins: () => [
require('cssnano')(),
],
},
},
{
loader: 'sass-loader',
options: {},
},
],
},
],
},
};
_webpack/main.js
- This is my Webpack entrypoint also my top-level JS file.
- I import all my necessary JS modules in this file.
- I also initialize JS code here as needed.
- Note: The
./main.scss file needs to be imported here.
Here is an example:
import Turbolinks from 'turbolinks';
import './main.scss';
Turbolinks.start();
_webpack/main.scss
- This is my top-level SCSS file.
- It is imported in the
./main.js file.
Here is an example:
@import 'scss/variables';
@import '~bootstrap/scss/bootstrap.scss';
@import 'scss/highlight';
body {
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
main {
min-height: 80vh;
}
Install npm-run-all NPM package
I like the npm-run-all NPM package because it allows me to organize my custom commands. Long story short, I found these featuers useful:
- The
run-s command: runs given npm-scripts sequentially
- The
run-p command: runs given npm-scripts in parallel
- The above commands accepts glob-like patterns as an argument, which allows me to shorten my scripts for parallel execution
Define commands in package.json
Personally I like defining convenient commands in package.json. Here is an example:
...
"scripts": {
"develop": "bundle exec jekyll clean && run-p develop:{webpack,jekyll}",
"develop:jekyll": "sleep 5 && bundle exec jekyll serve --watch",
"develop:webpack": "webpack --mode development --watch",
"build": "run-s build:webpack build:jekyll purgecss",
"build:jekyll": "JEKYLL_ENV=production bundle exec jekyll build",
"build:webpack": "webpack --mode production",
...
},
...
Now I can run:
yarn develop for running development servers (Webpack and Jekyll)yarn build for production build
In the development environment, once the servers are started, I can view the app at http://localhost:4000. Then whenever files are changed, Webpack will rebuild my asset bundle, which Jekyll detect and update my pages.
So far I have no issue with this set up. Webpack is extensible but I keep the config as simple as possible.
I use Webpack only for bundling JS and CSS. For other tasks, I can just write adhoc scipt in bash or node, which I found is better than using random plugins.
That's it.