United Kingdom: +44 (0)208 088 8978

SAFE Stack hits v2

The SAFE Stack has reached V2! Read on to find out what's changed.

In case you missed it, late last week v2 of the SAFE Stack template was launched! This is a big milestone that's been on the cards for several months now and was publicly previewed during F# Conf earlier this summer. The template introduces a number of changes from v1 both in terms of philosophy as well as technologies, so let's dig in and see what's changed with SAFE Stack:

Simplifying the Template

The biggest change is the template itself, which has been slimmed down from the "anything goes" v1 template to something that will be much simpler to maintain and keep up-to-date, meaning that the team will have more time to spend on other features within SAFE.

Previously, the SAFE template had a large number of features across multiple "dimensions", from the mechanism used to communicate between the client and server to the web server itself, or the hosting platform. Each of these interacted with one another so you ended up with an extremely challenging dev/test cycle for us. We'd built a lot of tooling to check various combinations (and to even automatically generated paket lock files to cater for each permutation) but even with this, we still found issues where we'd add a feature in and discover later on that it broke something else. .NET Templates are a great feature, but don't have great support for "optional" parts of code, needing #if statements to insert code based on different variables. We ended up with a template that was not only fragile, but also expensive to modify - meaning that we either couldn't add in features that we wanted, or it took too long to add in things that should have been simple to do.

The new v2 template has just one parameter: whether to use the default or "minimal" layout.

The Default SAFE Template

The "default" layout comes with a set of opinionated features that will appeal to people that are first getting up and running with SAFE Stack and want a "known good" starting point with most of the knobs tuned to "getting stuff done". You won't have to spend time on webpack settings or adding CSS libraries, nor will you need to add in productivity features such as Fable Remoting or a FAKE script - this is all built in.

The Minimal SAFE Template

Conversely, the "minimal" layout is a very bare bones template that is ideal for SAFE Stack experts that want to "fine tune" an application to meet their needs, or someone that wants to dig under the hood and see what's really going on. It contains no styling, uses raw HTTP for communication and has a minimalistic webpack. It may also appeal to developers coming from a NuGet background as it does not use Paket.

First class .NET Core support

The new template also takes advantage of many of the newer features in the .NET ecosystem that mean that things that (certainly when SAFE first launched) were hand-crafted or needed workarounds now "just work".

For example, the addition of .NET Tools means that FAKE and Paket have first-class support in .NET - they're simply tools that are brought down at build time, whilst we've taken advantage of improvements added to .NET Core's global.json file so that we can specify minimum versions of .NET Core without forcing you to install that exact version.

We've also used this opportunity to upgrade many of the dependencies used in SAFE Stack - so you'll be using the latest versions of Fable, Saturn and Giraffe etc., on .NET Core 3.1.

In short, your build toolchain will be more lightweight and easier to work with, whilst where possible we've preferred to use standard .NET SDK features so people coming from elsewhere in the .NET world will feel more at home.

Azure support

Azure support has always been important on the SAFE Stack, but if we're honest, whilst it worked reliably, there was a lot of code required to make it all play together nicely. Worse still, the getting started experience required you to follow a whole page of steps to create things like Client ID, copying and pasting them around etc. - in short, it definitely didn't fall into the "pit of success" category.

Thankfully, things have moved on since then which means that SAFE v2 has excellent support for Azure deployments today, by taking dependencies on the Farmer project, as well as the Azure CLI. Now, the first time you try to deploy to your Azure subscription, SAFE will automatically pop-up with a login dialog - one time only. There's no more ARM template that needs to be stored in your application as Farmer will create and deploy it for you. In fact, the Azure code is so small now that it fits directly in the FAKE script at just 14 lines of code.

Even if you're not using Azure, you'll appreciate the drastically simplified FAKE script which takes advantage of things like .NET publish to rapidly create a bundle of your combined client and server directly into a folder (and can also be easily achieved without a FAKE script), whilst the generated Saturn application has been greatly simplified as much of the work needed for Azure previously such as custom environment variables and port numbers are no longer required.

Automated Testing support

We've heard people ask repeatedly for support in the template for automated testing, and the new template delivers exactly this. In fact, not only does the template support server-side but also client-side testing of your SAFE application, through Fable.

Landing Page

We've spruced up the SAFE Stack landing page with a cleaner design that gives you key information quickly as well as calls to action on useful resources and getting started guides.

Simplified message

We've also reduced the tagline of SAFE Stack from what was a somewhat-wordy set of technical phrases and keywords to a much simpler message that we feel more succinctly expresses the aim of SAFE Stack:

The best way to write functional-first web applications

Documentation

We've started (but not finished!) the process of upgrading all the documentation on the site. Luckily, a lot of the work so far has been centered around removing documentation that is no longer necessary (although you can still get to the legacy docs on the site if needed).

Recipes

One key thing we've identified both from our day-to-day work with coaching and training as well as community feedback is the need for simple-to-follow guides on how to achieve specific tasks. These include things such as how to add specific features to your application e.g. unit tests, but also how to carry out common tasks e.g. how do I get data from the server onto the client.

Not only are these recipes useful in their own right, but they will effectively replace the extra features that existed in the original SAFE template that have now been deprecated. We've already created 30 recipes with lots more on the way. It's our hope to one day build some automation around these recipes so that a tool would be able to apply them to a "raw" SAFE Stack application.

We're looking for the community to support this initiative, so if you see a recipe in the list and would like to have a crack at writing it up, just let us know!

Looking forward

With v2 now launched, we're going to be putting down a roadmap for the next things we'll be prioritising. Most of these will will center around the ecosystem and documentation:

  • Recipes: More recipes that show you the best way to carry out common tasks.
  • Exercises: More exercises like the SAFE Dojo to give you hands-on experience with the stack.
  • Searchable package repository: There are several websites out there that provide lists of packages across the SAFE Stack. We'd like to provide a single, one-stop-shop for common packages that are used across the stack directly on the site.
  • Demos: Demonstrators with source code that you can look at to learn from, or simply try out to get ideas and see just what's possible with SAFE Stack.
  • More wrappers: We know that one of the concerns of the community is the lack of knowledge around creating JavaScript and React wrappers. We want to tackle this in two ways: firstly, by providing more high-quality wrappers of the most commonly used JS and React libraries and UI tools, and secondly, by providing first-class documentation and walkthrough exercises for people to get up to speed.

Again, we're looking for the community to help us to make SAFE Stack the continue to be the best place to write functional-first web applications.

How can I upgrade my template?

You can update the template by installing the template again: dotnet new -i SAFE.Template. This will bring down v2 and install it on your machine. For existing SAFE v1 applications, if you want to upgrade them we're working on a recipe right now that will give you step-by-step guidance on how to do this, although the utility of this recipe will depend on how much you have changed your application since creation.

Summary

We would have loved to have released SAFE v2 earlier. However, getting feedback from the community has really helped us focus on getting to a place where we think we'll be able to build a much stronger ecosystem more quickly than we would have been able to otherwise, and has put us on a stable foundation to rapidly take advantage of new technologies on the horizon such as .NET 5.

Thanks to everyone who has contributed to the individual components of SAFE and made it the overall web developer experience more popular than I expected it to be, in such a short time.

Have (fun _ -> ()) with SAFE v2!

Isaac