Documentation

Learn how Fable works & how to use it

Getting Started

Requirements

First of all, you need a couple of things installed on your computer for F# & Fable development.

npm comes bundled with node.js, but we recommend at least version 5. If necessary, upgrade it by running npm install -g npm. For F# dependencies, Paket will be automatically installed by a bootstraper in Fable templates.

Although is not a Fable requirement, on macOS and Linux you will need Mono for other F# tooling like Paket or editor support.

TL;DR

After installing the requirements, the easiest way to get up and running is to use a Fable template. Below we will see how to install and run the basic Fable.Template to create a simple web app.

Install the template (the same command can be used to update the template to latest version):

dotnet new -i Fable.Template

After that, if you type dotnet new -h you should see "fable" among the list of available templates. Let's call it to scaffold a Fable app:

dotnet new fable -n FableApp -lang F#
cd FableApp

IMPORTANT. PLEASE READ: Always check the README file in the generated project in case instructions change in future versions of the template.

After scaffolding the project, run the following commands (the first one can be skipped if dependencies are already installed and haven't changed):.

In the samples below, yarn is the tool of choice. If you want to use npm, just replace yarn by npm in the commands.

Check the "scripts" section in package.json for more info. If you are using VS Code + Ionide, you can also use F5 or Ctrl+Shift+B (Cmd+Shift+B on macOS) instead of typing yarn start. With this, Fable-specific errors will be highlighted in the editor along with other F# errors. See "Debugging in VS Code" in the template README.

Any modification you do to the F# code will be reflected in the web page after saving. When you want to output the JS code to disk, run yarn build and you'll get your frontend files ready for deployment in the build folder.

You can learn more about the structure of the project generated in the README file.

Now you are a Fable developer! This is all you need to start writing web apps in F#. Go on and experiment for yourself.

A bit longer explanation

Fable has two "hearts" or sides: the .NET side is a daemon (a lightweight TCP server listening by default on port 61225) that waits for messages containing the F# source (.fs) or project (.fsproj) file to parse together with other options, and returns its contents in the form of a Babel compliant AST.

On the other side, there is a JS client that takes care of watching the files, communicating with the Fable daemon, resolving npm dependencies and outputting the actual JS code. Some of the JS clients for Fable available:

  • fable-loader is a plugin for Webpack, a powerful JS bundler with many handy features for development, like live reloading.
  • rollup-plugin-fable for Rollup, another bundler focused on tree shaking.
  • fable-splitter is a standalone tool which, unlike the previous ones, outputs separated files instead of a single bundle.

All the clients need a configuration file, click the links above for more details. Also note that, unlike most JS projects, Fable will reference files outside the local folder (like the NuGet cache). To prevent conflicts, be sure to resolve all paths in the configuration as well as Babel options.

The usual way to run a JS tool is a package.json script, so when you type yarn run build this will invoke a command named "build" within the "scripts" property of the package.json file.

It is actually possible to run the Fable daemon and the JS clients separately:

dotnet fable start

# In a different shell
yarn run webpack-dev-server

The Fable daemon must be invoked in a directory with an .fsproj including a reference to the dotnet-fable package.

For convenience it is possible to tell Fable to automatically start the JS client and stop whenever it finishes. The commands above can be also executed as:

dotnet fable webpack-dev-server

Run dotnet fable --help to know more about the Fable daemon specific options.