LiveServer.jl - Documentation

LiveServer is a simple and lightweight development web-server written in Julia, based on HTTP.jl. It has live-reload capability, i.e. when changing files, every browser (tab) currently displaying a corresponding page is automatically refreshed.

LiveServer is inspired from Python's http.server and Node's browsersync.

Installation

In Julia ≥ 1.0, you can add it using the Package Manager with

pkg> add LiveServer

Usage

The main function LiveServer exports is serve which starts listening to the current folder and makes its content available to a browser. The following code creates an example directory and serves it:

julia> using LiveServer
julia> LiveServer.example() # creates an "example/" folder with some files
julia> cd("example")
julia> serve() # starts the local server & the file watching
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

Open a Browser and go to http://localhost:8000/ to see the content being rendered; try modifying files (such as index.html) and watch the changes being rendered immediately in the browser.

In the REPL:

julia> using LiveServer
julia> serve(host="0.0.0.0", port=8001, dir=".") # starts the remote server & the file watching
✓ LiveServer listening on http://0.0.0.0:8001...
  (use CTRL+C to shut down)

In the terminal:

julia -e 'using LiveServer; serve(host="0.0.0.0", port=8001, dir=".")'  # like as: python -m http.server 8001

Open a browser and go to https://localhost:8001/ to see the rendered content of index.html or, if it doesn't exist, the content of the directory. You can set the port to a custom number. This is similar to the http.server in Python.

Live serve your docs

A function derived from serve that will be convenient to Julia package developers is servedocs. It runs Documenter.jl along with LiveServer to render your docs and will track and render any modifications to your docs. This instantaneous feedback makes writing docs significantly easier and faster.

Assuming you are in directory/to/YourPackage.jl and that you have a docs/ folder as prescribed by Documenter, just run:

julia> using YourPackage, LiveServer
julia> servedocs()
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: ExpandTemplates: expanding markdown templates.
...
└ Deploying: ✘
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

Open a browser and go to http://localhost:8000/ to see your docs being rendered; try modifying files (e.g. docs/index.md) and watch the changes being rendered in the browser.

You can also use LiveServer with both Documenter and Literate.jl. This is explained here.

How it works

Let's assume you have a directory similar to that generated by LiveServer.example():

.
├── css
│   └── master.css
├── files
│   └── TestImage.png
├── index.html
└── pages
    └── blah.html

Calling serve() from within this directory starts a file server. It serves the contents of the directory as a static site, with the folder structure defining the paths of the URLs. That is, the file blah.html can be viewed at /pages/blah.html. When a directory is specified instead of a file, the server checks whether there is a file index.html in this directory and serves it if available.

Visiting http://localhost:8000/ makes your browser send a standard HTTP GET request to the server. The server, running a listener loop, receives this request, looks for index.html in the root folder, and serves it. After serving it, LiveServer adds this file to the list of watched files. That is, whenever this file changes, a callback is fired (see below). The HTML page may also contain references to style sheets or pictures, which are then requested by your browser as well. The server sends them to the browser, and also adds them to the list of watched files.

But what about the live reloading?

Triggering a page refresh in the browser is achieved by a WebSocket connection. The WebSocket API, according to MDN, is

an advanced technology that makes it possible to open a two-way interactive communication session between the user's browser and a server.

LiveServer injects a small piece of JavaScript code into every HTML file before serving it. This snippet is executed by the browser and opens a WebSocket connection to the server, which in turn adds it to a list of viewers of this page.

The server can now send the message "update" to all viewers of a page whenever the page is changed. The code snippet reacts to this message by triggering a page reload. The update is triggered by the callback mentioned above. When the file is not an HTML file, the viewers of any HTML file are updated, since LiveServer currently does not keep track of which HTML files reference what other files.