Web UI configuration

There are a number of global configuration options available to customise the behaviour of both the development web server and the static HTML builder.

These options can be set on your Fractal instance using the fractal.web.set() method. See the project settings documentation for more details.


How many concurrent export tasks to run at any one time. Useful if you are experiencing filesystem write errors when running the builder. More is not necessarily faster!

fractal.web.set('builder.concurrency', 5); // default is 10


Path to the folder that the static HTML build should be exported to.

fractal.web.set('builder.dest', __dirname + '/export');


The file extension that should be used for the exported HTML pages.

fractal.web.set('builder.ext', '.php'); // default is '.html'


The file extension that should be used when rewriting URLs for the static export.

If you are going to be serving the exported content via a web server and want to have 'pretty' URLs, then setting this to null (to generate extension-less URLs) and then doing some URL-rewriting on the server (using an .htaccess file or equivalent) is often a good solution.

fractal.web.set('builder.urls.ext', null); // default is '.html'


Whether or not to use BrowserSync to watch the filesystem and reload the web UI when changes occur.

fractal.web.set('server.sync', true); // default is false


An object of options to pass to the underlying BrowserSync instance when using the sync option described above.

fractal.web.set('server.syncOptions', {
    open: true,
    browser: ['google chrome', 'firefox'],
    notify: true

See the BrowserSync documentation for a full list of available options.


Hard-code a port number to start the server on. Generally this option is not required because Fractal will automatically find an available port to use.

fractal.web.set('server.port', 4444); // default is null


Whether to watch the filesystem for changes and trigger the re-building of the underlying data objects when updates occur.

This is effectively a light-weight alternative to the server.sync option, although it lacks any reload functionality or any of the advanced options that BrowserSync provides.

fractal.web.set('server.watch', true); // default is false


The path to the directory where your static assets live. Any assets within this directory will be made available to your components and preview layouts at a URL path relative to this directory. See the static assets documentation for more details.

fractal.web.set('static.path', __dirname + '/public');
// public/bar/foo.css will be served at http://localhost:3000/bar/foo.css


Virtual path prefix for the files that are served from the static asset directory specified in the static.path option. See the static assets documentation for more details.

fractal.web.set('static.path', 'project-assets');
// public/bar/foo.css will be served at http://localhost:3000/project-assets/bar/foo.css
Last Updated: 9/5/2018, 2:14:43 PM