How to Setup a Fable-Elmish Project (May 1 2017)

This is a short post that details the steps needed to setup a basic project with the following tools:

  1. .NET Core and F#
  2. Fable-Elmish
  3. Working Time Travel Debugger on Firefox and Chrome.

At the end, you should have the sample Fable-Elmish project (showing navigation and counter example) running in a browser with a working time travel debugger.

These instructions are working as of 1 May 2017.

NOTE: If you are already familiar with Fable-Elmish, this post will probably not help you. However, I would greatly appreciate any tips or corrections to improve these instructions.

Setup .NET Core and F#

The first step I took was to setup .NET Core. I downloaded and installed 3 packages, in the given order.

IDE

Install the IDE of your choice. I decided to go with Visual Studio Code and Ionide.

At a minimum, install the following extensions in VS Code to take full advantage of Ionide's F# development environment. - Ionide-FAKE - Ionide-fsharp - Ionide-Paket

There are lots of additional extensions available in VS Code that can make your life easier during the development process. Feel free to experiement!

.NET Core

Install .NET Core from the Microsoft Website. - Pick the appropriate version for your environment. - I did this on a Windows 7 64-bit machine, and the x64 version worked correctly for me. - At the time that I installed it, my version of the SDK was 1.0.3.

Microsoft Build Tools

Install Microsoft Build Tools 2015 from the Microsoft Website.

F# 4.0

Install Microsoft Visual F# 4.0 Tools RTM from the Microsoft Website.

At the time that I downloaded this, F# 4.1 was available. However, I used F# 4.0 based on advice in an issue in the Ionide GitHub project.

Setup Fable-Elmish

Install yarn

Yarn is a Node.js package manager, similar to npm. Fable / Fable-Elmish are using yarn, so you will need to install it.

I already had Node and npm installed, so I installed yarn with the following command.

npm install --global yarn

If you do not have npm, then you can download a yarn installer from the Yarn Website. Please note that I'm not sure if you will need npm as well, so keep in mind that you may need to install it later.

Setup a new project with Fable-Elmish

Setting up Fable-Elmish in a way that you can use it for a new project requires a bit of CLI work. Here are the steps.

  1. Open a command prompt / shell.

  2. Install the Fable-Elmish templates. This is the command to install the templates for Fable-Elmish based on the React framework.

    dotnet new -i "Fable.Template.Elmish.React::*"

  3. Create a new Fable-Elmish project.

    dotnet new fable-elmish-react -n project-name

  4. Go to your new project directory.

    cd project-name

  5. Install your Node-based dependencies. Running yarn without parameters is equivalent to the npm install command.

    yarn
  6. When I ran the commands, I received a warning from yarn about the version of my remotedev dependency. When I looked at package.json, I saw that my dependency was at version ^0.2.7 but my devDependency was at version ^0.2.5.
    • I fixed this situation by changing the devDependency version to ^0.2.7.

  7. Restore your NuGet-based dependencies.

    dotnet restore

Setup debugging environment

Chrome

  1. Install the React Developer Tools from the Chrome Web Store.

  2. Install the Redux DevTools from the Chrome Web Store.

Firefox

  1. Install the React Developer Tools from the Mozilla Add-ons site. When installed, this add-on will be called React Devtools.

  2. Install the Redux DevTools from the Mozilla Add-ons site.

Opera, IE, Safari, etc.

I have not tried these instructions myself, so please take with a grain of salt.

  1. React Developer Tools offers a standalone version for browsers / environments other than Chrome and Firefox. You can find the installation and usage instructions on the react-devtools GitHub Website.

  2. zalmoxisus, the person who has released the Redux DevTools extensions for Chrome and Firefox, has a package called remote-redux-devtools for use with browsers / environments other than Chrome and Firefox. You can find the installation and usage instructions on the remote-redux-devtools GitHub website.

Run the sample

  1. To run the sample, go to the project directory and run the following command.

    dotnet fable npm-run start

  2. Open your browser (I recommend Chrome or Firefox) and go to http://localhost:8080/.

  3. To open the debugger:
    • If you are using Chrome or Firefox, you will see a small green icon. Clicking on it will bring up the Redux DevTools panel / window that will show state changes (if you've taken any actions in your browser).
    • If you decided to use the remote-redux-devtools, you may have you modify the default app. If it doesn't work by default, see the fable-elmish debugger GitHub Website for more details.

  4. If you want to build the project for release, run the following command.

    dotnet fable npm-run build

Next steps

At this point, the basics should be setup and the project is ready for your custom code.

If you are stuck, an excellent resource is the Fable Gitter channel, where a number of Fable and Fable-Elmish developers often hang out.

If you are not familiar with the Elm architecture, that is a good next step.

This default version also does not give you certain often-requested features, such as using Rollup instead of Webpack.

Conclusion

If you are still reading, I hope this guide has helped you setup your first Fable-Elmish project.

If you have any suggestions, tips, or corrections, please leave them as a comment below.

See you next time!