Jekyll::Webpack
This plugin will allow you to build your assets with Webpack after Jekyll has compiled your site to the _site
folder. You will need to have Webpack installed at the root of your project in order for this to work.
Why?
This adds Webpack at a sane point in the build pipeline and will also allow you to parameterize your webpack and other JS config files by prepending them with front matter, before the compilation occurs. You can see a functioning example in the spec/fixtures
folder:-
Installation
Add this line to your application's Gemfile:
gem 'jekyll-webpack'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install jekyll-webpack
And add the following to your site's _config.yml
plugins:
- jekyll/webpack
NOTE the /
- the -
variant is not available yet.
ALSO NOTE - it's probably advisable to place this plugin as the very last one in the build pipe. EG:-
plugins:
- jekyll-otherplug
...
- jekyll/webpack
Usage
In your root Jekyll project folder you need to have Webpack installed, so:-
yarn add webpack webpack-cli --dev
And the basic JS entrypoint mkdir src && touch src/index.js
And you're away! Just run the jekyll serve
or jekyll build
commands with whatever env you need.
Config
Configuring JS config files
There is a _data/tailwind.yml
file in the fixure site that's picked up by adding a frontmatter declaration in tailwind.config.js
. This Tailwind config is in turn picked up by the outputted webpack config and parsed when webpack runs.
Debouncing Webpack runs
Sometimes the webpack build can take a long time. You can configure jekyll-webpack to debounce the build in a number of ways. The options are:-
- run once (when you first run
serve
) - run every n iterations (specify a number of iterations to skip webpack compilation)
- run on watch folder changes (specific a folder to watch and only run webpack when a file in the folder has changed)
Add the following entries into _config.yml
// _config.yml
webpack:
debounce:
run_once: true
// or ...
webpack:
debounce:
every: 10
// or ...
webpack:
debounce:
watch: src
This is very useful if you plan to use jekyll serve
with the --livereload
option as it can speed up your development time significantly.
Cleanup
If you wish to clean out unused source files after webpack has run that got included in the compiled site, you need to add an entry into your _config.yml
like:
// _config.yml
webpack:
cleanup_files: src
// or an array
webpack:
cleanup_files:
- src
- node_modules
Dest inclusion (excluding
If want to ensure that webpack only runs in a specific site dest (eg _site
only, and no subdirectories) you can pass a single path value or an inclusion list of paths you want webpack to run in, at config time, by modifiying the _config.yml
like so:
// _config.yml
webpack:
only_in: _site
// or as a list
webpack:
only_in:
- _site
- _build
Example _config.yml
You can have a look at the possible configuration options in the fixtures config file at spec/fixtures/_config.yml
in this repo.
Development
After checking out the repo, run bin/setup
to install dependencies. Then cd spec/fixtures && yarn
to install required JS dependencies for specs. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/tevio/jekyll-webpack. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Jekyll::Webpack project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.