Jump to navigation

Fractal comes with a local development server for running the web UI while you are building your component library.

Starting the server

You can either start the server using the Fractal CLI tool (if you are using it) or programmatically using Fractal’s API.

Using the CLI tool

You can use the start command from within the root of your project to get the server up and running:

fractal start

You can provide the following (optional) command line options to override the default configuration:

  • -p, --port <port-number> - the port number to use, for example 5000.
  • -t, --theme <theme-name> - the custom theme to use.
  • -s, --sync - whether to use the integrate BrowserSync instance to provide auto-refresh and syncing capabilities
  • -w, --watch - whether to watch components and documentation pages for changes

As an example, the command:

fractal start --watch --port 4000

Would start the preview server at the URL http://localhost:4000 and start watching the filesystem for changes.


If you wish to start the server programmatically, (often useful for build tool integrations), you can create a new server instance using the fractal.web.server() method and then start and stop it as required:

const server = fractal.web.server();

    console.log(`Fractal server is now running at ${server.url}`);


The Server object returned by the call to fractal.web.server() is a Node EventEmitter and will emit error events (and others) that you can bind to. See the fractal.web API docs for full details.

BrowserSync integration

The Fractal web server includes a seamless integration with BrowserSync, should you require it.

When enabled, it provides:

  • Auto-reloading of the web UI when files change
  • Re-injecting of static assets (such as stylesheets) when changes are made
  • A network-accessible URL for device testing
  • Syncing of page navigation between tabs
  • Lots more - see the BrowserSync website for details.

BrowserSync can be enabled as a global option, when starting the server via the CLI tool or programmatically:

Enabling globally

You can configure your Fractal instance to use BrowserSync integration whenever the server is started as follows:

fractal.web.set('server.sync', true);

You can also pass options to the underlying BrowserSync instance using the server.syncOptions property:

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

Using the CLI tool

You can use the --sync option to enable BrowserSync when starting the server:

fractal start --sync


You can set the sync option to true in the server config object when getting a new server instance:

const server = fractal.web.server({
    sync: true

    console.log(`Local URL: ${server.url}`);
    console.log(`Network URL: ${server.urls.sync.external}`);