Wutch is a python based live server that observes changes in the given directories and executes a shell command on each change. It also, optionally, renders the results in the default web browser, automatically refreshing each web page after every change.
You can use wutch with Sphinx, Jekyll, and other static site generators. On the GIF above you can see how wutch builds its own documentation. It behaves just like a live server. Adding any change causes a subprocess shell to run Sphinx (doc site generator used by wutch) to rebuild its docs in real time.
If you’ve ever worked with live servers popular among frontend developers you know how convenient
they are. Problem is you should either rely on the Live Server extension such as
this one or
create a build pipeline using something like
We wanted to create a command line tool that is able to rebuild documentation or website on each change and automatically refresh browser’s webpage afterwards.
- Watches multiple directories and glob file patters for changes
- Able to ignore multiple directories and glob file patters
- Runs given shell command on each change
- Starts a live server (with an option to bind to a given port and address)
- (optionally) Opens a browser when Wutch starts pointing to the build directory
- Automatically refreshes web page on each build
- Configurable timeout between rebuilds
- Configurable binging port and host (can be used as a development web server)
Hot to install wutch?
At the moment, wutch is distributed as a Python package for Python >= 3.8. In the future
a Homebrew formula, as well as
.rpm distributions will be added.
You can install wutch like this:
Or, to install for the current user only:
How to use wutch?
wutch binary becomes available. Now you can start a wutch watcher process.
By default, it will do the following
- watch current directory
- start a live server
- open a web browser pointing to the
sphinx-buildshell command on each change
- auto-refresh web page on each build
How to configure wutch to perform different actions? Wutch supports multiple sources of
configuration settings. They are loaded in a priority given below. Let’s take
command parameter that specifies what shell command to run as an example here.
- command line options
- environment variables starting with
- configuration file
wutch.cfgpresent in the current directory
- default variables hardcoded into
Below is the full list of supported parameters:
Building Sphinx documentation with Wutch
Wutch relies on itself when building and rendering its own documentation written with Sphinx (see wutch docs sources).
In order to set up a Sphinx doc development using wutch’s live server it’s enough
to place a
wutch.cfg file into the project folder and then simply run wutch binary.
With these settings wutch will look for the changes happening in
files in the
./docs directory. For each change, wutch will run
make -C docs build command from its Makefile.
It will then open the
./docs/_build/html/index.html file in the default browser
and will auto-refresh the browser page every rebuild.
Building Jekyll with Wutch
Jekyll already comes with the
jekyll serve command that creates a server which
rebuilds the website for every change. However, jekyll is not able to refresh the
page in the browser automatically.
Imagine you have a pretty standard Jekyll project structure. Below is a structure of this blog.
Here is how to build and run a live server for it with Wutch. For this example we will be using command line options instead of the config file.
Using Wutch as live server for frontend builds
Even though there are plenty of options in frontend to implement a live server that watches for changes and rebuilds CSS and HTML, still, wutch is capable of that too.
Imagine you have a Gulp based build pipeline for your website and you can run a build
gulp build command. Then all results of the build are dropped into the
directory of the project.
In that case we’d need to look for the changes in the current directory, but ignore
the changes in the