The Fractal web UI provides a web-based interface to browse your components and their associated files, as well as view project documentation and assets.
It can be run as via an in-built development server or exported to static HTML.
If you are using the Fractal CLI tool, you can start the local web UI server (and watch the file system for changes) with the
start command from within the root of your project directory:
fractal start --watch
See the dev server documentation for more information and configuration options.
You can configure various aspects of the web UI using the
fractal.web.set() method. For example, to use the integrated BrowserSync option by default, you can set the
sync option to
true as follows:
Only core web configuration options can be set using the
fractal.web.set() method. Theme-specific configuration options must be set on the theme instance itself.
To serve static assets from within the web UI you can use the
static.path configuration option to specify the path to a directory of assets:
fractal.web.set('static.path', __dirname + '/public');
All files within that directory will now be made available at a URL that matches the file’s path relative to the directory. For example, given the following project structure (and the configuration setting above):
├── components │ └── ... ├── public │ ├── css │ │ └── example.css │ └── js │ └── scripts.js
The the dev server will serve up the CSS and JS files at the URLs
If you want to prefix the URL path of the assets that are being served up, you can do so with the
The the dev server will now serve up the CSS and JS files from the previous example at the URLs
Linking to assets from view templates
If you want to link to any of your static assets from your components or preview layouts, it is strongly recommended that you use the supplied Handlebars
path helper to do so:
This helper lets you specify the static asset path as a root-relative URL such as
/foobar/css/example.css and will then automatically take care of any path-rewriting necessary to support the static HTML export process.
The web UI is built upon themes. Themes are very powerful, and allow complete control over everything from look and feel to URLs and functionality. Themes can be used to customise the look and feel of the web UI to match your project or even to give a completely different ‘view’ of your component library to different project stakeholders - for instance a ‘no code’ theme for people that might only be interested in reviewing the component previews.
The default theme (called ‘Mandelbrot’) that ships with Fractal also supports a number of customisation options if you don’t want to roll your own custom theme from scratch.