A set of SAFE-ready wrappers around existing React and JS UI Components.
+A fresh retake of the React API in Fable and a collection of high-quality components to build React applications in F#, optimized for happiness. Get it!
+Fable bindings and helpers for React and React Native. Get it!
+Bulma UI wrapper for amazing Feliz DSL. Get it!
+Fulma provides a wrapper around Bulma 0.9.0, an open source CSS framework, for fable-react. Get it!
+Feliz-style Fable bindings for Material-UI. Get it!
+Fable binding for reactstrap. Get it!
+Fable bindings for Material-UI. Get it!
+Fable bindings for Ant Design React components. Get it!
+Bindings for the Free icons of Font Awesome, should be used with Fable.FontAwesome. Get it!
+FluentUI (React) to Fable bindings. Get it!
+React Grid System to Fable bindings. Get it!
+Feliz-style Fable bindings for react-popover. Get it!
+A binding for react-select-search that implements a searchable and customizable dropdown for Feliz applications. Get it!
+Feliz-style Fable bindings for react-kawaii which contains lovely SVG components. Get it!
+Feliz-style Fable bindings for sweetalert2 and sweetalert2-react-content with Feliz style api for use within React applications. Implemented as both normal functions and Elmish commands, for maximum flexibility. Get it!
+SweetAlert integration for Fable, made with love to work in Elmish apps. Get it!
+Toastr integration with Fable, implemented as Elmish commands. Get it!
+A fork and binding of react-animated-tree, adapted to properly work within Elmish applications. Get it!
+Feliz-style Fable bindings for hamburger-react. Get it!
+Feliz-style Fable bindings for react-awesome-slider. Get it!
+Feliz-style Fable bindings for react-select. Get it!
+Fable binding for react-flatpickr that is ready to use within Elmish applications. Get it!
+Feliz-style Fable bindings for tippyjs-react. Get it!
+Feliz-style Fable bindings for react-d3-speedometer. Get it!
+React Kanban bindings for Fable React. Get it!
+This is a Fable React wrapper for canvas that allows you to declare a drawing. Get it!
+An F# computation expression that groups Fable UI data into one or more collapsable panels. Get it!
+Feliz-style Fable bindings for ag-grid. Get it!
+Fable bindings for ag-grid. Get it!
+Feliz-style Fable bindings for react flow. Get it!
+Feliz-style Fable bindings for react-google-maps. Get it!
+Feliz-style bindings for pigeon-maps, React maps without external dependencies. This binding includes it's own custom PigeonMaps.marker component to build map markers manually. Get it!
+Feliz-style bindings for ag-charts. Get it!
+Fable bindings for plotly.js and react-plotly.js with Feliz style api for use within React applications. Lets you build visualizations in an easy, discoverable, and safe fashion. Get it!
+Feliz-style bindings for recharts, a composable charting library built on React components. The binding translates the original API of recharts in a one-to-one fashion but makes it type-safe and easily discoverable. Get it!
+Feliz-style Fable bindings for roughViz visualisation library. It is a fun project when your data visualisations don't need to be formal. This binding is actually made to work with original rough-viz library than renders to the DOM rather than an existing third-party React library which makes it a nice example to learn from. Get it!
+Fable bindings in Feliz style for Facebook's experimental state management library recoil. Get it!
+Fable bindings for jest and friends for delightful Fable testing. Get it!
+Fable library for testing. Inspired by the popular Expecto library for F# and adopts the testList, testCase and testCaseAsync primitives for defining tests. Get it!
+Fable bindings for react-testing-library and user-event. Get it!
+Fable bindings for react spring. Get it!
+ + + + + + + + +Azure is a comprehensive set of cloud services that developers and IT professionals use to build, deploy and manage applications through a global network of data centres. Integrated tools, DevOps and a marketplace support you in efficiently building anything from simple mobile apps to Internet-scale solutions.
+Azure provides a number of flexible services for SAFE applications, including (but not only):
+Azure comes with several ready-made hosting services, including App Service, which enables seamless hosting of web applications, including ASP.NET Core applications (which Saturn is built on top of). In addition, Azure supports a number of managed hosting services for Docker and Kubernetes, which work fantastically well with SAFE.
+Azure comes with a large number of ready-made platform services that can dramatically lower the cost of developing bespoke systems, including:
+Many of the above services have ready-made SDKs that can be run on .NET and therefore from F#.
+ + + + + + + + +Elmish is a library for building single page applications in F#, following the model-view-update architecture made famous by Elm.
+++The following diagram is a simplified, high-level view of the MVU pattern.
+Modelin this case refers to your application's state, withUpdateandViewthe two functions that handle the flow of messaging. If you wish to read more, we also recommend reading the excellent Elmish Book.
Elmish is the library used to build the front-end application in SAFE and that application is compiled to JavaScript by Fable to run in the browser. The SAFE Stack template comes pre-bundled with the Elmish React module, which (as the name suggests) uses the React library to handle the heavy lifting of modifyng the DOM in an efficient way. This allow us to use the pure functional style of the MVU pattern whilst still retaining the ability to have a highly performant user interface.
+Because Elmish works alongside React, it is possible to use the vast number of available React components from the JavaScript ecosystem within our Elmish applications.
+This conceptual diagram illustrates how the different pieces of Elmish, React and Fable fit together to make the front-end part of your SAFE application which runs in the browser.
+Fable is an F#-to-JavaScript (JS) compiler, designed to produce readable and standard JS code. Fable brings all the power of F# to the JS ecosystem, with support for most of the F# core library as well as the most commonly used .NET APIs.
+It also provides rich integration with the JS ecosystem which means that you can use JS libraries from F# (and vice versa) as well as make use of standard JS tools.
+Fable is a tool that generates JavaScript files from F# code. This allows us to write full front end applications using F#. Being able to write both the Server and Client in the same language offers huge benefits especially when you can share code between the two, without the need for duplication. More information on code sharing can be found here.
+As Fable allows us to integrate into the JS Ecosystem, we can make use of tools such as Vite with features including Hot Module replacement and Source Maps.
+The SAFE Template already has Vite configured to get you up and running immediately.
+Learn more about Fable here.
+ + + + + + + + +Saturn is a web development library written in F# which allows you to easily create both server-side MVC applications as well as web APIs. It runs on top of two other components:
+Saturn, via Giraffe, provides very good integration with other ASP.NET Core components such as authentication.
+Many of Saturn's components and concepts will seem familiar to those of us with experience of other web frameworks such as Ruby on Rails, Python’s Django or especially Elixir's Phoenix.
+Saturn provides the ability to drive your SAFE applications from the server. It enables:
+It also integrates with SAFE to allow seamless sharing of types and functions, since Fable will convert most F# into JavaScript. In addition, you can seamless transport data between client and server using either the Fable.JSON or Fable.Remoting libraries, both of which have support for Saturn. You can read more about this here.
+Learn more about Saturn here.
+ + + + + + + + +This page explains the key differences that you should be aware of between running SAFE applications in development and production.
+The SAFE template is geared towards a streamlined development process. It builds and runs both the client and server on your machine.
+During development, in parallel to your .NET web server, Vite dev Server is used to enable hot module replacement. This means that you can continually make changes to your client application code and can rapidly see the results reflected in your browser, without the need to fully reload the application.
+The build of the .NET server also makes use of dotnet watch to have the server automatically restart with the latest changes. Since your backend applications will typically be stateless, this permits a rapid development workflow.
+It's important to note that the Vite dev server is configured to automatically route traffic intended for api/* routes to the backend web server. This simulates how a SAFE application might work in a production environment, with both client and server assets served from a single web server. This also allows you to not worry about ports and hosts for your backend server in your client code, or CORS issues.
+In a production environment, you won't need the Vite dev server. Instead, Vite is used as a one-off compiler step to create your bundled JavaScript from your Fable app (plus dependencies), and then deploy this along with your backend web server which also hosts that content directly. For example, you can use Saturn to host the static content required by the application e.g. HTML, JS and CSS files etc. as well as your backend APIs. This fits very well with standard CI / CD processes, as a build step in your Build.fs or Azure DevOps / AppVeyor / Travis step etc.
+Rather than hosting your client-side content and application inside your web server, you can opt to host your static content from some other service that supports hosting of HTTP content, such as Azure Blobs, or a content hosting service. In such a case, you'll need to consider how to route traffic to your back-end API from your client application (as they are hosted on different domains), as well as handle any potential CORS issues.
+ + + + + + + + +You may receive an error when trying to run the app, e.g. the current version might require {"node":"~18 || ~20","npm":"~9 || ~10"} but your locally installed versions are different. Ideally we'd like to install different versions side-by-side, which we can do using Node Version Manager.
Once NVM is installed, identify the version of Node that you'd like to install by checking this matrix. For our example here we can identify version 20.10.0 as satifying both the Node and npm version requirements. To install this version for the current project run:
nvm install 20.10.0
+nvm use 20.10.0
+The output from these commands will also tell you which version of npm is linked to the Node version, but if you do not currently have that version of npm installed you need to install it manually with the command:
+npm install -g npm@10.2.4
+The version numbers may vary depending on the SAFE Stack version you are using.
+You should now be able to run the app successfully.
+You may see the following SocketProtocolError message in the Debug Console once you have started your SAFE application.
+++
WebSocket connection to 'ws://localhost:8000/socketcluster/' failed: Error during WebSocket handshake: Unexpected response code: 404
Whilst these messages can be safely ignored, you can eliminate them by installing Redux Dev Tools in the launched Chrome instance as described in the debugging prerequisites section.
+VS Code does not kill the Fable process when you stop the debugger, leaving it running as a "zombie". In such a case, you will have to explicitly kill the process otherwise it will hold onto
+port 8080 and prevent you starting new instances. This should be easily doable by sending Ctrl+C in the Terminal window in VS Code for Watch Client task. Tracked here.
A project created from SAFE template might issue the following warning from Webpack upon building the JavaScript bundle:
+WARNING in entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (244 KiB). This can impact web performance.
+We're striving to optimise the bundle size, however with a number of different options and dependencies it's not that easy to stay below the Webpack recommended limit.
+To minimize the bundle size in your project you can try restricting browser compatibility by modifying the Babel Preset targets for Browserslist and thus using less polyfills.
+For more info, see this issue.
+The port that the server runs on changed from 8085 to 5000 (the ASP.NET Core default) in v4 of the SAFE Template. This was to make it compatible with deployment to Azure App Service on Linux.
+ + + + + + + + +With SAFE-Stack you can easily take advantage of serverless computing via Azure Functions.
+With Functions-As-A-Service (FAAS) you can focus on building your business logic and don't need to worry about provisioning and maintaining servers (hence "serverless"). Azure Functions provide a managed compute platform with high reliability. If you use a "consumption plan" it scales on demand and you only get billed for the actual runtime of your code.
+For SAFE apps we see various use cases for FAAS:
+The Azure Portal allows you to create and edit Functions and their source code via an online editor.
+For a short test go to the portal, click the "New" button and search for "Function App". Click through the wizard to create a new Function App. Open the app when it's created and add a new function. Pick "Timer" as scenario and F# as language.
+Replace the contents of function.json with:
+{
+"bindings": [
+ {
+ "name": "myTimer",
+ "type": "timerTrigger",
+ "direction": "in",
+ "schedule": "0 * * * * *"
+ }
+],
+"disabled": false
+}
+and replace the run.fsx with the following F# code:
+open System
+
+let minutesSince (d: DateTime) =
+(DateTime.Now - d).TotalMinutes
+
+let run(myTimer: TimerInfo, log: TraceWriter) =
+let meetupStart = new DateTime(2017, 11, 8, 19, 0, 0)
+
+minutesSince meetupStart
+|> int
+|> sprintf "Our meetup has been running for %d minutes"
+|> log.Info
+Now observe the logs to see that the function runs every minute and outputs the message about the meetup duration.
+While it seems very convenient, the online editor should only be used for testing and prototyping. In SAFE-Stack you usually benefit from reusing your domain model at various places see Client/Server - so we recommend to use "precompiled Azure Functions" as described below.
+In SAFE-Stack scenarios we recommend all deployments should be automated. Here, we discuss two options for deploying your functions apps into Azure.
+In the case of Function Apps the excellent Azure Functions Core Tools can be used. If you use core tools version 2 then the following should be added to your build/deploy script:
+dotnet publish -c Release
+func azure functionapp publish [FunctionApp Name]
+This will compile your Function App in release mode and push it to the Azure portal.
+In the case of a CI server etc., you will need to install the Functions Core Tools on the server and once per functions app log into the CI machine and explicitly authenticate it manually (see the Functions Core Tools docs).
+Since Azure Functions sits on top of Azure App Service, the same mechanisms for deployment there also exist here. In this case, you can use the exact same HTTPS upload capabilities of the App Service to upload a zip of your functions app into your Functions app. The standard SAFE Template can generate this for you for the core SAFE application as part of the FAKE script; the exact same mechanism can be utilised for your functions app.
+As per the standard App Service, HTTPS upload uses a user/pass supplied in the header of the zip which is PUT into the functions app. This user / pass can be taken from the App Service in the Azure Portal directly, or extracted during deployment of your ARM template (as per the FAKE script does for the App Service).
+ + + + + + + + +Sharing your domain types and contracts between client and server is extremely simple. Thanks to Fable's excellent F# transpilation into JavaScript, you can use all standard F# language features such as Records, Tuples and Discriminated Unions without worry. To share types across both your client and server project, first create a project in your repository called e.g Shared.fsproj. This project will contain any assets that should be shared across the client and server e.g. types and functions.
Then, create files with your types in the project as needed e.g
+type Customer = { Id : int; Name : string }
+Reference this project from your server project. You can now reference those types on the server.
+<Project Sdk="Microsoft.NET.Sdk">
+ ...
+ <ItemGroup>
+ <ProjectReference Include="..\Shared\Shared.fsproj" />
+ </ItemGroup>
+ ...
+</Project>
+Finally, reference this project in your client project (as above). You can now reference those types on the client; Fable will automatically convert your F# types into JavaScript in the background.
+You can also share behaviour using the same mechanism at that for sharing types. This is extremely useful for e.g shared validation or business logic that needs to occur on both client and server.
+Fable will translate your functions into native JavaScript, and will even translate many calls to the .NET base class library into corresponding JavaScript! This allows you to compile your domain model and domain logic to many many different targets including:
+You can read more about this on the Fable website.
+When sharing assets between client and server, you may wish to have different implementations for the "client" and "server" sides. For example, if the client-side version of a function should call an NPM package but the server-side version should use a NuGet package. This is a more advanced scenario where you may require different implementations for the JS and .NET version of code. In such situations, you can use #IF directives to conditionally compile code for either platform - see the Fable website for more information.
Using F# on both client and server is at the core of the SAFE stack, as it simplifies the way we think about building web applications by using the same language, idioms and in many cases sharing our code and domain models.
+However, building a client and a server app requires a fundamentally different way of thinking. On the server side we build stateless APIs in Saturn that map HTTP requests to internal functionality, whereas on the frontend we use the Elmish model, implementing the model-view-update pattern: a stateful pattern that lets us think about the application state as it evolves while the application is running.
+Even though we use the same language across platforms, applying these two different programming models forces us to switch our way of thinking back and forth when writing code for the client and for the server. This is where the Elmish.Bridge library comes into play: it brings the Elmish programming model to the server and unifies the way we write the application as a whole.
+Think of Elmish on the server as the model-view-update pattern but without the view part. Instead, you only need to implement init and update functions to manage the server state as it evolves while the server is running.
update functions on client and server can exchange data via message passing.Let's see a simple example of how this might work in practice:
+// Client-side
+let update msg state =
+ match msg with
+ | LoadUsers ->
+ // send the message to the server
+ state, Cmd.bridgeSend ServerMsg.LoadUsers
+ | UsersLoaded users ->
+ // receive message from the server
+ let nextState = { state with Users = users }
+ nextState, Cmd.none
+
+// Server-side
+let update clientDispatch msg state =
+ match msg with
+ | ServerMsg.LoadUsers ->
+ let loadUsersCmd =
+ Cmd.ofAsync
+ getUsersFromDb // unit -> Async<User list>
+ () // input arg = unit
+ UsersLoadedFromDb // User list -> ServerMsg
+ DoNothing // ServerMsg
+ state, loadUsersCmd
+
+ | ServerMsg.UsersLoadedFromDbSuccess users ->
+ // answer the current connected client with data
+ clientDispatch (ClientMsg.UsersLoaded users)
+ state, Cmd.none
+
+ | ServerMsg.DoNothing ->
+ state, Cmd.none
+The above example mimics what would have been a GET request to the server to get user data from database. However, now the client sends a fire-and-forget message to the server to load users, and at some point the server messages the current client back with the results. Notice that the server could have decided to do other things than just messaging the client back: for example, it could have broadcasted the same message to other clients updating their local state of the users.
There are many scenarios where it makes sense to use Elmish.Bridge:
+The biggest distinction between using this and "raw" Saturn is that your web server becomes a stateful service. This introduces several differences for application design.
+The server state has a lifespan equal to the that of the process under which the server instance is running. This means if the server application restarts then the server state will be reset.
+The server state is local to the server instance. This means that if you run multiple web servers, they won't be sharing the same server state by default.
+As of now there is no built-in persistence for the state, but you can implement this yourself using any number of persistance layers such as Redis Cache, Azure Tables or Blobs etc.
+In addition Elmish.Bridge does not use standard HTTP verbs for communication, but rather websockets. Therefore, it is not a suitable technology for an open web server that can serve requests from other sources than Elmish.Bridge clients.
+Head over to Elmish.Bridge to learn more.
+ + + + + + + + +Communicating over raw HTTP using Saturn has three main steps.
+Start by creating a function on your server that returns some data:
+let loadCustomersFromDb() =
+ [ { Id = 1; Name = "Joe Bloggs" } ]
+/// Returns the results of loadCustomersFromDb as JSON.
+let getCustomers next ctx =
+ json (loadCustomersFromDb()) next ctx
+You can opt to combine both of the above functions into one, depending on your preferences, but it's often good practice to separate your data access from serving data in HTTP endpoints.
+Also note the next and ctx arguments. These are used by Giraffe as part of its HTTP pipeline and are required by the json function (Note you can also use Successful.Ok instead of json, which will offer XML serialization as well).
Now expose the api method using Saturn's router construct and add it to your overall application scope:
+
let myApis = router {
+ get "/api/customers/" getCustomers
+}
+For simple endpoints you may elect to embed the API call directly in the scope (and use partial application to omit the next and ctx arguments):
+
let myApis = router {
+ get "/api/customers/" (json (loadCustomersFromDb()))
+}
+Finally, call the endpoint from your client application. +
promise {
+ let! customers = Fetch.fetchAs<Customer list> "api/customers" (Decode.Auto.generateDecoder()) []
+ // do more with customers here...
+}
+Note the use of the promise { } computation expression. This behaves similarly to async { } blocks that you might already know, whilst the fetchAs function retrieves data from the HTTP endpoint specified. The JSON is deserialized as a Customer array using an automatically-generated "decoder" (see the section on serialization for more information).
Alongside raw HTTP, you can also use Fable.Remoting, which provides an RPC-style mechanism for calling server endpoints. With Remoting, you don't need to worry about the details of serialization or of how to consume the endpoint - instead, remoting lets you define you client-server interactions as a shared type that is commonly referred to as a protocol or contract.
+Each field of the record is either of type Async<T> or a function that returns Async<T>, for example:
+
type ICustomerApi = {
+ getCustomers : unit -> Async<Customer list>
+ findCustomerByName : string -> Async<Customer option>
+}
+On the server you would implement the protocol as follows: +
let getCustomers() =
+ async {
+ return [
+ { Id = 1; Name = "John Doe" }
+ { Id = 2; Name = "Jane Smith" } ]
+ }
+
+let findCustomerByName (name: string) =
+ async {
+ let! allCustomers = getCustomers()
+ return allCustomers |> List.tryFind (fun c -> c.Name = name)
+ }
+
+
+let customerApi : ICustomerApi = {
+ getCustomers = getCustomers
+ findCustomerByName = findCustomerByName
+}
+After exposing an HttpHandler from customerApi you can start calling the API from the client.
let api = Remoting.createApi() |> Remoting.buildProxy<ICustomerApi>
+
+async {
+ let! customers = api.getCustomers()
+ for customer in customers do
+ printfn "#%d => %s" customer.Id customer.Name
+}
+Notice here, there is no need to configure routes or JSON serialization, worry about HTTP verbs, or even involve yourself with the Giraffe pipeline. If you open your browser network tab, you can easily inspect what remoting is doing behind the scenes.
+ + + + + + + + +++If you are using the standard SAFE Template (V3 +), you do not need to worry about serialization, as this is taken care of for you by Fable Remoting. However, if you are "rolling your own" communication channel or want to create an "open" API for multiple consumers, this article may be relevant for you.
+
When using basic HTTP communication between the client and server, you'll need to consider how to deserialize data from JSON to F# types.
+In order to guarantee that the serialization / deserialization routines between client and server are compatible, you should replace the JSON converter in Giraffe / Saturn with the Thoth library's serializer. This is the same library as that used in Fable for deserialization, and so will work seamlessly together.
+let configureSerialization (services:IServiceCollection) =
+ services.AddSingleton<Giraffe.Serialization.Json.IJsonSerializer>(Thoth.Json.Giraffe.ThothSerializer())
+The Thoth library makes use of decoders to convert JSON into F# values. There are generally two main approaches to take when doing this: automatic and manual decoders.
+Assume the following Customer record for the remaining examples.
+type Customer =
+ { Id : int
+ Name : string }
+Automatic decoders are the quickest and easier way to deserialize data. It works by Thoth trying to decode JSON automatically from a raw string to an F# type using automatic mapping rules. In the sample below, we fetch data from the /api/customers endpoint and have Thoth create a strongly-typed Decoder for a Customer array.
fetchAs<Customer []> "/api/customers" (Decode.Auto.generateDecoder()) []
+If the serialization fails, Thoth will create an Error (rather than Ok) value for this.
Be aware that automatic decoders are designed to work with primitives, collections, F# records, tuples and discriminated unions but cannot deserialize classes.
+You can reuse decoders when you know you'll be calling them often:
+// let-bound value that exists outside of the update function
+let customerDecoder = Decode.Auto.generateDecoder<Customer>()
+
+// inside the update function
+Fetch.fetchAs (sprintf "api/customers") (Decode.array customerDecoder [])
+Notice how the decoder is bound to a single Customer, and not an array. This way, we can also reuse the decoder on other routes, for example api/customers/1 which would return a single Customer object rather than a collection.
Manual decoders give you total control over how you rehydrate an object from JSON. Use them when:
+You create a manual decoder as follows:
+let customerDecoder : Decoder<Customer> =
+ Decode.object
+ (fun get ->
+ { Id = get.Required.Field "id" Decode.int
+ Name = get.Optional.Field "customerName" Decode.string |> Option.defaultValue "" })
+You can now replace the automatically generated decoder from earlier. You can also "manually" decode JSON to Customers as follows:
+Decode.fromString customerDecoder """{ "id": 67, "customerName": "Joe Bloggs" }"""
+If decoding fails on any field, an error case will be returned.
+ + + + + + + + +One of the most powerful features of SAFE is the ability to seamlessly share code across client and server.
+The basics of code sharing across client and server include:
+These two core areas are explained in more detail here.
+In addition to types and messages, there are several technologies available in SAFE that allow you to send messages from client to server (and from server to client). Each has their own strengths and weaknesses:
+Fable Remoting provides an excellent way to quickly get up and running with the SAFE stack. You can rapidly create contracts and have guaranteed type-safety between both client and server. Consider using remoting for rapid prototyping, since JSON serialization and HTTP routing is handled by the library, you only think of your client-server code in terms of types and stateless functions. Fable remoting is our recommended option for SAFE Stack apps where you "own" the client and server. However, if you need full control over the HTTP channel for returning specific status codes, using custom HTTP verbs or working with headers, then remoting might not for be you.
+The raw HTTP model provided by Saturn with router { } requires you to construct routes manually and does not guarantee that the client and endpoint have the same contract (you have to specify the same type on both sides yourself). However, using the raw HTTP model gives you total control over the routing and verbs used. If you have a public API that is exposed not just to your own application but to third-parties, or you need more fine grained control over your routes and data, you should use this approach.
Lastly, Elmish.Bridge provides an alternative way of modelling client/server communication. Unlike the other two mechanisms, Elmish Bridge provides the same Elmish model on the server as well as the client, as well as the ability to send notifications from the server back to connected clients via websockets. However, the Bridge model is inherently stateful, which means that a server restart could impact all connected clients.
+| + | Fable.Remoting | +Raw HTTP | +Elmish.Bridge | +
|---|---|---|---|
| Client / Server support | +Very easy | +Easy | +Very Easy | +
| State model | +Stateless | +Stateless | +Stateful | +
| "Open" API? | +Yes, with limitations | +Yes | +No | +
| HTTP Verbs? | +POST, GET | +Fully Configurable | +None | +
| Push messages? | +No | +With Channels | +Yes | +
| Pipeline Control? | +Limited | +Full | +Limited | +
Consider using a combination of multiple endpoints supporting combinations of the above to suit your needs!
+ + + + + + + + +Hot Module Replacement (HMR) allows to update the UI of an application while it is running, without a full reload. In SAFE stack apps, this can dramatically speed up the development for web and mobile GUIs, since there is no need to "stop" and "reload" an application. Instead, you can make changes to your views and have them immediately update in the browser, without the need to restart the application.
+In case of web development, the Vite development server will automatically refresh the changed parts of your elmish views whenever you save a file. Alternatively, in the case of mobile app development, this is achieved through React Native's own bundler.
+Since SAFE uses the Model-View-Update architecture with immutable models, the application state only changes when a message is processed; this fits the HMR model very nicely. Here's an example of HMR in action to change the input of a textbox to automatically convert the input to upper case.
+
Server-Side Rendering (SSR) means that some parts of your application code can run on both the server and the client. +For React this means that you can render your components directly to HTML on the server side (e.g. via a node.js server), which allows for better search engine optimization (SEO) and gives a faster initial response, especially on mobile devices.
+The browser typically receives a static HTML site and starts updating the UI immediately; +React's bundle code will be downloaded asynchronously and when it completes, the client-side JavaScript will take over via React's hydrate functionality. In the JavaScript ecosystem this is also known as an "isomorphic" or "universal" app.
+In SAFE, SSR can be done using fable-react. Its approach is a little different from those you might have seen in the JavaScript ecosystem, as it takes a purely F# approach: you render your Elmish views directly on .NET Core, with all the benefits of the .NET Core runtime.
+Welcome to the SAFE documentation site! This site contains all the documentation you'll need to quickly starting creating SAFE apps in F#.
+If you've not heard of SAFE before, please feel free to start with the introduction. Alternatively, you can immediately try out the quickstart guide and tutorial, or simply browse through the documentation.
+If there's anything missing from here, please feel free to add the documentation directly (or supply an issue) to the GitHub repository.
+We hope you enjoy using SAFE as much as we do!
+The SAFE team :)
+
The SAFE stack is the best way to write functional-first web applications.
+The SAFE stack allows you to develop web applications almost entirely in F#, without needing to compromise and shoehorn your codebase into an object-oriented framework or library, and without needing you to be an expert in CSS or HTML to create compelling, rich client-side web applications. SAFE Stack is:
+The SAFE stack is made up of four components:
+SAFE provides developers with a simple and consistent programming model for developing rich, scalable web-enabled applications that can run on multiple platforms. SAFE takes advantage of F#'s functional-first experience backed by the powerful and mature .NET framework to provide a type-safe, reliable experience that leads to the "pit of success".
+This section contains useful repositories that allow you to learn more about the SAFE stack, at your own pace.
+This dojo is a guided set of tasks designed to give you hands-on experience with the client and server components of the SAFE stack. You'll create server-side routes, client side UI and shared validation logic as you create a mashup application to provide details on UK locations.
+The dojo takes around 90 minutes to complete if you have never worked with the stack before.
+The following example repositories (and more!) can be found in the official SAFE Stack organisational GitHub page.
+The simplest Todo app: a client-server application written entirely in F# using Elmish on the client. Remoting for type-safe communication between the two.
+A minimalistic real-worldish blog engine written entirely in F#. Specifically made as a learning resource when building apps with the SAFE stack. This application features many concerns of large apps such as logging, database access, secured remoting, web sockets and much more.
+This sample demonstrates many of the useful features of a larger SAFE application, including login authentication using JWT tokens, automated deployment via Docker and SEO support with urls for pages. It also includes an example of using Azure Storage tables as a persistence store.
+This sample demonstrates how to build and share a complex domain model in SAFE across client and server, along with the use of websockets for a "reactive" UI support push notifications. It also demonstrates the use of F#'s flexible mailbox processors to implement an event-driven architecture.
+This repository shows how to use Azure services to implement a SAFE application that supports searching over multiple data sources with support for find-ahead typing and throttling. The application uses a combination of Azure Search and Azure Storage Tables to construct a large search index that can rapidly find results in a number of ways.
+This application is a real-time chat application built on SAFE that uses the AKKA framework to manage actors that represent chat users, including Akka Streams and the Akkling F# library.
+This application is a sample mobile application using the React Native library, built on top of the SAFE stack. React Native permits a very similar programming when writing SAFE applications as browser applications, so the experience should be very familiar to you.
+Enjoy the latest version of .NET runtime with newest SAFE Stack template!
+After a long beta test period, we're excited to launch SAFE 3! The new template upgrades SAFE to .NET 5 compatibility, Fable 3 and the latest versions of Giraffe and Saturn. We've also introduced the use of the popular Feliz domain-specific language (DSL), upgraded all documentation and made the build process even easier to use.
+We're super excited about this update as well as hearing about your suggestions and ideas to make it even better in the future.
+It's taken a while, but we're delighted to announce the launch of SAFE v2. The new template has been drastically slimmed down and provides a highly streamlined approach, whilst we've incorporated requested features such as testing support out of the box.
+We're looking forward to building on the new template with improved documentation, a set of easy-to-follow recipes for common tasks as well as new demos, exercises and a set of new wrappers around popular JS and React libraries.
+We're pleased to see that the Suave team has clarified their license and explicitly removed the dependency on the Logary package. However, our decision to remove Suave from the SAFE stack remains: Suave no longer forms a part of the strategic goals of the SAFE project, and our server-side focus remains on improving the experience for both Giraffe and Saturn.
+We nonetheless wish the Suave project, team and contributors the best of luck for the future.
+Due to the unclear future regarding the licensing of Suave and its dependencies, the SAFE team has today made the unamimous decision to remove Suave as a recommended option on the SAFE stack. We will no longer provide guidance on integrating Suave with the SAFE stack, nor will we maintain existing capabilities for it in SAFE tooling.
+Our default recommendation for SAFE stack applications is to use Saturn or Giraffe directly, running on top of Kestel on ASP.NET.
+SAFE will continue to promote all libraries, frameworks and toolchains that provide clear and consistent licensing, do not aim to discriminate against specific libraries on a commercial basis and promote open discussion.
+ + + + + + + + +The SAFE acronym is made up of four separate components:
+The Saturn library builds on top of the solid foundation of both the F#-friendly Giraffe and the high performance, rock-solid ASP.NET Core web server to provide a set of optional abstractions which make configuring web applications and constructing complex routes extremely easy to achieve.
+Saturn can host RESTful API endpoints, drive static websites or server-generated content, all inside an easy-to-learn functional programming model.
+Azure is a comprehensive set of cloud services that developers and IT professionals use to build, deploy and manage applications through a global network of data centres. Integrated tools, DevOps and a marketplace support you in efficiently building anything from simple mobile apps to Internet-scale solutions.
+Fable is an F# to JavaScript compiler, designed to produce readable and standard code. Fable allows you to create applications for the browser written entirely in F#, whilst also allowing you to interact with native JavaScript as needed.
+The Elmish model allows you to construct user interfaces running in the browser using a functional programming approach. Based upon on the Elm application model, Elmish uses the Model-View-Update paradigm to allow you to write applications that are simple to reason about. Elmish sits on top of the React framework.
+Please also feel free to read this blog series on the Compositional IT website for more details on the history of SAFE.
+Yes, absolutely. The above components are what we recommended as the default SAFE stack, but you can of course replace the components with alternatives as you see fit. Here are some alternative technologies which are also recommended by the SAFE team if the basic stack does not fit your needs:
+This page provides some basic guidance on getting up and running with your first SAFE application.
+You'll need to install the following pre-requisites in order to build SAFE applications
+You'll also want an IDE to create F# applications. We recommend one of the following great IDEs:
+dotnet new install SAFE.Template to install the SAFE project template (only required once )dotnet new SAFE to create a new SAFE projectdotnet tool restore to install local tools like Fable.dotnet run to build and run the appCongratulations - after a short delay, you'll be presented with a basic SAFE application running in your browser! The application will by default run in "development mode", which means it automatically watches your project for changes; whenever you save a file in the client project it will refresh the browser automatically; if you save a file in the server project it will also restart the server in the background.
+The standard template creates an opinionated SAFE Stack app that contains everything you'll need to start developing, testing and deploying applications into Azure. Alternatively there is a "bare-bones" SAFE Stack app with minimal value-add features. Take a look at the template options to see a side by side comparison of features available between the standard and minimal template.
+Still have issues getting started? Check out the troubleshooting page.
+ + + + + + + + +Fake is a DSL for build tasks that is modular, extensible and easy to start with. Fake allows you to easily build, bundle, deploy your app and more by executing a single command.
+++The standard template comes with a FAKE project by default, so this recipe only applies to the minimal template.
+
Create a new console app called 'Build' at the root of your solution
+dotnet new console -lang f# -n Build -o .
+++We are creating the project directly at the root of the solution in order to allow us to execute the build without needing to navigate into a subfolder.
+
Open the project you just created in your IDE and rename the module it contains from Program.fs to Build.fs.
This renaming isn't explicitly necessary, however it keeps your solution consistent with other SAFE apps and is a better name for the file really.
+++If you just rename the file directly rather than in your IDE, then the Build project won't be able to find it unless you edit the Build.fsproj file as well
+
Open Build.fs and paste in the following code.
open Fake.Core
+open Fake.IO
+open System
+
+let redirect createProcess =
+ createProcess
+ |> CreateProcess.redirectOutputIfNotRedirected
+ |> CreateProcess.withOutputEvents Console.WriteLine Console.WriteLine
+
+let createProcess exe arg dir =
+ CreateProcess.fromRawCommandLine exe arg
+ |> CreateProcess.withWorkingDirectory dir
+ |> CreateProcess.ensureExitCode
+
+let dotnet = createProcess "dotnet"
+
+let npm =
+ let npmPath =
+ match ProcessUtils.tryFindFileOnPath "npm" with
+ | Some path -> path
+ | None -> failwith "npm was not found in path."
+ createProcess npmPath
+
+let run proc arg dir =
+ proc arg dir
+ |> Proc.run
+ |> ignore
+
+let execContext = Context.FakeExecutionContext.Create false "build.fsx" [ ]
+Context.setExecutionContext (Context.RuntimeContext.Fake execContext)
+
+Target.create "Clean" (fun _ -> Shell.cleanDir (Path.getFullName "deploy"))
+
+Target.create "InstallClient" (fun _ -> run npm "install" ".")
+
+Target.create "Run" (fun _ ->
+ run dotnet "build" (Path.getFullName "src/Shared")
+ [ dotnet "watch run" (Path.getFullName "src/Server")
+ dotnet "fable watch --run npx vite" (Path.getFullName "src/Client") ]
+ |> Seq.toArray
+ |> Array.map redirect
+ |> Array.Parallel.map Proc.run
+ |> ignore
+)
+
+open Fake.Core.TargetOperators
+
+let dependencies = [
+ "Clean"
+ ==> "InstallClient"
+ ==> "Run"
+]
+
+[<EntryPoint>]
+let main args =
+ try
+ match args with
+ | [| target |] -> Target.runOrDefault target
+ | _ -> Target.runOrDefault "Run"
+ 0
+ with e ->
+ printfn "%A" e
+ 1
+Run the following command
+dotnet sln add Build.fsproj
+You will need to install the following dependencies:
+Fake.Core.Target
+Fake.IO.FileSystem
+We recommend migrating to Paket. +It is possible to use FAKE without Paket, however this will not be covered in this recipe.
+At the root of the solution, run dotnet paket install to install all your dependencies.
If you now execute dotnet run, the default target will be run. This will build the app in development mode and launch it locally.
To learn more about targets and FAKE in general, see Getting Started with FAKE.
+ + + + + + + + +When developing your SAFE application, the local runtime experience uses Vite to run the client and redirect API calls to the server on a different port. However, when you deploy your application, you'll need to run your Saturn server which will serve up statically-built client resources (HTML, JavaScript, CSS etc.).
+If you created your SAFE app using the recommended defaults, your application already has a FAKE script which will do the bundling for you. You can create a bundle using the following command:
+dotnet run Bundle
+This will build and package up both the client and server and place them into the /deploy folder at the root of the repository.
++See here for more details on this build target.
+
deploy folder at the root of your repository.Server.exe application.http://localhost:5000.You should now see your SAFE application.
+See this article for more information on architectural concerns regarding the move from dev to production and bundling SAFE Stack applications.
+ + + + + + + + +Using Docker makes it possible to deploy your application as a docker container or release an image on docker hub. This recipe walks you through creating a Dockerfile and automating the build and test process with Docker Hub.
Create a .dockerignore file with the same contents as .gitignore
cp .gitignore .dockerignore
+copy .gitignore .dockerignore
+Now, add the following lines to the .dockerignore file:
.git
+Create a Dockerfile with the following contents:
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
+
+# Install node
+ARG NODE_MAJOR=20
+RUN apt-get update
+RUN apt-get install -y ca-certificates curl gnupg
+RUN mkdir -p /etc/apt/keyrings
+RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
+RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
+RUN apt-get update && apt-get install nodejs -y
+
+WORKDIR /workspace
+COPY . .
+RUN dotnet tool restore
+RUN dotnet run Bundle
+
+FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine
+COPY --from=build /workspace/deploy /app
+WORKDIR /app
+EXPOSE 5000
+ENTRYPOINT [ "dotnet", "Server.dll" ]
+This uses multistage builds to keep the final image small.
+docker build -t my-safe-app .docker run -it -p 8080:8080 my-safe-app++Because the build is done entirely in docker, Docker Hub automated builds can be setup to automatically build and push the docker image.
+
Create a docker-compose.server.test.yml file with the following contents:
version: '3.4'
+services:
+ sut:
+ build:
+ target: build
+ context: .
+ working_dir: /workspace/tests/Server
+ command: dotnet run
+docker-compose -f docker-compose.server.test.yml up --build
+++The template is not currently setup for automating the client tests in ci.
+Docker Hub can also run automated tests for you.
+Follow the instructions to enable Autotest on docker hub.
+
++Not recommended for most applications
+
If you often build with docker locally, you may wish to make the build faster by optimising the Dockerfile for caching. For example, it is not necessary to download all paket and npm dependencies on every build unless there have been changes to the dependencies.
+Furthermore, the client and server can be built in separate build stages so that they are cached independently. Enable Docker BuildKit to build them concurrently.
+This comes at the expense of making the dockerfile more complex; if any changes are made to the build such as adding new projects or migrating package managers, the dockerfile must be updated accordingly.
+The following should be a good starting point but is not guaranteed to work.
+FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
+
+# Install node
+ARG NODE_MAJOR=20
+RUN apt-get update
+RUN apt-get install -y ca-certificates curl gnupg
+RUN mkdir -p /etc/apt/keyrings
+RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
+RUN echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
+RUN apt-get update && apt-get install nodejs -y
+
+WORKDIR /workspace
+COPY .config .config
+RUN dotnet tool restore
+COPY .paket .paket
+COPY paket.dependencies paket.lock ./
+
+FROM build as server-build
+COPY src/Shared src/Shared
+COPY src/Server src/Server
+RUN cd src/Server && dotnet publish -c release -o ../../deploy
+
+FROM build as client-build
+COPY package.json package-lock.json ./
+RUN npm install
+COPY src/Shared src/Shared
+COPY src/Client src/Client
+# tailwind.config.js needs to be in the dir where the
+# vite build command is run from otherwise styles will
+# be missing from the bundle
+COPY src/Client/tailwind.config.js .
+RUN dotnet fable src/Client --run npx vite build src/Client
+
+FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine
+COPY --from=server-build /workspace/deploy /app
+COPY --from=client-build /workspace/deploy /app
+WORKDIR /app
+EXPOSE 5000
+ENTRYPOINT [ "dotnet", "Server.dll" ]
+FAKE is a tool for build automation. The standard SAFE template comes with a ready-made build project at the root of the solution that provides support for many common SAFE tasks.
+If you would prefer not to use FAKE, you can of course simply ignore it, but this recipes shows how to completely remove it from your repository. It is important to note that having removed FAKE, you will have to follow a more manual approach to each of these processes. This recipe will only include instructions on how to run the application after removing FAKE.
+++Note that the minimal template does not use FAKE by default, and this recipe only applies to the standard template.
+
Delete Build.fs, Build.fsproj, Helpers.fs, paket.references at the root of the solution.
Remove the following dependencies +
dotnet paket remove Fake.Core.Target
+dotnet paket remove Fake.IO.FileSystem
+dotnet paket remove Farmer
+Now that you have removed the FAKE application dependencies, you will have to separately run the server and the client.
+Navigate to src/Server inside a terminal and execute dotnet run.
Navigate to src/Client inside a terminal and execute the following:
dotnet tool restore
+npm install
+dotnet fable watch -o output -s --run npx vite
+The app will now be running at http://localhost:8080/. Navigate to this address in a browser to see your app running.
See this guide to learn how to package a SAFE application for deployment to e.g. Azure.
+Fable Remoting is a type-safe RPC communication layer for SAFE apps. It uses HTTP behind the scenes, but allows you to program against protocols that exist across the application without needing to think about the HTTP plumbing, and is a great fit for the majority of SAFE applications.
+++Note that the standard template uses Fable Remoting. This recipe only applies to the minimal template.
+
Add Fable.Remoting.Giraffe to the Server and Fable.Remoting.Client to the Client.
+++See How Do I Add a NuGet Package to the Server +and How Do I Add a NuGet Package to the Client.
+
You now need to create the protocol, or contract, of the API we’ll be creating. Insert the following below the Route module in Shared.fs:
+
type IMyApi =
+ { hello : unit -> Async<string> }
+We need to provide a basic routing function in order to ensure client and server communicate on the
+same endpoint. Find the Route module in src/Shared/Shared.fs and replace it with the following:
module Route =
+ let builder typeName methodName =
+ sprintf "/api/%s/%s" typeName methodName
+We now need to provide an implementation of the protocol on the server. Open src/Server/Server.fs and insert the following right after the open statements:
let myApi =
+ { hello = fun () -> async { return "Hello from SAFE!" } }
+We now need to "adapt" Fable Remoting into the ASP.NET pipeline by converting it into a Giraffe HTTP Handler. Don't worry - this is not hard. Find webApp in Server.fs and replace it with the following:
open Fable.Remoting.Server
+open Fable.Remoting.Giraffe
+
+let webApp =
+ Remoting.createApi()
+ |> Remoting.withRouteBuilder Route.builder // use the routing function from step 3
+ |> Remoting.fromValue myApi // use the myApi implementation from step 4
+ |> Remoting.buildHttpHandler // adapt it to Giraffe's HTTP Handler
+We now need a corresponding client proxy in order to be able to connect to the server. Open src/Client/Client.fs and insert the following right after the Msg type:
+
open Fable.Remoting.Client
+
+let myApi =
+ Remoting.createApi()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.buildProxy<IMyApi>
+Replace the following two lines in the init function in Client.fs:
let getHello() = Fetch.get<unit, string> Route.hello
+let cmd = Cmd.OfPromise.perform getHello () GotHello
+with this:
+let cmd = Cmd.OfAsync.perform myApi.hello () GotHello
+At this point, the app should work just as it did before. Now, expanding the API and adding a new endpoint is as easy as adding a new field to the API protocol we defined in Shared.fs, editing the myApi record in Server.fs with the implementation, and finally making calls from the proxy.
First off, you need to create a SAFE app, install the relevant dependencies, and wire them up to be available for use in your F# Fable code.
+dotnet new SAFE
+dotnet tool restore
+Add bulma to your project: +follow this recipe
+Install Fable.Form.Simple.Bulma using Paket: +
dotnet paket add Fable.Form.Simple.Bulma -p Client
+Install bulma and fable-form-simple-bulma npm packages: +
npm add fable-form-simple-bulma
+npm add bulma
+Rename src/Client/Index.css to Index.scss
Update the import in App.fs
...
+importSideEffects "./index.scss"
+...
+...
+- importSideEffects "./index.css"
++ importSideEffects "./index.scss"
+...
+Import bulma and fable-form-simple in Index.scss
@import "bulma/bulma.sass";
+@import "fable-form-simple-bulma/index.scss";
+...
+Remove the Bulma stylesheet link from ./src/Client/index.html, as it is no longer needed:
<link rel="icon" type="image/png" href="/favicon.png"/>
+- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css">
+ <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css">
+With the above preparation done, you can use Fable.Form.Simple.Bulma in your ./src/Client/Index.fs file.
Open the newly added namespaces:
+open Fable.Form.Simple
+open Fable.Form.Simple.Bulma
+Create type Values to represent each input field on the form (a single textbox), and create a type Form which is an alias for Form.View.Model<Values>:
type Values = { Todo: string }
+type Form = Form.View.Model<Values>
+In the Model type definition, replace Input: string with Form: Form
type Model = { Todos: Todo list; Form: Form }
+-type Model = { Todos: Todo list; Input: string }
++type Model = { Todos: Todo list; Form: Form }
+Update the init function to reflect the change in Model:
let model = { Todos = []; Form = Form.View.idle { Todo = "" } }
+-let model = { Todos = []; Input = "" }
++let model = { Todos = []; Form = Form.View.idle { Todo = "" } }
+Change Msg discriminated union - replace the SetInput case with FormChanged of Form, and add string data to the AddTodo case:
type Msg =
+ | GotTodos of Todo list
+ | FormChanged of Form
+ | AddTodo of string
+ | AddedTodo of Todo
+type Msg =
+ | GotTodos of Todo list
+- | SetInput of string
+- | AddTodo
++ | FormChanged of Form
++ | AddTodo of string
+ | AddedTodo of Todo
+Modify the update function to handle the changed Msg cases:
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+ | FormChanged form -> { model with Form = form }, Cmd.none
+ | AddTodo todo ->
+ let todo = Todo.create todo
+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+ model, cmd
+ | AddedTodo todo ->
+ let newModel =
+ { model with
+ Todos = model.Todos @ [ todo ]
+ Form =
+ { model.Form with
+ State = Form.View.Success "Todo added"
+ Values = { model.Form.Values with Todo = "" } } }
+ newModel, Cmd.none
+let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+- | SetInput value -> { model with Input = value }, Cmd.none
++ | FormChanged form -> { model with Form = form }, Cmd.none
+- | AddTodo ->
+- let todo = Todo.create model.Input
+- let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+- { model with Input = "" }, cmd
++ | AddTodo todo ->
++ let todo = Todo.create todo
++ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
++ model, cmd
+- | AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none
++ | AddedTodo todo ->
++ let newModel =
++ { model with
++ Todos = model.Todos @ [ todo ]
++ Form =
++ { model.Form with
++ State = Form.View.Success "Todo added"
++ Values = { model.Form.Values with Todo = "" } } }
++ newModel, Cmd.none
+Create form. This defines the logic of the form, and how it responds to interaction:
let form : Form.Form<Values, Msg, _> =
+ let todoField =
+ Form.textField
+ {
+ Parser = Ok
+ Value = fun values -> values.Todo
+ Update = fun newValue values -> { values with Todo = newValue }
+ Error = fun _ -> None
+ Attributes =
+ {
+ Label = "New todo"
+ Placeholder = "What needs to be done?"
+ HtmlAttributes = []
+ }
+ }
+
+ Form.succeed AddTodo
+ |> Form.append todoField
+In the function todoAction, remove the existing form view. Then replace it using Form.View.asHtml to render the view:
let private todoAction model dispatch =
+ Form.View.asHtml
+ {
+ Dispatch = dispatch
+ OnChange = FormChanged
+ Action = Action.SubmitOnly "Add"
+ Validation = Validation.ValidateOnBlur
+ }
+ form
+ model.Form
+ let private todoAction model dispatch =
+- Html.div [
+- ...
+- ]
++ Form.View.asHtml
++ {
++ Dispatch = dispatch
++ OnChange = FormChanged
++ Action = Action.SubmitOnly "Add"
++ Validation = Validation.ValidateOnBlur
++ }
++ form
++ model.Form
+With the basic structure in place, it's easy to add functionality to the form. For example, the changes necessary to add a high priority checkbox are pretty small.
+ + + + + + + + +This recipe shows how to create an endpoint on the server and hook up it up to the client using HTTP POST. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
+A POST endpoint is normally used to send data from the client to the server in the body, for example from a form. This is useful when we need to supply more data than can easily be provided in the URI.
+++You may wish to use POST for "write" operations and use GETs for "reads", however this is a highly opinionated topic that is beyond the scope of this recipe.
+
Fable Remoting takes care of deciding whether to use POST or GET etc. - you don't have to worry about this. Refer to this recipe for more details.
+Create the type that will store the payload sent from the client to the server.
+type SaveCustomerRequest =
+ { Name : string
+ Age : int }
+Create a new function saveCustomer that will call the server. It supplies the customer to save, which
+is serialized and sent to the server in the body of the message.
let saveCustomer customer =
+ let save customer = Fetch.post<SaveCustomerRequest, int> ("/api/customer", customer)
+ Cmd.OfPromise.perform save customer CustomerSaved
+++The generic arguments of
+Fetch.postare the input and output types. The example above shows that +the input is of typeSaveCustomerRequestwith the response will contain an integer value. This may +be the ID generated by the server for the save operation.
This can now be called from within your update function e.g.
| SaveCustomer request ->
+ model, saveCustomer request
+| CustomerSaved generatedId ->
+ { model with GeneratedCustomerId = Some generatedId; Message = "Saved customer!" }, Cmd.none
+Create a function that can extract the payload from the body of the request using Giraffe's built-in model binding support:
+open FSharp.Control.Tasks
+open Giraffe
+open Microsoft.AspNetCore.Http
+open Shared
+
+/// Extracts the request from the body and saves to the database.
+let saveCustomer next (ctx:HttpContext) = task {
+ let! customer = ctx.BindModelAsync<SaveCustomerRequest>()
+ do! Database.saveCustomer customer
+ return! Successful.OK "Saved customer" next ctx
+}
+Tie your function into the router, using the post verb instead of get.
let webApp = router {
+ post "/api/customer" saveCustomer // Add this
+}
+This recipe shows how to create an endpoint on the server and hook up it up to the client. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
+Fable Remoting is a library which allows you to create client/server messaging without any need to think about HTTP verbs or serialization etc.
+Add your new endpoint onto an existing API contract e.g. ITodosApi. Because Fable Remoting exposes your API through F# on client and server, you get type safety across both.
type ITodosApi =
+ { getCustomer : int -> Async<Customer option> }
+Create a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required. +
let loadCustomer customerId = async {
+ return Some { Name = "My Customer" }
+}
+++Note the use of
+asynchere. Fable Remoting uses async workflows, and not tasks. You can write functions that use task, but will have to at some point map to async usingAsync.AwaitTask.
Tie the function you've just written into the API implementation. +
let todosApi =
+ { ///...
+ getCustomer = loadCustomer
+ }
+Test out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc. See here for more details on the required format.
+Create a new function loadCustomer that will call the endpoint.
let loadCustomer customerId =
+ Cmd.OfAsync.perform todosApi.getCustomer customerId LoadedCustomer
+++Note the final value supplied,
+CustomerLoaded. This is theMsgcase that will be sent into the +Elmish loop once the call returns, with the returned data. It should take in a value that +matches the type returned by the Server e.g.CustomerLoaded of Customer option. See here +for more information.
This can now be called from within your update function e.g.
| LoadCustomer customerId ->
+ model, loadCustomer customerId
+This recipe shows how to create a GET endpoint on the server and consume it on the client using the Fetch API.
+Create a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required. +
open Saturn
+open FSharp.Control.Tasks
+
+/// Loads a customer from the DB and returns as a Customer in json.
+let loadCustomer (customerId:int) next ctx = task {
+ let customer = { Name = "My Customer" }
+ return! json customer next ctx
+}
+++Note how we parameterise this function to take in the
+customerIdas the first argument. Any parameters you need should be supplied in this manner. If you do not need any parameters, just omit them and leave thenextandctxones.This example does not cover dealing with "missing" data e.g. invalid customer ID is found.
+
Tie the function into the router with a route.
+let webApp = router {
+ getf "/api/customer/%i" loadCustomer // Add this
+}
+++Note the use of
+getfrather thanget. If you do not need any parameters, just useget. See here for reference docs on the use of the Saturn router.
Test out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc.
+Create a new function loadCustomer that will call the endpoint.
++This example uses Thoth.Fetch to download and deserialise the response.
+
let loadCustomer customerId =
+ let loadCustomer () = Fetch.get<unit, Customer> (sprintf "/api/customer/%i" customerId)
+ Cmd.OfPromise.perform loadCustomer () CustomerLoaded
+++Note the final value supplied,
+CustomerLoaded. This is theMsgcase that will be sent into the +Elmish loop once the call returns, with the returned data. It should take in a value that +matches the type returned by the Server e.g.CustomerLoaded of Customer. See here +for more information.
An alternative (and slightly more succinct) way of writing this is:
+let loadCustomer customerId =
+ let loadCustomer = sprintf "/api/customer/%i" >> Fetch.get<unit, Customer>
+ Cmd.OfPromise.perform loadCustomer customerId CustomerLoaded
+This can now be called from within your update function e.g.
| LoadCustomer customerId ->
+ model, loadCustomer customerId
+This recipe demonstrates the steps you need to take to store new data on the client using the MVU pattern, which is typically read from the Server. You will learn the steps required to modify the model, update and view functions to handle a button click which requests data from the server and handles the response.
+Create a type in the Shared project which will act as the contract type between client and server. As SAFE compiles F# into JavaScript for you, you only need a single definition which will automatically be shared. +
type Customer = { Name : string }
+Modify the Msg type to have two new messages:
type Msg =
+ // other messages ...
+ | LoadCustomer of customerId:int // Add this
+ | CustomerLoaded of Customer // Add this
+++You will see that this symmetrical pattern is often followed in MVU:
++
+- A command to initiate a call to the server for some data (LoadCustomer)
+- An event with the result of calling the command (CustomerLoaded)
+
Update the Model to store the Customer once it is loaded: +
type Model =
+ { // ...
+ TheCustomer : Customer option }
+++Make
+TheCustomeroptional so that it can be initialised asNone(see next step).
Update the init function to provide default data
+
let model =
+ { // ...
+ TheCustomer = None }
+Update your view to initiate the LoadCustomer event. Here, we create a button that will start loading customer 42 on click:
+
let view model dispatch =
+ Html.div [
+ // ...
+ Html.button [
+ prop.onClick (fun _ -> dispatch (LoadCustomer 42))
+ prop.text "Load Customer"
+ ]
+ ]
+Modify the update function to handle the new messages:
+
let update msg model =
+ match msg with
+ // ....
+ | LoadCustomer customerId ->
+ // Implementation to connect to the server to be defined.
+ | CustomerLoaded c ->
+ { model with TheCustomer = Some c }, Cmd.none
+++ + + + + + + + +The code to fire off the message to the server differs depending on the client / server communication you are using and normally whether you are reading or writing data. See here for more information.
+
Saturn is a functional alternative to MVC and Razor which sits on top of Giraffe. Giraffe itself is a functional wrapper around the ASP.NET Core web framework, making it easier to work with when using F#.
+Since Saturn is built on top of Giraffe, migrating to using "raw" Giraffe is relatively simple to do.
+Navigate to the Server module in the Server project.
+Remove +
open Saturn
+open Giraffe
+open Microsoft.AspNetCore.Builder
+open Microsoft.Extensions.DependencyInjection
+open Microsoft.Extensions.Hosting
+open Microsoft.AspNetCore.Hosting
+In the same module, we need to replace the Server's application computation expression with some functions which set up the default host, configure the application and register services.
Remove this
+let app =
+ application {
+ // ...setup functions
+ }
+
+[<EntryPoint>]
+let main _ =
+ run app
+ 0
+and replace it with this
+let configureApp (app : IApplicationBuilder) =
+ app
+ .UseStaticFiles()
+ .UseGiraffe webApp
+
+let configureServices (services : IServiceCollection) =
+ services
+ .AddGiraffe() |> ignore
+
+[<EntryPoint>]
+let main _ =
+ Host.CreateDefaultBuilder()
+ .ConfigureWebHostDefaults(
+ fun webHostBuilder ->
+ webHostBuilder
+ .Configure(configureApp)
+ .ConfigureServices(configureServices)
+ .UseWebRoot("public")
+ |> ignore)
+ .Build()
+ .Run()
+ 0
+If you are using the standard SAFE template, there is nothing more you need to do, as routing is taken care of by Fable Remoting.
+If however you are using the minimal template, you will need to replace the Saturn router expression with the Giraffe equivalent.
+Replace this +
let webApp =
+ router {
+ get Route.hello (json "Hello from SAFE!")
+ }
+with this +
let webApp = route Route.hello >=> json "Hello from SAFE!"
+The steps shown here are the minimal necessary to get a SAFE app running using Giraffe.
+As with any Server setup however, there are many more optional parameters that you may wish to configure, such as caching, response compression and serialisation options as seen in the default SAFE templates amongst many others.
+See the Giraffe and ASP.NET Core host builder, application builder and service collection docs for more information on this.
+ + + + + + + + +In SAFE apps, you can send a file from the server to the client as well as you can send any other type of data.
+Since the standard template uses Fable.Remoting, we need to edit our API definition first. Find your API type definition in Shared.fs. It's usually the last block of code. The one you see here is named ITodoAPI. Edit this definition to have the download member you see below.
type ITodoAPI =
+ { //...other routes
+ download : unit -> Async<byte[]> }
+Open the Server.fs file and find the API that implements the definition we've just edited. It should now have an error since we're not matching the definition at the moment. Add the following route to it
+//...other functions in todosApi
+download =
+ fun () -> async {
+ let byteArray = System.IO.File.ReadAllBytes("file.txt")
+ return byteArray
+ }
+++Make sure to replace "file.txt" with your file that is placed in
+src/Serveror relative path
Since the download function is asynchronous, we can't just call it anywhere in our view. The way we're going to deal with this is to create a Msg case and handle it in our update funciton.
type Msg =
+ //...other cases
+ | DownloadFile
+ | FileDownloaded of byte[]
+let update (msg: Msg) (model: Model): Model * Cmd<Msg> =
+ match msg with
+ //...other cases
+ | DownloadFile -> model, Cmd.OfAsync.perform todosApi.download () FileDownloaded
+ | FileDownloaded file ->
+ file.SaveFileAs("downloaded-file.txt")
+ model, Cmd.none // You can do something else here
+++The
+SaveFileAsfunction detects the mime-type/content-type automatically based on the file extension of the file input
Html.button [
+ prop.onClick (fun _ -> dispatch DownloadFile)
+ prop.text "Click to download"
+]
+Having added this last snippet of code into the view function, you will be able to download the file by clicking the button that will now be displayed in your UI. For more information visit the Fable.Remoting documentation
SAFE Stack makes it easy to catch and handle exceptions raised by the server on the client.
+Update the model to store the error details that we receive from the server. Find the Model type in src/Client/Index.fs and add it the following Errors field:
type Model =
+ { ... // the rest of the fields
+ Errors: string list }
+Now, bind an empty list to the field record inside the init function:
let model =
+ { ... // the rest of the fields
+ Errors = [] }
+We now add a new message to handle errors that we get back from the server after making a request. Add the following case to the Msg type:
type Msg =
+ | ... // other message cases
+ | GotError of exn
+In this simple example, we will simply capture the Message of the exception. Add the following line to the end of the pattern match inside the update function:
| GotError ex ->
+ { model with Errors = ex.Message :: model.Errors }, Cmd.none
+We now have to connect up the server response to the new message we created. Elmish has support for this through the either Cmd functions (instead of the perform functions). Make the following changes to your server call:
let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+…and replace it with the following:
+let cmd = Cmd.OfAsync.either todosApi.addTodo todo AddedTodo GotError
+Now, if you get an exception from the Server, its message will be added to the Errors field of the Model type. Instead of throwing the error, you can now display a meaningful text to the user like so:
In the function todoAction in src/Client/Index.fs add the following:
Html.button [
+//other button properties
+]
+for msg in model.Errors do
+ Html.p msg
+In the todosApi in src/Server/Server.fs replace the addTodo with the following:
addTodo =
+ fun todo -> async {
+ failwith "Something went wrong"
+ return
+ match Storage.addTodo todo with
+ | Ok() -> todo
+ | Error e -> failwith e
+ }
+and when you try to add a todo then you will see the error message from the server.
+ + + + + + + + +SAFE Stack makes it really simple and easy to share code between the client and the server, since both of them are written in F#. The client side is transpiled into JavaScript by Fable, whilst the server side is compiled down to .NET CIL. Serialization between both happens in the background, so you don't have to worry about it.
+Let's say the you have the following type in src/Server/Server.fs:
+
type Customer =
+ { Id : Guid
+ Name : string
+ Email : string
+ PhoneNumber : string }
+And you have the following function that is used to validate this Customer type in src/Client/Index.fs:
+
let customerIsValid customer =
+ (Guid.Empty = customer.Id
+ || String.IsNullOrEmpty customer.Name
+ || String.IsNullOrEmpty customer.Email
+ || String.IsNullOrEmpty customer.PhoneNumber)
+ |> not
+If at any point you realise you need to use both the Customer type and the customerIsValid function both in the Client and the Server, all you need to do is to move both of them to Shared project. You can either put them in the Shared.fs file, or create your own file in the Shared project (eg. Customer.fs). After this, you will be able to use both the Customer type and the customerIsValid function in both the Client and the Server.
SAFE comes out of the box with [Fable.Remoting] or [Thoth] for serialization. These will handle transport of data seamlessly for you.
+++ + + + + + + + +Be careful not to place code in
+Shared.fsthat depends on a Client or Server-specific dependency. If your code depends onFablefor example, in most cases it will not be suitable to place it in Shared, since it can only be used in Client. Similarly, if your types rely on .NET specific types in e.g. the framework class library (FCL), beware. Fable has built-in mappings for popular .NET types e.g.System.DateTimeandSystem.Math, but you will have to write your own mappers otherwise.
Fable makes it quick and easy to upload files from the client.
+Create a file in the client project named FileUpload.fs somewhere before the Index.fs file and insert the following:
module FileUpload
+
+open Feliz
+open Fable.Core.JsInterop
+Then, add the following. The reader.onload block will be executed once we select and confirm a file to be uploaded. Read the FileReader docs to find out more.
let handleFileEvent onLoad (fileEvent:Browser.Types.Event) =
+ let files:Browser.Types.FileList = !!fileEvent.target?files
+ if files.length > 0 then
+ let reader = Browser.Dom.FileReader.Create()
+ reader.onload <- (fun _ -> reader.result |> unbox |> onLoad)
+ reader.readAsArrayBuffer(files.[0])
+Insert the following block of code at the end of FileUpload.fs. This function will create a UI element to be used to upload files.
let createFileUpload onLoad =
+ Html.input [
+ prop.type' "file"
+ prop.label "Choose a file"
+ prop.onChange (handleFileEvent onLoad)
+ ]
+Having followed all these steps, you can now use the createFileUpload function in Index.fs to create the UI element for uploading files.
FileUpload.createFileUpload (HandleFile >> dispatch)
+One thing to note is that HandleFile is a case of the discriminated union type Msg that's in Index.fs.
type Msg =
+ // other messages
+ | HandleFile of Browser.Types.Event
+
+let update msg model =
+ match msg with
+ //other messages
+ | HandleFile event ->
+ // do what you need with the file
+There are many ways to supply configuration settings e.g. connection strings to your application, and the official ASP .NET documentation explains in great detail the various options you have available.
+In this recipe, we show how to add configuration using an appsettings.json configuration file.
++Never store secrets in plain text files such as
+appsettings.json- our recommendation is to use it for non-secret configuration data that is shared across your development team; see here for more guidance.
appsettings.json. It does not need to be added to the project file.{
+ "MyKey": "My appsettings.json Value"
+}
+Server.fs, ensure that your API builder functions take in an HTTPContext as an argument and change the construction of your Fable Remoting endpoint to supply one:
+++open Microsoft.AspNetCore.Http
+
+--let todosApi = {
+++let todosApi (context: HttpContext) = {
+
+...
+
+-- |> Remoting.fromValue todosApi
+++ |> Remoting.fromContext todosApi
+context to get a handle to the IConfiguration object, which allows you to access settings regardless of what infrastructure you are using to store them e.g. appsettings.json, environment variables etc.
+++open Giraffe
+++open Microsoft.Extensions.Configuration
+
+let todosApi (context: HttpContext) =
+++ let cfg = context.GetService<IConfiguration>()
+++ let value = cfg["MyKey"] // "My appsettings.json Value"
+++Note that the
+todosApifunction will be called on every single ASP .NET request. It is safe to "capture" thecfgvalue and use it across multiple API methods.
User Secrets are an alternative way of storing secrets which, although still stored in plain text files, are not stored in your repository folder and therefore less at risk to accidentally committing into source control. However, Saturn currently disables User Secrets as part of its startup routine, and you must manually turn them back on:
+++type DummyType() = class end
+
+let app = application {
+++ host_config (fun hostBuilder ->
+++ hostBuilder.ConfigureAppConfiguration(fun _ configBuilder ->
+++ configBuilder.AddUserSecrets<DummyType>()
+++ |> ignore
+++ )
+++ )
+}
+You can then access the IConfiguration as before, and user secrets values will be accessible.
Configuration of the client can be done in many ways, but generally a simple strategy is to have an API endpoint which is called on startup that provides any settings required by the client.
+ + + + + + + + +In order to debug Server code from Visual Studio, we need set the correct URLs in the project's debug properties.
+You can do this through the Server project's Properties/Debug editor or by editing the launchSettings.json file in src/Server/Properties
After selecting the debug profile that you wish to edit (IIS Express or Server), you will need to set the App URL field to http://localhost:5000 and Launch browser field to http://localhost:8080. The process is very similar for VS Mac.
Once this is done, you can expect your launchSettings.json file to look something like this:
+
{
+ "iisSettings": {
+ "windowsAuthentication": false,
+ "anonymousAuthentication": true,
+ "iisExpress": {
+ "applicationUrl": "http://localhost:5000/",
+ "sslPort": 44330
+ }
+ },
+ "profiles": {
+ "IIS Express": {
+ "commandName": "IISExpress",
+ "launchBrowser": true,
+ "launchUrl": "http://localhost:8080/",
+ "environmentVariables": {
+ "ASPNETCORE_ENVIRONMENT": "Development"
+ }
+ },
+ "Server": {
+ "commandName": "Project",
+ "launchBrowser": true,
+ "launchUrl": "http://localhost:8080",
+ "environmentVariables": {
+ "ASPNETCORE_ENVIRONMENT": "Development"
+ },
+ "applicationUrl": "http://localhost:5000"
+ }
+ }
+}
+Since you will be running the server directly through Visual Studio, you cannot use a FAKE script to start the application. Launch the Client directly by running the following command in src/Client
dotnet fable watch -o output -s --run npx vite
+Set the server as your Startup project, either using the drop-down menu at the top of the IDE or by right clicking on the project itself and selecting Set as Startup Project. Select the profile that you set up earlier and wish to launch from the drop-down at the top of the IDE. Either press the Play button at the top of the IDE or hit F5 on your keyboard to start the Server debugging and launch a browser pointing at the website.
+Although we write our client-side code using F#, it is being converted into JavaScript at runtime by Fable and executed in the browser. +However, we can still debug it via the magic of source mapping. If you are using Visual Studio, you cannot directly connect to the browser debugger. You can, however, debug your client F# code using the browser's development tools.
+The exact instructions will depend on your browser, but essentially it simply involves:
+VS Code allows "full stack" debugging i.e. both the client and server. Prerequisites that you should install:
+ctrl+shift+d to open the debug pane.Run and Debug buttonThe server is now running. You can use the bar at the top of your screen to pause, restart or kill the debugger
+dotnet fable watch -o output -s --run npx vite from <repo root>/src/Client/. ctrl+shift+p and run Debug: Open Link. http://localhost:8080/. This will launch a browser which is pointed at the URL and connect the debugger to it. ++ + + + + + + + +If you find that your breakpoints aren't being hit, try stopping the Client, disconnecting the debugger and re-launching them both.
+To find out more about the VS Code debugger, see here.
+
Testing on the client is a little different than on the server.
+This is because the code which is ultimately being executed in the browser is JavaScript, translated from F# by Fable, and so it must be tested in a JavaScript environment.
+Furthermore, code that is shared between the Client and Server must be tested in both a dotnet environment and a JavaScript environment.
+The SAFE template uses a library called Fable.Mocha which allows us to run the same tests in both environments. It mirrors the Expecto API and works in much the same way.
+If you are using the standard template then there is nothing more you need to do in order to start testing your Client.
+In the tests/Client folder, there is a project named Client.Tests with a single script demonstrating how to use Mocha to test the TODO sample.
++Note the compiler directive here which makes sure that the Shared tests are only included when executing in a JavaScript (Fable) context. They are covered by Expecto under dotnet as you can see in
+Server.Tests.fs.
In order to run the tests, instead of starting your application using +
dotnet run
+dotnet run Runtests
+Once the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
++This command builds and runs the Server test project too. If you want to run the Client tests alone, you can simply launch the test server using
+npm run test:live, which executes a command stored inpackage.json.
If you are using the minimal template, you will need to first configure a test project as none are included.
+Create a .Net library called Client.Tests in the tests/Client subdirectory using the following commands:
dotnet new classlib -lang F# -n Client.Tests -o tests/Client
+dotnet sln add tests/Client
+Reference the Client project from the Client.Tests project:
+dotnet add tests/Client reference src/Client
+Run the following command:
+dotnet add tests/Client package Fable.Mocha
+Add this function to Client.fs in the Client project
+let sayHello name = $"Hello {name}"
+Replace the contents of tests/Client/Library.fs with the following code:
module Tests
+
+open Fable.Mocha
+
+let client = testList "Client" [
+ testCase "Hello received" <| fun _ ->
+ let hello = Client.sayHello "SAFE V3"
+
+ Expect.equal hello "Hello SAFE V3" "Unexpected greeting"
+]
+
+let all =
+ testList "All"
+ [
+ client
+ ]
+
+[<EntryPoint>]
+let main _ = Mocha.runTests all
+Add a file called index.html to the tests/Client folder with following contents:
+
<!DOCTYPE html>
+<html>
+ <head>
+ <title>SAFE Client Tests</title>
+ </head>
+ <body>
+ <script type="module" src="/output/Library.js"></script>
+ </body>
+</html>
+Add a file called vite.config.mts to tests/Client:
import { defineConfig } from "vite";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+ server: {
+ port: 8081
+ }
+});
+npm install
+cd tests/Client
+dotnet fable watch -o output --run npx vite
+Once the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
Testing your Server code in a SAFE app is just the same as in any other dotnet app, and you can use the same tools and frameworks that you are familiar with. These include all of the usual suspects such as NUnit, XUnit, FSUnit, Expecto, FSCheck, AutoFixture etc.
+In this guide we will look at using Expecto, as this is included with the standard SAFE template.
+If you are using the standard template, then there is nothing more you need to do in order to start testing your Server code.
+In the tests/Server folder, there is a project named Server.Tests with a single script demonstrating how to use Expecto to test the TODO sample.
In order to run the tests, instead of starting your application using +
dotnet run
+you should instead use +
dotnet run RunTests
+
++This method builds and runs the Client test project too, which can be slow. If you want to run the Server tests alone, you can simply navigate to the tests/Server directory and run the project using
+dotnet run.
If you would like to use dotnet tests from the command line or the test runner that comes with Visual Studio, there are a couple of extra steps to follow.
+Run the following commands at the root of your solution: +
dotnet paket add Microsoft.NET.Test.Sdk -p Server.Tests
+dotnet paket add YoloDev.Expecto.TestSdk -p Server.Tests
+Open your ServerTests.fsproj file and add the following element:
+<PropertyGroup>
+ <GenerateProgramFile>false</GenerateProgramFile>
+</PropertyGroup>
+To allow your tests to be discovered, you will need to decorate them with a [<Tests>] attribute.
The provided test would look like this: +
[<Tests>]
+let server = testList "Server" [
+ testCase "Adding valid Todo" <| fun _ ->
+ let storage = Storage()
+ let validTodo = Todo.create "TODO"
+ let expectedResult = Ok ()
+
+ let result = storage.AddTodo validTodo
+
+ Expect.equal result expectedResult "Result should be ok"
+ Expect.contains (storage.GetTodos()) validTodo "Storage should contain new todo"
+]
+There are now two ways to run these tests.
+From the command line, you can just run +
dotnet test tests/Server
+Alternatively, if you are using Visual Studio or VS Mac you can make use of the built-in test explorers.
+
If you are using the minimal template, you will need to first configure a test project as none are included.
+Create a .Net console project called Server.Tests in the tests/Server folder.
dotnet new console -lang F# -n Server.Tests -o tests/Server
+dotnet sln add tests/Server
+Reference the Server project from the Server.Tests project:
+dotnet add tests/Server reference src/Server
+Run the following command:
+dotnet add tests/Server package Expecto
+Update the Server.fs file in the Server project to extract the message logic from the router like so: +
let getMessage () = "Hello from SAFE!"
+
+let webApp =
+ router {
+ get Route.hello (getMessage () |> json )
+ }
+Replace the contents of tests/Server/Program.fs with the following:
open Expecto
+
+let server = testList "Server" [
+ testCase "Message returned correctly" <| fun _ ->
+ let expectedResult = "Hello from SAFE!"
+ let result = Server.getMessage()
+ Expect.equal result expectedResult "Result should be ok"
+]
+
+[<EntryPoint>]
+let main _ = runTestsWithCLIArgs [] [||] server
+dotnet run -p tests/Server
+This will print out the results in the console window
+
Add the libraries Microsoft.NET.Test.Sdk and YoloDev.Expecto.TestSdk to your Test project, using NuGet.
++The way you do this will depend on whether you are using NuGet directly or via Paket. See this recipe for more details.
+
You can now add [<Test>] attributes to your tests so that they can be discovered, and then run them using the dotnet tooling in the same way as explained earlier for the standard template.
Sometimes you need to use a JS library directly, instead of using it through a wrapper library that makes it easy to use from F# code. In this case you need to import a module from the library. +Here are the most common import patterns used in JS.
+In most cases components use the default export syntax which is when the the component being exported from the module becomes available. For example, if the module being imported below looked something like: +
// module-name
+const foo = () => "hello"
+
+export default foo
+foo.
+import foo from 'module-name' // JS
+let foo = importDefault "module-name" // F#
+To ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element. +
Browser.Dom.console.log("imported value", foo)
+An example of this in use is how React is imported +
import React from "react"
+
+// Although in the newer versions of React this is uneeded
+In some cases components can use the named export syntax. In the below case "module-name" has an object/function/class that is called bar. By referncing it below it is brought into the current scope.
+For example, if the module below contained something like:
+
export const bar (x,y) => x + y
+import { bar } from "module-name" // JS
+let bar = import "bar" "module-name" // F#
+To ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element. +
Browser.Dom.console.log("imported value", bar)
+An example of this is how React hooks are imported +
import { useState } from "react"
+In rare cases you may have to import an entire module's contents and provide an alias in the below case we named it myModule. You can now use dot notation to access anything that is exported from module-name. For example, if the module being imported below includes an export to a function doAllTheAmazingThings() you could access it like:
+
myModule.doAllTheAmazingThings()
+import * as myModule from 'module-name' // JS
+let myModule = importAll "module-name" // F#
+To ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element. +
Browser.Dom.console.log("imported value", myModule)
+An example of this is another way to import React +
import * as React from "react"
+
+// Uncommon since importDefault is the standard
+See the Fable docs for more ways to import modules and use JavaScript from Fable.
+ + + + + + + + +To use a third-party React library in a SAFE application, you need to write an F# wrapper around it. There are two ways for doing this - using Feliz or using Fable.React.
+This recipe uses the react-d3-speedometer NPM package for demonstration purposes. Add it to your Client before continuing.
+If you don't already have Feliz installed, add it to your client.
+In the Client projects Index.fs add the following snippets
open Fable.Core.JsInterop
+Within the view function
+Feliz.Interop.reactApi.createElement (importDefault "react-d3-speedometer", createObj [
+ "minValue" ==> 0
+ "maxValue" ==> 100
+ "value" ==> 10
+])
+createElement from Feliz.ReactApi.IReactApi takes the component you're wrapping react-d3-speedometer, the props that component takes and creates a ReactComponent we can use in F#.importDefault from Fable.Core.JsInterop is giving us access to the component and is equivalent to import ReactSpeedometer from "react-d3-speedometer"
+The reason for using importDefault is the documentation for the component uses a default export "ReactSpeedometer". Please find a list of common import statetments at the end of this recipe
As a quick check to ensure that the library is being imported and we have no typos you can console.log the following at the top within the view function
Browser.Dom.console.log("REACT-D3-IMPORT", importDefault "react-d3-speedometer")
+In the console window (which can be reached by right-clicking and selecting Insepct Element) you should see some output from the above log. +If nothing is being seen you may need a slightly different import statement, please refer to this recipe.
+createObj from Fable.Core.JsInterop takes a sequence of string * obj which is a prop name and value for the component, you can find the full prop list for react-d3-speedometer here.==> (short hand for prop.custom) to transform the sequence into a JavaScript object createObj [
+ "minValue" ==> 0
+ "maxValue" ==> 10
+]
+Is equivalent to
+{ minValue: 0, maxValue: 10 }
+That's the bare minimum needed to get going!
+Once your component is working you may want to extract out the logic so that it can be used in multiple pages of your app. +For a full detailed tutorial head over to this blog post!
+Create an empty file named ReactSpeedometer.fs in the Client project above Index.fs and insert the following statements at the beginning of the file.
module ReactSpeedometer
+
+open Fable.Core
+open Fable.Core.JsInterop
+open Fable.React
+Prop represents the props of the React component. In this recipe, we're using the props listed here for react-d3-speedometer. We model them in Fable.React using a discriminated union.
type Prop =
+ | Value of int
+ | MinValue of int
+ | MaxValue of int
+ | StartColor of string
+++One difference to note is that we use PascalCase rather than camelCase.
+Note that we can model any props here, both simple values and "event handler"-style ones.
+
Add the following function to the file. Note that the last argument passed into the ofImport function is a list of ReactElements to be used as children of the react component. In this case, we are passing an empty list since the component doesn't have children.
let reactSpeedometer (props : Prop list) : ReactElement =
+ let propsObject = keyValueList CaseRules.LowerFirst props // converts Props to JS object
+ ofImport "default" "react-d3-speedometer" propsObject [] // import the default function/object from react-d3-speedometer
+With all these in place, you can use the React element in your client like so:
+open ReactSpeedometer
+
+reactSpeedometer [
+ Prop.Value 10 // Since Value is already decalred in HTMLAttr you can use Prop.Value to tell the F# compiler its of type Prop and not HTMLAttr
+ MaxValue 100
+ MinValue 0
+ StartColor "red"
+ ]
+When you want to call a JavaScript library from your Client, it is easy to import and reference it using NPM.
+Run the following command: +
npm install name-of-package
+This will download the package into the solution's node_modules folder.
+You will also see a reference to the package in the Client's package.json file: +
"dependencies": {
+ "name-of-package": "^1.0.0"
+}
+Adding packages to the Client project is a very similar process to the Server, with a few key differences:
+Any references to the Server directory should be Client
Client code written in F# is converted into JavaScript using Fable. Because of this, we must be careful to only reference libraries which are Fable compatible.
+If the NuGet package uses any JS libraries you must install them.
+ For simplicity, use Femto to sync - if the NuGet package is compatible - or install via NPM manually, if not.
There are lots of great libraries available to choose from.
+ + + + + + + + +You can add NuGet packages to the server to give it more capabilities. You can download a wide variety of packages from the official NuGet site.
+In this example we will add the FsToolkit ErrorHandling package package.
+Navigate to the root directory of your solution and run:
+dotnet paket add FsToolkit.ErrorHandling -p Server
+This will add an entry to both the solution paket.dependencies file and the Server project's paket.reference file, as well as update the lock file with the updated dependency graph.
+++ + + + + + + + +For a detailed explanation of package management using Paket, visit the official docs.
+
++Note that the minimal template uses NuGet by default. This recipe only applies to the full template.
+
Paket is a fully featured package manager that acts as an alternative to the NuGet package manager commonly used in .NET.
+It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
+For most use cases, we would recommend sticking with Paket. If, however, you are in a position where you wish to remove it and revert back to the NuGet package manager, you can easily do so with the following steps.
+In every project's .fsproj file you will find the following line. Remove it and save.
<Import Project="..\..\.paket\Paket.Restore.targets" />
+You will find this file at the root of your solution. Remove it from your solution if included and then delete it.
+Each project directory will contain a paket.references file. This lists all the NuGet packages that the project requires.
Inside a new ItemGroup in the project's .fsproj file you will need to add an entry for each of these packages.
<ItemGroup>
+ <PackageReference Include="Azure.Core" Version="1.24" />
+ <PackageReference Include="AnotherPackage" Version="2.0.1" />
+ <!--...add entry for each package in the references file...-->
+</ItemGroup>
+++You can find the version of each package in the
+paket.lockfile at the root of the solution. The version number is contained in brackets next to the name of the package at the first level of indentation. For example, in this case Azure.Core is version 1.24:
Azure.Core (1.24)
+ Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)
+ System.Diagnostics.DiagnosticSource (>= 4.6)
+ System.Memory.Data (>= 1.0.2)
+ System.Numerics.Vectors (>= 4.5)
+ System.Text.Encodings.Web (>= 4.7.2)
+ System.Text.Json (>= 4.7.2)
+ System.Threading.Tasks.Extensions (>= 4.5.4)
+Once you have added all of your dependencies to the relevant .fsproj files, you can remove the folowing files and folders from your solution.
Files:
+* paket.lock
+* paket.dependencies
+* all of the paket.references files
Folders:
+* .paket
+* paket-files
If you open .config/dotnet-tools.json you will find an entry for paket. Remove it.
Alternatively, run
+dotnet tool uninstall paket
+Paket is a fully featured package manager that acts as an alternative to the NuGet package manager.
+It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
+++Note that the standard template uses Paket by default. This recipe only applies to the minimal template.
+
dotnet tool install paket
+dotnet tool restore
+Run this command to move existing NuGet references to Paket from your packages.config or .fsproj file: +
dotnet paket convert-from-nuget
+This will add three files to your solution, all of which should be committed to source control:
+For a more detailed explanation of this process see the official migration guide.
+++ + + + + + + + +In the case where you have added a NuGet project to a solution which is already using paket, run this command with the option
+--force.If you are working in Visual Studio and wish to see your Paket files in the Solution Explorer, you will need to add both the paket.lock and any paket.references files created in your project directories during the last step to your solution.
+
SAFE Stack uses Fable bindings, which are NuGet packages that provide idiomatic and type-safe wrappers around native JavaScript APIs. These bindings often rely on third-party JavaScript libraries distributed via the NPM registry. This leads to the problem of keeping both the NPM package in sync with its corresponding NuGet F# wrapper. Femto is a dotnet CLI tool that solves this issue.
+++For in-depth information about Femto, see Introducing Femto.
+
Navigate to the root folder of the solution and execute the following command: +
dotnet tool install femto
+In the root directory, run the following: +
dotnet femto ./src/Client
+alternatively, you can call femto directly from ./src/Client:
cd ./src/Client
+dotnet femto
+This will give you a report of discrepancies between the NuGet packages and the NPM packages for the project, as well as steps to take in order to resolve them.
+To sync your NPM dependencies with your NuGet dependencies, you can either manually follow the steps returned by step 2, or resolve them automatically using the following command: +
dotnet femto ./src/Client --resolve
+Keeping your NPM dependencies in sync with your NuGet packages is now as easy as repeating step 3. Of course, you can instead repeat the step 2 and resolve packages manually, too.
+ + + + + + + + +++This recipe is not a detailed discussion of the pros and cons of Dependency Injection (DI) compared to other patterns. It simply illustrates how to use it within a SAFE Stack application!
+
Create a class that you wish to inject with a dependency (in this example, we use the built-in IConfiguration type that is included in ASP .NET):
open Microsoft.Extensions.Configuration
+
+type DatabaseRepository(config:IConfiguration) =
+ member _.SaveDataToDb (text:string) =
+ let connectionString = config["SqlConnectionString"]
+ // Connect to SQL using the above connection string etc.
+ Ok 1
+++Instead of functions or modules, DI in .NET and F# only works with classes.
+
Register your type with ASP .NET during startup within the application { } block.
+
++ open Microsoft.Extensions.DependencyInjection
+
+ application {
+ //...
+++ service_config (fun services -> services.AddSingleton<DatabaseRepository>())
+++This section of the official ASP .NET Core article explain the distinction between different lifetime registrations, such as Singleton and Transient.
+
Ensure that your Fable Remoting API can access the HttpContext type by using the fromContext builder function.
+
-- |> Remoting.fromValue createFableRemotingApi
+++ |> Remoting.fromContext createFableRemotingApi
+Within your Fable Remoting API, use the supplied context to retrieve your dependency:
++ open Microsoft.AspNetCore.Http
+
+ let createFableRemotingApi
+++ (context:HttpContext) =
+++ let dbRepository = context.GetService<DatabaseRepository>()
+ // ...
+ // Return the constructed API record value...
+++Giraffe provides the
+GetService<'T>extension to allow you to quickly retrieve a dependency from theHttpContext.
This will instruct ASP .NET to get a handle to the DatabaseRepository object; ASP .NET will automatically supply the IConfiguration object to the constructor. Whether a new DatabaseRepository object is constructed on each call depends on the lifetime you have registered it with.
++You can have your types depend on other types that you create, as long as they are registering into ASP .NET Core's DI container using methods such as
+AddSingletonetc.
The default template uses in-memory storage. This recipe will show you how to replace the in-memory storage with LiteDB in the form of LiteDB.FSharp.
+Add the LiteDB.FSharp NuGet package to the server project.
+Replace the use of the ResizeArray in the Storage type with a database and collection:
open LiteDB.FSharp
+open LiteDB
+
+type Storage () =
+ let database =
+ let mapper = FSharpBsonMapper()
+ let connStr = "Filename=Todo.db;mode=Exclusive"
+ new LiteDatabase (connStr, mapper)
+ let todos = database.GetCollection<Todo> "todos"
+++LiteDb is a file-based database, and will create the file if it does not exist automatically.
+
This will create a database file Todo.db in the Server folder. The option mode=Exclusive is added for MacOS support (see this issue).
++See here for more information on connection string arguments.
+See the official docs for details on constructor arguments.
+
Replace the implementations of GetTodos and AddTodo as follows:
/// Retrieves all todo items.
+ member _.GetTodos () =
+ todos.FindAll () |> List.ofSeq
+
+ /// Tries to add a todo item to the collection.
+ member _.AddTodo (todo:Todo) =
+ if Todo.isValid todo.Description then
+ todos.Insert todo |> ignore
+ Ok ()
+ else
+ Error "Invalid todo"
+Modify the existing "priming" so that it first checks if there are any records in the database before inserting data:
+if storage.GetTodos() |> Seq.isEmpty then
+ storage.AddTodo(Todo.create "Create new SAFE project") |> ignore
+ storage.AddTodo(Todo.create "Write your app") |> ignore
+ storage.AddTodo(Todo.create "Ship it !!!") |> ignore
+Add the CLIMutable attribute to the Todo record in Shared.fs
[<CLIMutable>]
+type Todo =
+ { Id : Guid
+ Description : string }
+++This is required to allow LiteDB to hydrate (read) data into F# records.
+
The easiest way to get a database running locally is using Docker. You can find the installer on their website. Once docker is installed, use the following command to spin up a database server
+docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<your password>" -p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest
+1) In the "Connections" tab, click the "New Connection" button
+
2) Enter your connection details, leaving the "Database" dropdown set to <Default>.
USE master
+GO
+IF NOT EXISTS (
+ SELECT name
+ FROM sys.databases
+ WHERE name = N'SafeTodo'
+)
+ CREATE DATABASE [SafeTodo];
+GO
+IF SERVERPROPERTY('ProductVersion') > '12'
+ ALTER DATABASE [SafeTodo] SET QUERY_STORE=ON;
+GO
+NOTE: Alternatively, if you don't want to manually create the new database, you can install the "New Database" extension in Azure Data Studio which gives you a "New Database" option when right clicking the "Databases" folder.
+CREATE TABLE [dbo].[Todos]
+(
+ [Id] UNIQUEIDENTIFIER NOT NULL PRIMARY KEY,
+ [Description] NVARCHAR(500) NOT NULL,
+ [IsDone] BIT NOT NULL
+)
+At this point, you should have a SAFE Stack solution and a minimal "SafeTodo" SQL Server database with a "Todos" table. +Next, we will use Azure Data Studio with the "SQL Database Projects" extension to create a new SSDT (SQL Server Data Tools) .sqlproj that will live in our SAFE Stack .sln.
+1) Install the "SQL Database Projects" extension.
+2) Right click the SafeTodo database and choose "Create Project From Database" (this option is added by the "SQL Database Projects" extension)
+
3) Configure a path within your SAFE Stack solution folder and a project name and then click "Create". NOTE: If you choose to create an "ssdt" subfolder as I did, you will need to manually create this subfolder first.
+
4) You should now be able to view your SQL Project by clicking the "Projects" tab in Azure Data Studio.
+
5) Finally, right click the SafeTodoDB project and select "Build". This will create a .dacpac file which we will use in the next step.
+Install dependencies SqlProvider and Microsoft.Data.SqlClient
dotnet paket add SqlProvider -p Server
+dotnet paket add Microsoft.Data.SqlClient -p Server
+Next, we will wire up our type provider to generate database types based on the compiled .dacpac file.
+1) In the Server project, create a new file, Database.fs. (this should be above Server.fs).
module Database
+open FSharp.Data.Sql
+
+[<Literal>]
+let SsdtPath = __SOURCE_DIRECTORY__ + @"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac"
+
+type DB =
+ SqlDataProvider<
+ Common.DatabaseProviderTypes.MSSQLSERVER_SSDT,
+ SsdtPath = SsdtPath,
+ UseOptionTypes = Common.NullableColumnType.OPTION
+ >
+
+//TO RELOAD SCHEMA: 1) uncomment the line below; 2) save; 3) recomment; 4) save again and wait.
+//DB.GetDataContext().``Design Time Commands``.ClearDatabaseSchemaCache
+
+let createContext (connectionString: string) =
+ DB.GetDataContext(connectionString)
+2) Create TodoRepository.fs below Database.fs.
module TodoRepository
+open FSharp.Data.Sql
+open Database
+open Shared
+
+/// Get all todos that have not been marked as "done".
+let getTodos (db: DB.dataContext) =
+ query {
+ for todo in db.Dbo.Todos do
+ where (not todo.IsDone)
+ select
+ { Shared.Todo.Id = todo.Id
+ Shared.Todo.Description = todo.Description }
+ }
+ |> List.executeQueryAsync
+
+let addTodo (db: DB.dataContext) (todo: Shared.Todo) =
+ async {
+ let t = db.Dbo.Todos.Create()
+ t.Id <- todo.Id
+ t.Description <- todo.Description
+ t.IsDone <- false
+
+ do! db.SubmitUpdatesAsync() |> Async.AwaitTask
+ }
+3) Create TodoController.fs below TodoRepository.fs.
module TodoController
+open Database
+open Shared
+
+let getTodos (db: DB.dataContext) =
+ TodoRepository.getTodos db |> Async.AwaitTask
+
+let addTodo (db: DB.dataContext) (todo: Todo) =
+ async {
+ if Todo.isValid todo.Description then
+ do! TodoRepository.addTodo db todo
+ return todo
+ else
+ return failwith "Invalid todo"
+ }
+4) Finally, replace the stubbed todosApi implementation in Server.fs with our type provided implementation.
module Server
+
+open Fable.Remoting.Server
+open Fable.Remoting.Giraffe
+open Saturn
+open System
+open Shared
+open Microsoft.AspNetCore.Http
+
+let todosApi =
+ let db = Database.createContext @"Data Source=localhost,1433;Database=SafeTodo;User ID=sa;Password=<your password>;TrustServerCertificate=True"
+ { getTodos = fun () -> TodoController.getTodos db
+ addTodo = TodoController.addTodo db }
+
+let webApp =
+ Remoting.createApi()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.fromValue todosApi
+ |> Remoting.withErrorHandler fableRemotingErrorHandler
+ |> Remoting.buildHttpHandler
+
+let app =
+ application {
+ use_router webApp
+ memory_cache
+ use_static "public"
+ use_gzip
+ }
+
+run app
+From the VS Code terminal in the SafeTodo folder, launch the app (server and client):
+dotnet run
You should now be able to add todos.
+
When creating a Release build for deployment, it is important to note that SQLProvider SSDT expects that the .dacpac file will be copied to the deployed Server project bin folder.
+Here are the steps to accomplish this:
+1) Modify your Server.fsproj to include the .dacpac file with "CopyToOutputDirectory" to ensure that the .dacpac file will always exist in the Server project bin folder.
+<ItemGroup>
+ <None Include="..\{relative path to SSDT project}\ssdt\SafeTodo\bin\$(Configuration)\SafeTodoDB.dacpac" Link="SafeTodoDB.dacpac">
+ <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+ </None>
+
+ { other files... }
+</ItemGroup>
+2) In your Server.Database.fs file, you should also modify the SsdtPath binding so that it can build the project in either Debug or Release mode:
+[<Literal>]
+#if DEBUG
+let SsdtPath = __SOURCE_DIRECTORY__ + @"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac"
+#else
+let SsdtPath = __SOURCE_DIRECTORY__ + @"/../../ssdt/SafeTodoDB/bin/Release/SafeTodoDB.dacpac"
+#endif
+NOTE: This assumes that your SSDT .sqlproj will be built in Release mode (you can build it manually, or use a FAKE build script to handle this).
+ + + + + + + + +Follow the following pattern and headings and the guide below.
+Start by writing a short introduction of a few sentences. Explain what the recipe is about, and problems it solves. Which technologies does it utilise, and what are the alternatives etc.?
+Remember to link the first instance of any technology to the appropriate docs elsewhere within this site, or to the homepage of the technology (or both!).
+Write clear instructions on how to get to the desired outcome. The step-by-step instructions should be clear, short, easy to understand with possibly a use case and an example at the end if suitable.
+If you have a step in this section that is relevant to some other recipe we have here in the docs, such as adding a package to a SAFE app, link it to that relevant page.
+ + + + + + + + +Bulma is a free open-source UI framework based on flexbox that helps you create modern and responsive layouts.
+When using Feliz (the standard for a SAFE app), follow the instructions below. When using Fable.React, use the Fulma wrapper for Bulma.
+dotnet paket add Feliz.Bulma -p Client
+index.html ...
+ <head>
+ ...
++ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css">
+ </head>
+ ...
+open Feliz.Bulma
+
+Bulma.button.button [
+ str "Click me!"
+]
+DaisyUI is a component library for Tailwind CSS.
+To use the library from within F# we will use Feliz.DaisyUI (Github).
Open a terminal at ./src/Client
Add daisyUI JS dependencies using NPM: npm i -D daisyui@latest
Add Feliz.DaisyUI .NET dependency...
+dotnet paket add Feliz.DaisyUIdotnet add package Feliz.DaisyUIUpdate the tailwind.config.js file's module.exports.plugins array; add require("daisyui")
module.exports = {
+ content: [
+ '.index.html',
+ './**/*.fs',
+ ],
+ theme: {
+ extend: {},
+ },
+ plugins: [
+ require('daisyui'),
+ ],
+}
+Open the daisyUI namespace wherever you want to use it. +
open Feliz.DaisyUI
+Congratulations, now you can use daisyUI components!
+ Documentation can be found at https://dzoukr.github.io/Feliz.DaisyUI/
Feliz is a wrapper for the base React DSL library that emphasises consistency, lightweight formatting, discoverable attributes and full type-safety. The default SAFE Template already uses Feliz.
+dotnet paket add Feliz -p Client
+open Feliz
+
+Html.button [
+ prop.style [ style.marginLeft 5 ]
+ prop.onClick (fun _ -> setCount(count - 1))
+ prop.text "Decrement"
+]
+FontAwesome is the most popular icon set out there and will provide you with a handful of free icons as well as a multitude of premium icons. The standard SAFE template has out-of-the-box support for FontAwesome. You can just start using it in your Client code like so:
+open Feliz
+
+Html.i [ prop.className "fas fa-star" ]
+If you don't need the full features of Feliz we suggest using Fable.FontAwesome.Free.
Add Fable.FontAwesome.Free NuGet Package to the Client project.
++ ++
Open the index.html file and add the following line to the head element:
+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css">
+open Fable.FontAwesome
+
+Icon.icon [
+ Fa.i [ Fa.Solid.Star ] [ ]
+]
+Now you can use FontAwesome in your code
+ + + + + + + + +Written for SAFE template version 4.2.0
+If your application has multiple separate components, there is no need to have one big, complex model that manages all the state for all components. In this recipe we separate the information of the todo list out of the main Model, and give the todo list application its own route. We also add a "Page not found" page.
Install Feliz.Router in the client project
+dotnet paket add Feliz.Router -p Client
+To include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router
+Move the following functions and types to a new TodoList Module in a file TodoList.fs:
private access modifieralso open Shared, Fable.Remoting.Client, Elmish and Feliz
module TodoList
+
+open Shared
+open Fable.Remoting.Client
+open Elmish
+open Feliz
+
+type Model = { Todos: Todo list; Input: string }
+
+type Msg =
+ | GotTodos of Todo list
+ | SetInput of string
+ | AddTodo
+ | AddedTodo of Todo
+
+let todosApi =
+ Remoting.createApi ()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.buildProxy<ITodosApi>
+
+let init () =
+ let model = { Todos = []; Input = "" }
+ let cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos
+ model, cmd
+
+let update msg model =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+ | SetInput value -> { model with Input = value }, Cmd.none
+ | AddTodo ->
+ let todo = Todo.create model.Input
+
+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+
+ { model with Input = "" }, cmd
+ | AddedTodo todo ->
+ {
+ model with
+ Todos = model.Todos @ [ todo ]
+ },
+ Cmd.none
+
+let private todoAction model dispatch =
+ Html.div [
+ prop.className "flex flex-col sm:flex-row mt-4 gap-4"
+ prop.children [
+ Html.input [
+ prop.className
+ "shadow appearance-none border rounded w-full py-2 px-3 outline-none focus:ring-2 ring-teal-300 text-grey-darker"
+ prop.value model.Input
+ prop.placeholder "What needs to be done?"
+ prop.autoFocus true
+ prop.onChange (SetInput >> dispatch)
+ prop.onKeyPress (fun ev ->
+ if ev.key = "Enter" then
+ dispatch AddTodo)
+ ]
+ Html.button [
+ prop.className
+ "flex-no-shrink p-2 px-12 rounded bg-teal-600 outline-none focus:ring-2 ring-teal-300 font-bold text-white hover:bg-teal disabled:opacity-30 disabled:cursor-not-allowed"
+ prop.disabled (Todo.isValid model.Input |> not)
+ prop.onClick (fun _ -> dispatch AddTodo)
+ prop.text "Add"
+ ]
+ ]
+ ]
+
+let view model dispatch =
+ Html.div [
+ prop.className "bg-white/80 rounded-md shadow-md p-4 w-5/6 lg:w-3/4 lg:max-w-2xl"
+ prop.children [
+ Html.ol [
+ prop.className "list-decimal ml-6"
+ prop.children [
+ for todo in model.Todos do
+ Html.li [ prop.className "my-1"; prop.text todo.Description ]
+ ]
+ ]
+
+ todoAction model dispatch
+ ]
+ ]
+Create a new Model in the Index module, to keep track of the open page
type Page =
+ | TodoList of TodoList.Model
+ | NotFound
+
+type Model = { CurrentPage: Page }
+Add a Msg type with a case of TodoList.Msg
type Msg =
+ | TodoListMsg of TodoList.Msg
+Create an update function (we moved the original one to TodoList). Handle the TodoListMsg by updating the TodoList Model. Wrap the command returned by the update of the todo list in a TodoListMsg before returning it. We expand this function later with other cases that deal with navigation.
let update message model =
+ match model.CurrentPage, message with
+ | TodoList todoList, TodoListMsg todoListMessage ->
+ let newTodoListModel, todoCommand = TodoList.update todoListMessage todoList
+
+ let model = {
+ model with
+ CurrentPage = TodoList newTodoListModel
+ }
+
+ model, todoCommand |> Cmd.map TodoListMsg
+Create a function initFromUrl; initialize the TodoList app when given the URL of the todo list app. Also return the command that TodoList's init may return, wrapped in a TodoListMsg
let initFromUrl url =
+ match url with
+ | [ "todo" ] ->
+ let todoListModel, todoListMsg = TodoList.init ()
+ let model = { CurrentPage = TodoList todoListModel }
+
+ model, todoListMsg |> Cmd.map TodoListMsg
+Add a wildcard, so any URLs that are not registered display the "not found" page
+let initFromUrl url =
+ match url with
+ ...
+ | _ -> { CurrentPage = NotFound }, Cmd.none
+ let initFromUrl url =
+ match url with
+ ...
++ | _ -> { CurrentPage = NotFound }, Cmd.none
+Add an init function to Index; return the current page based on Router.currentUrl
let init () =
+ Router.currentUrl ()
+ |> initFromUrl
+Add an UrlChanged case of string list to the Msg type
type Msg =
+ ...
+ | UrlChanged of string list
+ type Msg =
+ ...
++ | UrlChanged of string list
+Handle the case in the update function by calling initFromUrl
let update message model =
+ ...
+ match model.CurrentPage, message with
+ | _, UrlChanged url -> initFromUrl url
+ let update message model =
+ ...
++ match model.CurrentPage, message with
++ | _, UrlChanged url -> initFromUrl url
+Complete the pattern match in the update function, adding a case with a wildcard for both message and model. Return the model, and no command
let update message model =
+ ...
+ | _, _ -> model, Cmd.none
+ let update message model =
+ ...
++ | _, _ -> model, Cmd.none
+Add a function pageContent to the Index module. If the CurrentPage is of TodoList, render the todo list using TodoList.view; in order to dispatch a TodoList.Msg, it needs to be wrapped in a TodoListMsg.
For the NotFound page, return a "Page not found" box
let pageContent model dispatch =
+ match model.CurrentPage with
+ | TodoList todoListModel -> TodoList.view todoListModel (TodoListMsg >> dispatch)
+ | NotFound -> Html.text "Page not found"
+In the view function, replace the call to todoList with a call to pageContent
let view model dispatch =
+ ...
+ pageContent model dispatch
+ ...
+ let view model dispatch =
+ ...
+- todoList model dispatch
++ pageContent model dispatch
+ ...
+Wrap the content of the view function in a router.children property of a React.router. Also add an onUrlChanged property, that dispatches the 'UrlChanged' message.
let view model dispatch =
+ React.router [
+ router.onUrlChanged (UrlChanged >> dispatch)
+ router.children [
+ Html.section [
+ ...
+ ]
+ ]
+ ]
+ let view model dispatch =
++ React.router [
++ router.onUrlChanged (UrlChanged >> dispatch)
++ router.children [
+ Html.section [
+ ...
+ ]
++ ]
++ ]
+The routing should work now. Try navigating to localhost:8080; you should see a page with "Page not Found". If you go to localhost:8080/#/todo, you should see the todo app.
+# sign
+You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. +There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
+When building larger apps, you probably want different pages to be accessible through different URLs. In this recipe, we show you how to add routes to different pages to an application, including adding a "page not found" page that is displayed when an unknown URL is entered.
+In this recipe we use the simplest approach to storing states for multiple pages, by creating a single state for the full app. A potential benefit of this approach is that the state of a page is not lost when navigating away from it. You will see how that works at the end of the recipe.
+Install Feliz.Router in the client project
+dotnet paket add Feliz.Router -p Client
+To include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router
+Add the current page to the model of the client, using a new Page type
type Page =
+ | TodoList
+ | NotFound
+
+type Model =
+ { CurrentPage: Page
+ Todos: Todo list
+ Input: string }
++ type Page =
++ | TodoList
++ | NotFound
++
+- type Model = { Todos: Todo list; Input: string }
++ type Model =
++ { CurrentPage: Page
++ Todos: Todo list
++ Input: string }
+Create a function to parse a URL to a page, including a wildcard for unmapped pages
+let parseUrl url =
+ match url with
+ | ["todo"] -> Page.TodoList
+ | _ -> Page.NotFound
+On initialization, set the current page
+let init () : Model * Cmd<Msg> =
+ let page = Router.currentUrl () |> parseUrl
+
+ let model =
+ { CurrentPage = page
+ Todos = []
+ Input = "" }
+ ...
+ model, cmd
+ let init () : Model * Cmd<Msg> =
++ let page = Router.currentUrl () |> parseUrl
++
+- let model = { Todos = []; Input = "" }
++ let model =
++ { CurrentPage = page
++ Todos = []
++ Input = "" }
+ ...
+ model, cmd
+Add an action to handle navigation.
+To the Msg type, add a PageChanged case of Page
type Msg =
+ ...
+ | PageChanged of Page
+ type Msg =
+ ...
++ | PageChanged of Page
+Add the PageChanged update action
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ ...
+ | PageChanged page -> { model with CurrentPage = page }, Cmd.none
+ let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ ...
++ | PageChanged page -> { model with CurrentPage = page }, Cmd.none
+Rename the view function to todoView
let todoView model dispatch =
+ Html.section [
+ ...
+ ]
+- let view model dispatch =
++ let todoView model dispatch =
+ Html.section [
+ ...
+ ]
+Add a new view function, that returns the appropriate page
+let view model dispatch =
+ match model.CurrentPage with
+ | TodoList -> todoView model dispatch
+ | NotFound ->
+ Html.div [
+ prop.className "flex flex-col items-center justify-center h-full"
+ prop.text "Page not found"
+ ]
+Adding UI elements to every page of the website
+In this recipe, we moved all the page content to the todoView, but you don't have to. You can add UI you want to display on every page of the application to the view function.
Add the React.Router element as the outermost element of the view. Dispatch the PageChanged event on onUrlChanged
let view (model: Model) (dispatch: Msg -> unit) =
+ React.router [
+ router.onUrlChanged (parseUrl >> PageChanged >> dispatch)
+ router.children [
+ match model.CurrentPage with
+ ...
+ ]
+ ]
+ let view (model: Model) (dispatch: Msg -> unit) =
++ React.router [
++ router.onUrlChanged (parseUrl >> PageChanged >> dispatch)
+ router.children [
+ match model.CurrentPage with
+ ...
+ ]
+ ]
+The routing should work now. Try navigating to localhost:8080; you should see a page with "Page not Found". If you go to localhost:8080/#/todo, you should see the todo app.
+To see how the state is maintained even when navigating away from the page, type something in the text box and move away from the page by entering another path in the address bar. Then go back to the todo page. The entered text is still there.
+# sign
+You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. +There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
+Now that you have set up the routing, adding more pages is simple: add a new case to the Page type; add a route for this page in the parseUrl function; add a function that takes a model and dispatcher to generate your new page, and add a new case to the pattern match inside the view function to display the new case.
The default way to add extra styles is to add them using Tailwind classes. +If you wish to use your own CSS stylesheets with SAFE apps, Vite can bundle them up for you.
+There are two different approaches to adding your own CSS file, depending on what files you have available.
+index.cssThe default template includes a stylesheet at src/Client/index.css which contains references to Tailwind.
+The cleanest way to add your own stylesheet is to create a new file e.g. src/Client/custom-style.css and then reference it from index.css.
src/Client, e.g. custom-style.cssindex.css
+ +@import "./custom-style.css";
+ @tailwind base;
+ @tailwind components;
+ @tailwind utilities;
+index.cssIn order for Vite to know that there are styles to be bundled, you must import them into your app. By default this is already configured for index.css but if you don't have it set up, not to worry! Follow these steps:
src/Client, e.g. custom-style.cssApp.fs:
+ open Fable.Core.JsInterop
+importSideEffects "./custom-style.css"
+You can now style your app by writing to the custom-style.css file.
Tailwind is a utility-first CSS framework which can be composed to build any design, directly in your markup.
+As of SAFE version 5 (released in December 2023) it is included in the template by default so it can be used straight away.
+If you are are using the minimal template or if you are upgrading from an old version of SAFE, continue reading for installation instructions.
+Add a stylesheet to the project
+Install the required npm packages +
npm install -D tailwindcss postcss autoprefixer
+tailwind.config.js
+ npx tailwindcss init
+Amend the tailwind.config.js as follows
+
/** @type {import('tailwindcss').Config} */
+module.exports = {
+ mode: "jit",
+ content: [
+ "./index.html",
+ "./**/*.{fs,js,ts,jsx,tsx}",
+ ],
+ theme: {
+ extend: {},
+ },
+ plugins: [],
+}
+Create a postcss.config.js with the following
+
module.exports = {
+ plugins: {
+ tailwindcss: {},
+ autoprefixer: {},
+ }
+}
+Add the Tailwind layers to your stylesheet +
@tailwind base;
+@tailwind components;
+@tailwind utilities;
+Start using tailwind classes e.g. +
for todo in model.Todos do
+ Html.li [
+ prop.classes [ "text-red-200" ]
+ prop.text todo.Description
+ ]
+Remove the CDN reference from the index template in src/Client/index.html:
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css">
+Add styles from NPM. How do I add an NPM package to the client? +In this example we will add the Bulma NPM package.
+// Set variables to affect Bulma styles
+$body-color: #c6538c;
+@import 'bulma/bulma.sass';
+By default, a full SAFE-stack application uses Tailwind CSS for styling. You might not always want to manage your styling using Tailwind, for example because you want to use a CSS framework like Bulma. In this recipe we describe how to fully remove Tailwind
+Tailwind uses classes to style UI elements. In src/Client, search for all occurrences of prop.className and prop.classes and remove them if they are used for Tailwind support. In a vanilla SAFE template installation, this means removing all occurrences of prop.className.
Remove NPM packages that were installed for Tailwind using
+ npm uninstall tailwindcss postcss autoprefixer
+Remove the following files:
+src/Client/postcss.config.js
+src/Client/tailwind.config.js
+src/Client/index.css
+Your SAFE Stack app is now Tailwind-free.
+ + + + + + + + +UseElmish is a powerful package that allows you to write standalone components using Elmish. A component built around the UseElmish hook has its own view, state and update function.
In this recipe we add routing to a safe app, and implement the todo list page using the UseElmish hook.
Install Feliz.Router in the Client project
+dotnet paket add Feliz.Router -p Client
+Install Feliz.UseElmish in the Client project
+cd src/Client
+dotnet femto install Feliz.UseElmish
+Open the router in the client project
+open Feliz.Router
+Create a new Module TodoList in the client project. Move the following functions and types to the TodoList Module:
Also open Shared, Fable.Remoting.Client, Elmish and Feliz.
module TodoList
+
+open Shared
+open Fable.Remoting.Client
+open Elmish
+
+open Feliz
+
+type Model = { Todos: Todo list; Input: string }
+
+type Msg =
+ | GotTodos of Todo list
+ | SetInput of string
+ | AddTodo
+ | AddedTodo of Todo
+
+let todosApi =
+ Remoting.createApi ()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.buildProxy<ITodosApi>
+
+let init () =
+ let model = { Todos = []; Input = "" }
+ let cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos
+ model, cmd
+
+let update msg model =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+ | SetInput value -> { model with Input = value }, Cmd.none
+ | AddTodo ->
+ let todo = Todo.create model.Input
+
+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+
+ { model with Input = "" }, cmd
+ | AddedTodo todo ->
+ {
+ model with
+ Todos = model.Todos @ [ todo ]
+ },
+ Cmd.none
+
+let private todoAction model dispatch =
+ Html.div [
+ prop.className "flex flex-col sm:flex-row mt-4 gap-4"
+ prop.children [
+ Html.input [
+ prop.className
+ "shadow appearance-none border rounded w-full py-2 px-3 outline-none focus:ring-2 ring-teal-300 text-grey-darker"
+ prop.value model.Input
+ prop.placeholder "What needs to be done?"
+ prop.autoFocus true
+ prop.onChange (SetInput >> dispatch)
+ prop.onKeyPress (fun ev ->
+ if ev.key = "Enter" then
+ dispatch AddTodo)
+ ]
+ Html.button [
+ prop.className
+ "flex-no-shrink p-2 px-12 rounded bg-teal-600 outline-none focus:ring-2 ring-teal-300 font-bold text-white hover:bg-teal disabled:opacity-30 disabled:cursor-not-allowed"
+ prop.disabled (Todo.isValid model.Input |> not)
+ prop.onClick (fun _ -> dispatch AddTodo)
+ prop.text "Add"
+ ]
+ ]
+ ]
+
+[<ReactComponent>]
+let todoList model dispatch =
+ Html.div [
+ prop.className "bg-white/80 rounded-md shadow-md p-4 w-5/6 lg:w-3/4 lg:max-w-2xl"
+ prop.children [
+ Html.ol [
+ prop.className "list-decimal ml-6"
+ prop.children [
+ for todo in model.Todos do
+ Html.li [ prop.className "my-1"; prop.text todo.Description ]
+ ]
+ ]
+
+ todoAction model dispatch
+ ]
+ ]
+open Feliz.UseElmish in the TodoList Module
+open Feliz.UseElmish
+...
+In the todoList module, rename the function todoList to view, and remove the private access modifier.
+On the first line, call React.useElmish, passing it the init and update functions. Bind the output to model and dispatch
let view model dispatch =
+ let model, dispatch = React.useElmish (init, update, [||])
+ ...
+-let containerBox model dispatch =
++let view model dispatch =
++ let model, dispatch = React.useElmish (init, update, [||])
+ ...
+Replace the arguments of the function with unit, and add the ReactComponent attribute to it
[<ReactComponent>]
+let view () =
+ ...
++ [<ReactComponent>]
+- let view model dispatch =
++ let view () =
+ ...
+In the Index module, create a model that holds the current page
type Page =
+ | TodoList
+ | NotFound
+
+type Model =
+ { CurrentPage: Page }
+Create a function that initializes the app based on an url
+let initFromUrl url =
+ match url with
+ | [ "todo" ] ->
+ let model = { CurrentPage = TodoList }
+
+ model, Cmd.none
+ | _ ->
+ let model = { CurrentPage = NotFound }
+
+ model, Cmd.none
+Create a new init function, that fetches the current url, and calls initFromUrl.
let init () = Router.currentUrl () |> initFromUrl
+Add a Msg type, with an PageChanged case
type Msg =
+ | PageChanged of string list
+update function, that reinitializes the app based on an URL
+let update msg model =
+ match msg with
+ | PageChanged url -> initFromUrl url
+Add a pageContent function to the Index module, that returns the appropriate page content
let pageContent model =
+ match model.CurrentPage with
+ | NotFound -> Html.text "Page not found"
+ | TodoList -> TodoList.view ()
+In the view function, replace the call to todoList with a call to pageContent
let view model dispatch =
+ Html.section [
+ ...
+ pageContent model
+ ...
+ ]
+ let view model dispatch =
+ Html.section [
+ ...
+ - todoList view model
+ + pageContent model
+ ...
+ ]
+Wrap the content of the view method in a React.Router element's router.children property, and add a router.onUrlChanged property to dispatch the urlChanged message
let view model dispatch =
+ React.router [
+ router.onUrlChanged ( PageChanged>>dispatch )
+ router.children [
+ Html.section [
+ ...
+ ]
+ ]
+ ]
+let view (model: Model) (dispatch: Msg -> unit) =
++ React.router [
++ router.onUrlChanged ( PageChanged>>dispatch )
++ router.children [
+ Html.section [
+ ...
+ ]
++ ]
++ ]
+The routing should work now. Try navigating to localhost:8080; you should see a page with "Page not Found". If you go to localhost:8080/#/todo, you should see the todo app.
+# sign
+You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. +There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
+There have been a number of changes between the second and third major versions of the SAFE template. This guide shows you how to upgrade your v2 project to v3.
+++If you haven't done so already then you will need to install the prequisites listed in the Quick Start guide.
+
Download and install the latest SAFE Stack V3 template by running the following command:
+dotnet new install SAFE.Template::3.1.1
+Create a new SAFE project in the safetemp folder. We will use this as a basis for our conversion.
dotnet new SAFE -o safetemp
+We advise committing or stashing any unsaved changes to your code and making a new branch to perform the upgrade.
+You can then test it in isolation and then safely merge back in.
+This file lists any custom dotnet tools used.
+.config/dotnet-tools.json file.++Important! If you have installed extra dotnet tools, you will need to add them back in manually.
+
global.json filepaket.dependencies file in the root of the solution.paket.lock file.paket.references files.Important If you have installed extra NuGet packages, you will need to add them back in manually to the dependencies and references files.
+Run paket to update project references:
+dotnet paket install
+paket.lock file.package.json filepackage-lock.json fileImportant If you have installed extra npm packages, you will need to add them back in manually to the dependencies.
+.gitignore file in the root of the solutionbuild.fsx FAKE script.Build.fs fileHelpers.fs fileBuild.fsproj projectpaket.references file (the one directly under the root directory)dotnet sln add Build.fsproj
+Important If you have made any modifications to the build script e.g. extra targets, you will need to add them back in manually. You will also need to add any packages you added for the build to the paket.references file.
+webpack.config.js file.webpack.tests.config.js fileImportant If you have made any modifications to the webpack file, you will need to apply them back in manually.
+Client.fsprojServer.fsprojShared.fsprojRun +
dotnet run
+If you have problems loading your website, carefully check that you haven't missed out any JavaScript or NuGet packages when overwriting the paket and package files. The console output will usually give you a good guide if this is the case.
+ + + + + + + + +This guide shows you how to upgrade your v3 project to v4.
+++If you haven't done so already then you will need to install the prequisites listed in the Quick Start guide.
+
Download and install the latest SAFE Stack V3 template by running the following command:
+dotnet new install SAFE.Template
+Create a new SAFE project in the safetemp folder. We will use this as a basis for our conversion.
dotnet new SAFE -o safetemp
+We advise committing or stashing any unsaved changes to your code and making a new branch to perform the upgrade.
+You can then test it in isolation and then safely merge back in.
+This file lists any custom dotnet tools used.
+.config/dotnet-tools.json file.++Important! If you have installed extra dotnet tools, you will need to add them back in manually.
+
global.json filepaket.dependencies file in the root of the solution.paket.lock file.paket.references files.Important If you have installed extra NuGet packages, you will need to add them back in manually to the dependencies and references files.
+Run paket to update project references:
+dotnet paket install
+paket.lock file.package.json filepackage-lock.json fileImportant If you have installed extra npm packages, you will need to add them back in manually to the dependencies.
+.gitignore file in the root of the solutionBuild.fs fileBuild.fsproj fileImportant If you have made any modifications to the build script e.g. extra targets, you will need to add them back in manually.
+webpack.config.js file.webpack.tests.config.js fileImportant If you have made any modifications to the webpack file, you will need to apply them back in manually.
+Client.Tests.fsproj fileServer.Tests.fsproj fileShared.Tests.fsproj fileClient.fsproj fileServer.fsproj fileShared.fsproj fileFor all of the above, change
+<TargetFramework>net5.0</TargetFramework>
+to
+<TargetFramework>net6.0</TargetFramework>
Server/Properties/launch.json fileRun +
dotnet run
+If you have problems loading your website, carefully check that you haven't missed out any JavaScript or NuGet packages when overwriting the paket and package files. The console output will usually give you a good guide if this is the case.
+On mac you might get an error like this:
+> dotnet run
+dotnet watch 🚀 Started
+/Users/espen/code/dotnet-new-safe-4.1.1/.paket/Paket.Restore.targets(219,5): error MSB3073: The command "dotnet paket restore --project "/Users/espen/code/dotnet-new-safe-4.1.1/src/Shared/Shared.fsproj" --output-path "obj" --target-framework "net6.0"" exited with code 134. [/Users/espen/code/dotnet-new-safe-4.1.1/src/Shared/Shared.fsproj]
+
+The build failed. Fix the build errors and run again.
+dotnet watch ❌ Exited with error code 1
+dotnet watch ⏳ Waiting for a file to change before restarting dotnet...
+^Cdotnet watch 🛑 Shutdown requested. Press Ctrl+C again to force exit.
+If so, try uninstalling all .NET SDKs and runtimes below 3.0.100. See NET uninstall tool for how to unistall SDKs on mac.
+ + + + + + + + +Get the latest dotnet tools such as Fable and Fantomas into your repository.
+dotnet-tools.json file from here.dotnet tool restore.Use our preferred F# formatting style.
+.editorconfig file from here.Migrate all dependencies to .NET 8.
+Overwrite your global.json file from here.
Update each of your project files to target .NET 8.
+<PropertyGroup>
+ <TargetFramework>net8.0</TargetFramework>
+</PropertyGroup>
+Upgrade all .NET dependencies to the latest versions for SAFE v5:
+dotnet paket remove Fable.React -p Client.dotnet paket remove Feliz.Bulma -p Client.paket.dependencies file from here.paket.lock file from here.paket.references file from here.dotnet paket install to update the Shared project.cd into the required project.dotnet paket add <package> --keep-minor. This will download the latest version of the package you required but will not update any associated dependencies outside of their existing major version.webpack.config.jssrc/Client/vite.config.mts file from here.Install Tailwind.
+ +Update HTML and F# code.
+src/Client/index.html with this file.src/Client/App.fs, after the existing open declarations
+ open Fable.Core.JsInterop
+
+importSideEffects "./index.css"
+tests/Client/vite.config.mts from here.tests/Client/index.html file from here..fantomasignore from here.In the Build.fs file replace the following lines:
Line 27:
+- "client", dotnet [ "fable"; "-o"; "output"; "-s"; "--run"; "npm"; "run"; "build" ] clientPath ]
++ "client", dotnet [ "fable"; "-o"; "output"; "-s"; "--run"; "npx"; "vite"; "build" ] clientPath ]
+Line 35:
+- operating_system OS.Windows
+- runtime_stack Runtime.DotNet60
++ operating_system OS.Linux
++ runtime_stack (DotNet "8.0")
+Line 51:
+- "client", dotnet [ "fable"; "watch"; "-o"; "output"; "-s"; "--run"; "npm"; "run"; "start" ] clientPath ]
++ "client", dotnet [ "fable"; "watch"; "-o"; "output"; "-s"; "--run"; "npx"; "vite" ] clientPath ]
+Line 58:
+- "client", dotnet [ "fable"; "watch"; "-o"; "output"; "-s"; "--run"; "npm"; "run"; "test:live" ] clientTestsPath ]
++ "client", dotnet [ "fable"; "watch"; "-o"; "output"; "-s"; "--run"; "npx"; "vite" ] clientTestsPath ]
+Note: If you are using a template created prior to version v4.3, you may have the following string syntax for the dotnet commands and therefore the change you need to make will be slightly different.
- "client", dotnet "fable -o output -s --run npm run build" clientPath
++ "client", dotnet "fable -o output -s --run npx vite build" clientPath
+Tailwind CSS Intellisense extension..vscode/settings.json file from here. The regexes in this file are for Feliz style DSL, if you want to support Fable.React DSL you will need to adapt the regexes.This article shows the steps required in order to create a SAFE Stack 5-style app from scratch. This repository should be used as a guide to follow whilst reading this tutorial; each section links to a specific commit from the history of the repository.
+This first section creates some basic folders and tools that will simply coding going forwards and represents some best practices.
+git init
+.gitignore file to ensure that you do not accidentally commit unnecessary files into your repository. This example file has been generated through VS Code and fine-tuned with extra files / folders required for SAFE Stack applications.dotnet tool install fantomas
+.editorconfig file which configures Fantomas as required for optimal F# formatting.global.json file to pin the repository to a specific version of .NET.
+dotnet new global.json
+Now that we have basic core tools installed, we can go about creating a basic F# server and client and get them communicating with one another.
+server.dotnet new console -lang F#
+dotnet run
+client.dotnet tool install fable
+dotnet fable
+Now that we have a running HTTP server and the ability to create JS from F#, we can now install the required browser libraries and tools required to host a full app in the browser.
+index.html file that will be used as the launch point for the web application; it will also load the JS that is generated by Fable.npm install vite
+++Vite is a multi-purpose tool used to aid development and packaging of JavaScript applications.
+
You can now launch the application. +
dotnet fable watch -o output -s --run npx vite
+output folder and then launches Vite, which acts as a local development web server.
+You should see output in your terminal similar to this:
+
http://localhost:5173 in your browser and view the console output using the dev console (normally F12). You should see the console output from your client's Program.fs e.g.
Now that we have running client and server F# applications, let's have them communicate with each other over HTTP. We'll use a basic library for this called SimpleHttp.
+vite.config.mts which will tell it to redirect traffic destined for the server (which we assume always starts with /api/) to port 5000 (which is the port the server runs on).++See here for more information about this redirection process.
+
Program.fs to handle the on-click event of the button so that when it is clicked, it makes a request to e.g. /api/data and puts the response in the console and a browser alert.
Congratulations! At this stage, you have a working F# client / server application that can communicate over HTTP.
+We now spend the next few steps getting React working within the app and with F# support.
+Now that we have a (very) basic F# client/server app, we'll now add support for React - a front-end framework that will enable us to create responsive and rich UIs.
+Now that we have React added to our application, we can add the appropriate F# libraries such as Feliz to start to use React in a typesafe, F#-friendly manner.
+<button> element from the index.html - we'll be creating it dynamically with React from now on.<div> with an named id to the body of the index.html. This will be the "root" element that React will attach to from which to make HTML elements.Program.fs in the Client project so that it creates a React button that can behave as the original static HTML button.This next step adds Feliz's JSX support, which allows you to embed standard React JSX code directly in your F# applications.
+button [] element), use standard JSX code with string interpolation.Program.jsx instead of Program.js in your index.html file..jsx instead of .js files:dotnet fable watch -o output -s -e .jsx --run npx vite
+This next section takes advantage of F#'s typing for both client and server.
+shared, and a Contracts.fs file inside it.text "Hello world" call with it.Elmish is an F# library modelled closely on the Elm language model for writing browser-based applications, which has popularised the "model-view-update" paradigm.
+index.html.This last section adds more UX capabilities.
+Follow the Tailwind guide to add Tailwind to your project.
+If you do not want to use the JSX support:
+JSX.jsx to create components but rather standard [ReactComponent].div and button etc.Welcome to the SAFE documentation site! This site contains all the documentation you'll need to quickly starting creating SAFE apps in F#.
If you've not heard of SAFE before, please feel free to start with the introduction. Alternatively, you can immediately try out the quickstart guide and tutorial, or simply browse through the documentation.
If there's anything missing from here, please feel free to add the documentation directly (or supply an issue) to the GitHub repository.
We hope you enjoy using SAFE as much as we do!
The SAFE team :)
"},{"location":"awesome-safe-components/","title":"SAFE-Compatible UI Components","text":"A set of SAFE-ready wrappers around existing React and JS UI Components.
"},{"location":"awesome-safe-components/#how-can-i-contribute-my-library-to-this-list","title":"How can I contribute my library to this list?","text":""},{"location":"awesome-safe-components/#required","title":"Required","text":"A fresh retake of the React API in Fable and a collection of high-quality components to build React applications in F#, optimized for happiness. Get it!
"},{"location":"awesome-safe-components/#fablereact","title":"Fable.React","text":"Fable bindings and helpers for React and React Native. Get it!
"},{"location":"awesome-safe-components/#ui-frameworks","title":"UI Frameworks","text":""},{"location":"awesome-safe-components/#felizbulma","title":"Feliz.Bulma","text":"Bulma UI wrapper for amazing Feliz DSL. Get it!
"},{"location":"awesome-safe-components/#fulma","title":"Fulma","text":"Fulma provides a wrapper around Bulma 0.9.0, an open source CSS framework, for fable-react. Get it!
"},{"location":"awesome-safe-components/#felizmaterialui","title":"Feliz.MaterialUI","text":"Feliz-style Fable bindings for Material-UI. Get it!
"},{"location":"awesome-safe-components/#fablereactstrap","title":"Fable.Reactstrap","text":"Fable binding for reactstrap. Get it!
"},{"location":"awesome-safe-components/#fablematerialui","title":"Fable.MaterialUI","text":"Fable bindings for Material-UI. Get it!
"},{"location":"awesome-safe-components/#fableantd","title":"Fable.AntD","text":"Fable bindings for Ant Design React components. Get it!
"},{"location":"awesome-safe-components/#fablefontawesomefree","title":"Fable.FontAwesome.Free","text":"Bindings for the Free icons of Font Awesome, should be used with Fable.FontAwesome. Get it!
"},{"location":"awesome-safe-components/#fablefluentui","title":"Fable.FluentUI","text":"FluentUI (React) to Fable bindings. Get it!
"},{"location":"awesome-safe-components/#fablereactgridsystem","title":"Fable.ReactGridSystem","text":"React Grid System to Fable bindings. Get it!
"},{"location":"awesome-safe-components/#ui-controls","title":"UI Controls","text":""},{"location":"awesome-safe-components/#felizpopover","title":"Feliz.Popover","text":"Feliz-style Fable bindings for react-popover. Get it!
"},{"location":"awesome-safe-components/#felizselectsearch","title":"Feliz.SelectSearch","text":"A binding for react-select-search that implements a searchable and customizable dropdown for Feliz applications. Get it!
"},{"location":"awesome-safe-components/#felizkawaii","title":"Feliz.Kawaii","text":"Feliz-style Fable bindings for react-kawaii which contains lovely SVG components. Get it!
"},{"location":"awesome-safe-components/#felizsweetalert","title":"Feliz.SweetAlert","text":"Feliz-style Fable bindings for sweetalert2 and sweetalert2-react-content with Feliz style api for use within React applications. Implemented as both normal functions and Elmish commands, for maximum flexibility. Get it!
"},{"location":"awesome-safe-components/#elmishsweetalert","title":"Elmish.SweetAlert","text":"SweetAlert integration for Fable, made with love to work in Elmish apps. Get it!
"},{"location":"awesome-safe-components/#elmishtoastr","title":"Elmish.Toastr","text":"Toastr integration with Fable, implemented as Elmish commands. Get it!
"},{"location":"awesome-safe-components/#elmishanimatedtree","title":"Elmish.AnimatedTree","text":"A fork and binding of react-animated-tree, adapted to properly work within Elmish applications. Get it!
"},{"location":"awesome-safe-components/#felizreacthamburger","title":"Feliz.ReactHamburger","text":"Feliz-style Fable bindings for hamburger-react. Get it!
"},{"location":"awesome-safe-components/#felizreactawesomeslider","title":"Feliz.ReactAwesomeSlider","text":"Feliz-style Fable bindings for react-awesome-slider. Get it!
"},{"location":"awesome-safe-components/#felizreactselect","title":"Feliz.ReactSelect","text":"Feliz-style Fable bindings for react-select. Get it!
"},{"location":"awesome-safe-components/#fablereactflatpickr","title":"Fable.React.Flatpickr","text":"Fable binding for react-flatpickr that is ready to use within Elmish applications. Get it!
"},{"location":"awesome-safe-components/#feliztippy","title":"Feliz.Tippy","text":"Feliz-style Fable bindings for tippyjs-react. Get it!
"},{"location":"awesome-safe-components/#felizreactspeedometer","title":"Feliz.ReactSpeedometer","text":"Feliz-style Fable bindings for react-d3-speedometer. Get it!
"},{"location":"awesome-safe-components/#fablereactkanban","title":"Fable.ReactKanban","text":"React Kanban bindings for Fable React. Get it!
"},{"location":"awesome-safe-components/#fablereactdrawingcanvas","title":"Fable.React.DrawingCanvas","text":"This is a Fable React wrapper for canvas that allows you to declare a drawing. Get it!
"},{"location":"awesome-safe-components/#fablegroupingpanel","title":"Fable.GroupingPanel","text":"An F# computation expression that groups Fable UI data into one or more collapsable panels. Get it!
"},{"location":"awesome-safe-components/#data-visualisation","title":"Data Visualisation","text":""},{"location":"awesome-safe-components/#felizaggrid","title":"Feliz.AgGrid","text":"Feliz-style Fable bindings for ag-grid. Get it!
"},{"location":"awesome-safe-components/#fablereactaggrid","title":"Fable.ReactAgGrid","text":"Fable bindings for ag-grid. Get it!
"},{"location":"awesome-safe-components/#felizreactflow","title":"Feliz.Reactflow","text":"Feliz-style Fable bindings for react flow. Get it!
"},{"location":"awesome-safe-components/#maps","title":"Maps","text":""},{"location":"awesome-safe-components/#fablereactgooglemaps","title":"Fable.ReactGoogleMaps","text":"Feliz-style Fable bindings for react-google-maps. Get it!
"},{"location":"awesome-safe-components/#felizpigeonmaps","title":"Feliz.PigeonMaps","text":"Feliz-style bindings for pigeon-maps, React maps without external dependencies. This binding includes it's own custom PigeonMaps.marker component to build map markers manually. Get it!
"},{"location":"awesome-safe-components/#charting","title":"Charting","text":""},{"location":"awesome-safe-components/#felizagchart","title":"Feliz.AgChart","text":"Feliz-style bindings for ag-charts. Get it!
"},{"location":"awesome-safe-components/#felizplotly","title":"Feliz.Plotly","text":"Fable bindings for plotly.js and react-plotly.js with Feliz style api for use within React applications. Lets you build visualizations in an easy, discoverable, and safe fashion. Get it!
"},{"location":"awesome-safe-components/#felizrecharts","title":"Feliz.Recharts","text":"Feliz-style bindings for recharts, a composable charting library built on React components. The binding translates the original API of recharts in a one-to-one fashion but makes it type-safe and easily discoverable. Get it!
"},{"location":"awesome-safe-components/#felizroughviz","title":"Feliz.RoughViz","text":"Feliz-style Fable bindings for roughViz visualisation library. It is a fun project when your data visualisations don't need to be formal. This binding is actually made to work with original rough-viz library than renders to the DOM rather than an existing third-party React library which makes it a nice example to learn from. Get it!
"},{"location":"awesome-safe-components/#state-management","title":"State management","text":""},{"location":"awesome-safe-components/#felizrecoil","title":"Feliz.Recoil","text":"Fable bindings in Feliz style for Facebook's experimental state management library recoil. Get it!
"},{"location":"awesome-safe-components/#testing","title":"Testing","text":""},{"location":"awesome-safe-components/#fablejester","title":"Fable.Jester","text":"Fable bindings for jest and friends for delightful Fable testing. Get it!
"},{"location":"awesome-safe-components/#fablemocha","title":"Fable.Mocha","text":"Fable library for testing. Inspired by the popular Expecto library for F# and adopts the testList, testCase and testCaseAsync primitives for defining tests. Get it!
"},{"location":"awesome-safe-components/#fablereacttestinglibrary","title":"Fable.ReactTestingLibrary","text":"Fable bindings for react-testing-library and user-event. Get it!
"},{"location":"awesome-safe-components/#animation","title":"Animation","text":""},{"location":"awesome-safe-components/#funreactspring","title":"Fun.ReactSpring","text":"Fable bindings for react spring. Get it!
"},{"location":"intro/","title":"Introduction","text":""},{"location":"intro/#what-is-safe","title":"What is SAFE?","text":"The SAFE stack is the best way to write functional-first web applications.
The SAFE stack allows you to develop web applications almost entirely in F#, without needing to compromise and shoehorn your codebase into an object-oriented framework or library, and without needing you to be an expert in CSS or HTML to create compelling, rich client-side web applications. SAFE Stack is:
The SAFE stack is made up of four components:
SAFE provides developers with a simple and consistent programming model for developing rich, scalable web-enabled applications that can run on multiple platforms. SAFE takes advantage of F#'s functional-first experience backed by the powerful and mature .NET framework to provide a type-safe, reliable experience that leads to the \"pit of success\".
This section contains useful repositories that allow you to learn more about the SAFE stack, at your own pace.
"},{"location":"learning/#tutorials","title":"Tutorials","text":""},{"location":"learning/#safe-dojo","title":"SAFE Dojo","text":"This dojo is a guided set of tasks designed to give you hands-on experience with the client and server components of the SAFE stack. You'll create server-side routes, client side UI and shared validation logic as you create a mashup application to provide details on UK locations.
The dojo takes around 90 minutes to complete if you have never worked with the stack before.
"},{"location":"learning/#safe-samples","title":"SAFE Samples","text":"The following example repositories (and more!) can be found in the official SAFE Stack organisational GitHub page.
"},{"location":"learning/#safe-todo-list","title":"SAFE Todo List","text":"The simplest Todo app: a client-server application written entirely in F# using Elmish on the client. Remoting for type-safe communication between the two.
"},{"location":"learning/#tabula-rasa","title":"tabula-rasa","text":"A minimalistic real-worldish blog engine written entirely in F#. Specifically made as a learning resource when building apps with the SAFE stack. This application features many concerns of large apps such as logging, database access, secured remoting, web sockets and much more.
"},{"location":"learning/#safe-bookstore","title":"SAFE Bookstore","text":"This sample demonstrates many of the useful features of a larger SAFE application, including login authentication using JWT tokens, automated deployment via Docker and SEO support with urls for pages. It also includes an example of using Azure Storage tables as a persistence store.
"},{"location":"learning/#safe-confplanner","title":"SAFE ConfPlanner","text":"This sample demonstrates how to build and share a complex domain model in SAFE across client and server, along with the use of websockets for a \"reactive\" UI support push notifications. It also demonstrates the use of F#'s flexible mailbox processors to implement an event-driven architecture.
"},{"location":"learning/#safe-search","title":"SAFE Search","text":"This repository shows how to use Azure services to implement a SAFE application that supports searching over multiple data sources with support for find-ahead typing and throttling. The application uses a combination of Azure Search and Azure Storage Tables to construct a large search index that can rapidly find results in a number of ways.
"},{"location":"learning/#safe-chat","title":"SAFE Chat","text":"This application is a real-time chat application built on SAFE that uses the AKKA framework to manage actors that represent chat users, including Akka Streams and the Akkling F# library.
"},{"location":"learning/#safe-nightwatch","title":"SAFE Nightwatch","text":"This application is a sample mobile application using the React Native library, built on top of the SAFE stack. React Native permits a very similar programming when writing SAFE applications as browser applications, so the experience should be very familiar to you.
"},{"location":"learning/#videos","title":"Videos","text":"Enjoy the latest version of .NET runtime with newest SAFE Stack template!
"},{"location":"news/#2021","title":"2021","text":""},{"location":"news/#28th-june-safe-v3-is-live","title":"28th June - SAFE v3 is Live!","text":"After a long beta test period, we're excited to launch SAFE 3! The new template upgrades SAFE to .NET 5 compatibility, Fable 3 and the latest versions of Giraffe and Saturn. We've also introduced the use of the popular Feliz domain-specific language (DSL), upgraded all documentation and made the build process even easier to use.
We're super excited about this update as well as hearing about your suggestions and ideas to make it even better in the future.
"},{"location":"news/#2020","title":"2020","text":""},{"location":"news/#22nd-august-safe-v2-launches","title":"22nd August - SAFE v2 Launches!","text":"It's taken a while, but we're delighted to announce the launch of SAFE v2. The new template has been drastically slimmed down and provides a highly streamlined approach, whilst we've incorporated requested features such as testing support out of the box.
We're looking forward to building on the new template with improved documentation, a set of easy-to-follow recipes for common tasks as well as new demos, exercises and a set of new wrappers around popular JS and React libraries.
"},{"location":"news/#2018","title":"2018","text":""},{"location":"news/#5th-august","title":"5th August","text":"We're pleased to see that the Suave team has clarified their license and explicitly removed the dependency on the Logary package. However, our decision to remove Suave from the SAFE stack remains: Suave no longer forms a part of the strategic goals of the SAFE project, and our server-side focus remains on improving the experience for both Giraffe and Saturn.
We nonetheless wish the Suave project, team and contributors the best of luck for the future.
"},{"location":"news/#18th-june","title":"18th June","text":"Due to the unclear future regarding the licensing of Suave and its dependencies, the SAFE team has today made the unamimous decision to remove Suave as a recommended option on the SAFE stack. We will no longer provide guidance on integrating Suave with the SAFE stack, nor will we maintain existing capabilities for it in SAFE tooling.
Our default recommendation for SAFE stack applications is to use Saturn or Giraffe directly, running on top of Kestel on ASP.NET.
SAFE will continue to promote all libraries, frameworks and toolchains that provide clear and consistent licensing, do not aim to discriminate against specific libraries on a commercial basis and promote open discussion.
"},{"location":"overview/","title":"Overview","text":""},{"location":"overview/#safe-stack-components","title":"SAFE Stack components","text":"The SAFE acronym is made up of four separate components:
The Saturn library builds on top of the solid foundation of both the F#-friendly Giraffe and the high performance, rock-solid ASP.NET Core web server to provide a set of optional abstractions which make configuring web applications and constructing complex routes extremely easy to achieve.
Saturn can host RESTful API endpoints, drive static websites or server-generated content, all inside an easy-to-learn functional programming model.
"},{"location":"overview/#microsoft-azure","title":"Microsoft Azure","text":"Azure is a comprehensive set of cloud services that developers and IT professionals use to build, deploy and manage applications through a global network of data centres. Integrated tools, DevOps and a marketplace support you in efficiently building anything from simple mobile apps to Internet-scale solutions.
"},{"location":"overview/#fable","title":"Fable","text":"Fable is an F# to JavaScript compiler, designed to produce readable and standard code. Fable allows you to create applications for the browser written entirely in F#, whilst also allowing you to interact with native JavaScript as needed.
"},{"location":"overview/#elmish","title":"Elmish","text":"The Elmish model allows you to construct user interfaces running in the browser using a functional programming approach. Based upon on the Elm application model, Elmish uses the Model-View-Update paradigm to allow you to write applications that are simple to reason about. Elmish sits on top of the React framework.
"},{"location":"overview/#further-reading","title":"Further reading","text":"Please also feel free to read this blog series on the Compositional IT website for more details on the history of SAFE.
"},{"location":"overview/#are-there-alternative-components-in-the-safe-stack","title":"Are there alternative components in the SAFE stack?","text":"Yes, absolutely. The above components are what we recommended as the default SAFE stack, but you can of course replace the components with alternatives as you see fit. Here are some alternative technologies which are also recommended by the SAFE team if the basic stack does not fit your needs:
This page provides some basic guidance on getting up and running with your first SAFE application.
"},{"location":"quickstart/#install-pre-requisites","title":"Install pre-requisites","text":"You'll need to install the following pre-requisites in order to build SAFE applications
You'll also want an IDE to create F# applications. We recommend one of the following great IDEs:
dotnet new install SAFE.Template to install the SAFE project template (only required once )dotnet new SAFE to create a new SAFE projectdotnet tool restore to install local tools like Fable.dotnet run to build and run the appCongratulations - after a short delay, you'll be presented with a basic SAFE application running in your browser! The application will by default run in \"development mode\", which means it automatically watches your project for changes; whenever you save a file in the client project it will refresh the browser automatically; if you save a file in the server project it will also restart the server in the background.
The standard template creates an opinionated SAFE Stack app that contains everything you'll need to start developing, testing and deploying applications into Azure. Alternatively there is a \"bare-bones\" SAFE Stack app with minimal value-add features. Take a look at the template options to see a side by side comparison of features available between the standard and minimal template.
"},{"location":"quickstart/#troubleshooting","title":"Troubleshooting","text":"Still have issues getting started? Check out the troubleshooting page.
"},{"location":"safe-from-scratch/","title":"Creating a SAFE Stack App from Scratch","text":"This article shows the steps required in order to create a SAFE Stack 5-style app from scratch. This repository should be used as a guide to follow whilst reading this tutorial; each section links to a specific commit from the history of the repository.
"},{"location":"safe-from-scratch/#1-folders-and-tools","title":"1. Folders and tools","text":"This first section creates some basic folders and tools that will simply coding going forwards and represents some best practices.
"},{"location":"safe-from-scratch/#11-create-a-basic-source-controlled-repository","title":"1.1 Create a basic source-controlled repository","text":"git init\n.gitignore file to ensure that you do not accidentally commit unnecessary files into your repository. This example file has been generated through VS Code and fine-tuned with extra files / folders required for SAFE Stack applications.dotnet tool install fantomas\n.editorconfig file which configures Fantomas as required for optimal F# formatting.global.json file to pin the repository to a specific version of .NET. dotnet new global.json\nNow that we have basic core tools installed, we can go about creating a basic F# server and client and get them communicating with one another.
"},{"location":"safe-from-scratch/#21-create-a-basic-server-application","title":"2.1 Create a basic server application","text":"server.dotnet new console -lang F#\ndotnet run\nclient.dotnet tool install fable\ndotnet fable\nNow that we have a running HTTP server and the ability to create JS from F#, we can now install the required browser libraries and tools required to host a full app in the browser.
index.html file that will be used as the launch point for the web application; it will also load the JS that is generated by Fable.npm install vite\nVite is a multi-purpose tool used to aid development and packaging of JavaScript applications.
You can now launch the application.
dotnet fable watch -o output -s --run npx vite\noutput folder and then launches Vite, which acts as a local development web server. You should see output in your terminal similar to this:
http://localhost:5173 in your browser and view the console output using the dev console (normally F12). You should see the console output from your client's Program.fs e.g.Now that we have running client and server F# applications, let's have them communicate with each other over HTTP. We'll use a basic library for this called SimpleHttp.
vite.config.mts which will tell it to redirect traffic destined for the server (which we assume always starts with /api/) to port 5000 (which is the port the server runs on). See here for more information about this redirection process.
Program.fs to handle the on-click event of the button so that when it is clicked, it makes a request to e.g. /api/data and puts the response in the console and a browser alert.Congratulations! At this stage, you have a working F# client / server application that can communicate over HTTP.
"},{"location":"safe-from-scratch/#3-adding-react","title":"3. Adding React","text":"We now spend the next few steps getting React working within the app and with F# support.
"},{"location":"safe-from-scratch/#31-add-basic-react-support","title":"3.1 Add basic React support","text":"Now that we have a (very) basic F# client/server app, we'll now add support for React - a front-end framework that will enable us to create responsive and rich UIs.
Now that we have React added to our application, we can add the appropriate F# libraries such as Feliz to start to use React in a typesafe, F#-friendly manner.
<button> element from the index.html - we'll be creating it dynamically with React from now on.<div> with an named id to the body of the index.html. This will be the \"root\" element that React will attach to from which to make HTML elements.Program.fs in the Client project so that it creates a React button that can behave as the original static HTML button.This next step adds Feliz's JSX support, which allows you to embed standard React JSX code directly in your F# applications.
button [] element), use standard JSX code with string interpolation.Program.jsx instead of Program.js in your index.html file..jsx instead of .js files:dotnet fable watch -o output -s -e .jsx --run npx vite\nThis next section takes advantage of F#'s typing for both client and server.
"},{"location":"safe-from-scratch/#41-add-type-safe-client-server-communication","title":"4.1 Add type-safe Client / Server communication","text":"shared, and a Contracts.fs file inside it.text \"Hello world\" call with it.Elmish is an F# library modelled closely on the Elm language model for writing browser-based applications, which has popularised the \"model-view-update\" paradigm.
index.html.This last section adds more UX capabilities.
"},{"location":"safe-from-scratch/#51-add-tailwind-support","title":"5.1 Add Tailwind support","text":"Follow the Tailwind guide to add Tailwind to your project.
"},{"location":"safe-from-scratch/#52-revert-to-standard-f-feliz-optional","title":"5.2 Revert to \"standard\" F# Feliz (optional)","text":"If you do not want to use the JSX support:
JSX.jsx to create components but rather standard [ReactComponent].div and button etc.The following companies provide commercial training, support, consultancy and development services for SAFE Stack applications.
"},{"location":"support/#compositional-it","title":"Compositional IT","text":"Compositional IT are experts in designing functional-first, cloud-ready systems, offering consultancy and support, training and development. Run by an F# MVP and well-known member of the .NET community, they are dedicated to raising awareness of the benefits of both functional programming and harnessing the power of the cloud to deliver high-quality, low-cost solutions.
"},{"location":"support/#lambda-factory","title":"Lambda Factory","text":"Lambda Factory is a consulting company specializing in designing and building complex systems using Functional Programming languages such as F#, Elm and Elixir. It also offers help with introducing functional programming and open source driven development to the organization, as well as trainings, workshops and mentoring. Founded by open source contributor and well-known member of F# Community, Lambda Factory has been committed to supporting F# Community and helping it grow.
"},{"location":"support/#fuzzy-cloud","title":"Fuzzy Cloud","text":"Fuzzy Cloud is a fast-growing team of highly skilled and passionate IT professionals who can deliver services that help you speed up innovation and maximize efficiency. Our services are dynamic, scalable, resilient and responsive enabling rapid growth and high value for our clients. We take a highly collaborative approach to align our services with your business goals. We provide consulting in area like Cloud, Cross Platform mobile development, Machine Learning etc using Languages like F#, Python, Dart and few others.
"},{"location":"support/#the-f-community","title":"The F# Community","text":"The SAFE stack was written largely by the community as open source projects, such as Saturn, Giraffe, Fable and Elmish (as well as the alternative elements within the stack). All those teams are always happy to contribute and help out.
"},{"location":"support/#social","title":"Social","text":"You can also reach out to the SAFE team on @safe_stack or on the regular F# channels on Slack: either the official F# Foundation Slack (an F# Foundation membership is required) or on the Functional Programming Slack. We'll be expanding this over time.
"},{"location":"template-overview/","title":"Overview","text":"The SAFE Template is a dotnet CLI template for SAFE Stack projects, designed to get you up and running as quickly as possible, with flexible options to suit your application. The template gets you up and running with the most common elements of the stack with minimal configuration options.
All template options come with a fully working end-to-end SAFE application with known-good dependencies on client (NPM) and server (NuGet), as well as a preconfigured Vite configuration file.
"},{"location":"template-overview/#using-the-template","title":"Using the template","text":"Refer to the Quickstart guide to see basic guidance on how to install and use the template.
"},{"location":"template-overview/#template-options","title":"Template options","text":"The template provides two simple modes: the standard and minimal template.
"},{"location":"template-overview/#standard-template","title":"Standard Template","text":"The standard template creates an opinionated SAFE Stack app that contains everything you'll need to start developing, testing and deploying applications into Azure.
dotnet new SAFE\nUse this configuration if..
The minimal template is a \"bare-bones\" SAFE Stack app with minimal value-add features.
dotnet new SAFE -m\nUse this configuration if..
The SAFE Stack now runs FAKE using a console app rather than a script.
"},{"location":"template-safe-commands/#run","title":"\"Run\"","text":"dotnet run\nUsed for development purposes, and provides a great live-reload experience. It pulls down any dependencies required for both the client and server, before running both the client and server in a \"watch\" mode, so any changes you make on either side will be automatically applied without you needing to restart the application.
Navigating to http://localhost:8080/ will load the application.
dotnet run Bundle\nUsed to both build and package up your application in a production fashion, ready for deployment. It will restore all dependencies and build both the client and server in a production and release mode respectively, and correctly copy the outputs into the deploy folder in the root of the application. Once your build has completed, you can launch the entire application locally to test it as follows:
cd deploy\nServer\nNavigating to http://localhost:5000/ will load the application.
dotnet run Azure\nThis target will deploy your application to Azure with a fully configured Application Insights instance. You do not need to pre-create any resources in Azure - the template will create everything needed, using free SKUs so you can test without any costs.
You must already have an Azure account and will be prompted to log into it during the deployment process.
This build step uses both the Azure CLI and Farmer projects to create all resources in just a few lines of code.
The name of resources will be generated based on the folder in which you created the application. These may be incompatible with Azure naming rules, or may already be in use (Azure web applications must be globally unique) so you may have to modify the name of the webapp to pick one that is acceptable.
"},{"location":"template-safe-commands/#runtests-target","title":"\"RunTests\" target","text":"dotnet run RunTests\nThis target behaves similarly to the standard Run target, except that it launches the unit tests for both client and server.
Launch the client tests on http://localhost:8081/
dotnet run Format\nThis target will format all the F# files in the src folder using Fantomas. Out of the box, Fantomas tries to reformat the code according to the F# style guide by Microsoft. For more info, check out the documentation.
Please feel free to submit a PR to add testimonials to this page!
"},{"location":"testimonials/#msu-solutions-gmbh","title":"msu solutions GmbH","text":"SAFE gives us a fast development cycle for our web and mobile platforms
We at msu solutions GmbH are big fans of SAFE stack. For the last couple of years we were already using F# open source technologies for web and mobile projects. Tools like the Fable compiler and elmish are rock solid and a pleasure to work with.
Since the release of SAFE, we see that all these important technologies are now bundled and tested under one big umbrella. Especially the commercial support for SAFE is very important for us and our customers.
"},{"location":"testimonials/#goswin-rothenthal","title":"Goswin Rothenthal","text":"It just works!
The docs are very detailed and helpful. I got the template up and running on a public URL on Azure within one hour. Without any issues. Even though I am new to dotnet core and Azure.
"},{"location":"testimonials/#demetrix","title":"Demetrix","text":"SAFE was the perfect place to start our biological design and data management platform
Demetrix uses F# for DNA design and data management in our research pipeline. Our data systems are built on top of SAFE and it was a great experience for both veteran F# developers and people new to the environment. I would start with SAFE again in a heartbeat for a new project. We shared some of our experiences at Open F# 2018.
"},{"location":"testimonials/#microdesk","title":"Microdesk","text":"Spoil your customers with F# and the SAFE stack!
Porting a production web app from TypeScript/React to use the SAFE stack turned out to be a huge win. Sharing F# models on the front and back-end allows you to leverage the excellent F# compiler and type system when designing and refactoring your codebase. Using a type provider (in our case, SQLProvider) extends this coverage to your database as well. This means that changes to any part of your application will be picked up by the compiler which will essentially guide you to every relevant place in the source code that needs to be updated. This is so effective that once you experience it, you will never want to be without it.
On the front end, the Elmish pattern, which may look intimidating at first glance, is actually quite fun and intuitive to write. More importantly, it guides you into the \"pit of success\" by making you write highly testable \"pure functions\" that outline your UI state transitions (in your update function). Putting all state transitions in one place becomes a breath of fresh air because it eliminates the spaghetti code that can happen in MVVM view models of even modest complexity. Do you have a complex \"sort\" that needs to be handled in your update? You can easily write a unit test in F# that passes in the relevant command input for that. No mocking is required because it will be a pure function! If you still feel leery of the Elmish pattern, you are free to use React Hooks API or any other pattern you prefer. There are also many excellent external libraries - i.e. Feliz - that allow you to optionally use the Elmish pattern on only certain pages, among other things.
Worried about getting stuck? Don't worry because the F# community will practially crawl all over themselves to be the first to answer you question. There are also options for professional consultation as well. The community support is amazing! The SAFE stack is designed to be as turn-key as possible, but there are also plenty of opportunities to customize the stack as you see fit.
Overall, the SAFE stack has allowed me to completely spoil a very demanding customer with timely, bug-free deliverables.
"},{"location":"testimonials/#jake-witcher","title":"Jake Witcher","text":"I really appreciate the effort that went in to this!
The F# SAFE stack documentation is incredibly well done. One of the best features is the learning resources page that includes GitHub repos of example projects.
"},{"location":"testimonials/#casper-bollen","title":"Casper Bollen","text":"Never did Computer Science
The SAFE stack enables me to create full backend to frontend web apps in a matter of weeks!!
"},{"location":"testimonials/#leko-thomas","title":"Leko Thomas","text":"Recipes are concise solve only one problem and are composable
I find SAFE stack recipes have so much value. Thank you! Please keep on doing it.
"},{"location":"testimonials/#james-randall","title":"James Randall","text":"After a year I still feel like F# with the SAFE stack is like high octane rocket fuel for developers.
The F# community have created, and made very accessible, a fantastic set of tools that allow you to write F# end to end on the web and in a way that embraces the existing world.
"},{"location":"components/component-azure/","title":"Azure in SAFE","text":""},{"location":"components/component-azure/#what-is-azure","title":"What is Azure?","text":"Azure is a comprehensive set of cloud services that developers and IT professionals use to build, deploy and manage applications through a global network of data centres. Integrated tools, DevOps and a marketplace support you in efficiently building anything from simple mobile apps to Internet-scale solutions.
"},{"location":"components/component-azure/#how-does-azure-integrate-with-safe","title":"How does Azure integrate with SAFE?","text":"Azure provides a number of flexible services for SAFE applications, including (but not only):
"},{"location":"components/component-azure/#hosting-services","title":"Hosting Services","text":"Azure comes with several ready-made hosting services, including App Service, which enables seamless hosting of web applications, including ASP.NET Core applications (which Saturn is built on top of). In addition, Azure supports a number of managed hosting services for Docker and Kubernetes, which work fantastically well with SAFE.
"},{"location":"components/component-azure/#platform-services","title":"Platform Services","text":"Azure comes with a large number of ready-made platform services that can dramatically lower the cost of developing bespoke systems, including:
Many of the above services have ready-made SDKs that can be run on .NET and therefore from F#.
"},{"location":"components/component-elmish/","title":"Elmish in SAFE","text":""},{"location":"components/component-elmish/#what-is-elmish","title":"What is Elmish?","text":"Elmish is a library for building single page applications in F#, following the model-view-update architecture made famous by Elm.
The following diagram is a simplified, high-level view of the MVU pattern. Model in this case refers to your application's state, with Update and View the two functions that handle the flow of messaging. If you wish to read more, we also recommend reading the excellent Elmish Book.
Elmish is the library used to build the front-end application in SAFE and that application is compiled to JavaScript by Fable to run in the browser. The SAFE Stack template comes pre-bundled with the Elmish React module, which (as the name suggests) uses the React library to handle the heavy lifting of modifyng the DOM in an efficient way. This allow us to use the pure functional style of the MVU pattern whilst still retaining the ability to have a highly performant user interface.
Because Elmish works alongside React, it is possible to use the vast number of available React components from the JavaScript ecosystem within our Elmish applications.
This conceptual diagram illustrates how the different pieces of Elmish, React and Fable fit together to make the front-end part of your SAFE application which runs in the browser.
flowchart RL subgraph Browser React(React - Handles DOM updates) Fable(Fable - Translates F# to JS) ER(Elmish React - Elmish to React bridge) Elmish(Elmish - Provides MVU abstractions) You(Your F# domain logic) You --- Elmish --- ER --- Fable --- React end"},{"location":"components/component-elmish/#learn-elmish","title":"Learn Elmish","text":"Fable is an F#-to-JavaScript (JS) compiler, designed to produce readable and standard JS code. Fable brings all the power of F# to the JS ecosystem, with support for most of the F# core library as well as the most commonly used .NET APIs.
It also provides rich integration with the JS ecosystem which means that you can use JS libraries from F# (and vice versa) as well as make use of standard JS tools.
"},{"location":"components/component-fable/#how-does-fable-integrate-with-safe","title":"How does Fable integrate with SAFE?","text":"Fable is a tool that generates JavaScript files from F# code. This allows us to write full front end applications using F#. Being able to write both the Server and Client in the same language offers huge benefits especially when you can share code between the two, without the need for duplication. More information on code sharing can be found here.
"},{"location":"components/component-fable/#fable-and-vite","title":"Fable and Vite","text":"As Fable allows us to integrate into the JS Ecosystem, we can make use of tools such as Vite with features including Hot Module replacement and Source Maps.
The SAFE Template already has Vite configured to get you up and running immediately.
Learn more about Fable here.
"},{"location":"components/component-saturn/","title":"Saturn in SAFE","text":"Saturn is a web development library written in F# which allows you to easily create both server-side MVC applications as well as web APIs. It runs on top of two other components:
Saturn, via Giraffe, provides very good integration with other ASP.NET Core components such as authentication.
Many of Saturn's components and concepts will seem familiar to those of us with experience of other web frameworks such as Ruby on Rails, Python\u2019s Django or especially Elixir's Phoenix.
"},{"location":"components/component-saturn/#how-does-saturn-integrate-with-safe","title":"How does Saturn integrate with SAFE?","text":"Saturn provides the ability to drive your SAFE applications from the server. It enables:
It also integrates with SAFE to allow seamless sharing of types and functions, since Fable will convert most F# into JavaScript. In addition, you can seamless transport data between client and server using either the Fable.JSON or Fable.Remoting libraries, both of which have support for Saturn. You can read more about this here.
flowchart TB outputs>JSON, HTML etc.] subgraph host[.NET Core Host] saturn[Saturn - Routers, Controllers etc.] giraffe[Giraffe - Core F# abstractions] aspnet[ASP.NET Core - HTTP Context etc.] kestrel[Kestrel - Web Server] saturn --- giraffe --- aspnet --- kestrel end data[(Transactional Data e.g. SQL)] content>Static Content e.g. HTML, CSS, JavaScript] outputs -- serves --- host kestrel -- reads --- data kestrel -- reads --- contentLearn more about Saturn here.
"},{"location":"faq/faq-build/","title":"Moving from dev to prod","text":"This page explains the key differences that you should be aware of between running SAFE applications in development and production.
"},{"location":"faq/faq-build/#developing-safe-applications","title":"Developing SAFE applications","text":"The SAFE template is geared towards a streamlined development process. It builds and runs both the client and server on your machine.
During development, in parallel to your .NET web server, Vite dev Server is used to enable hot module replacement. This means that you can continually make changes to your client application code and can rapidly see the results reflected in your browser, without the need to fully reload the application.
The build of the .NET server also makes use of dotnet watch to have the server automatically restart with the latest changes. Since your backend applications will typically be stateless, this permits a rapid development workflow.
It's important to note that the Vite dev server is configured to automatically route traffic intended for api/* routes to the backend web server. This simulates how a SAFE application might work in a production environment, with both client and server assets served from a single web server. This also allows you to not worry about ports and hosts for your backend server in your client code, or CORS issues.
flowchart LR subgraph c[localhost:8080] js>Fable-compiled JS] vite(Vite dev server) js -- hot module replacement --- vite end subgraph s[localhost:5000] dotnet(dotnet watch run) saturn(Saturn on Kestrel) saturn --- dotnet end c -- /api redirect --> s"},{"location":"faq/faq-build/#running-safe-applications-in-production","title":"Running SAFE applications in production","text":"In a production environment, you won't need the Vite dev server. Instead, Vite is used as a one-off compiler step to create your bundled JavaScript from your Fable app (plus dependencies), and then deploy this along with your backend web server which also hosts that content directly. For example, you can use Saturn to host the static content required by the application e.g. HTML, JS and CSS files etc. as well as your backend APIs. This fits very well with standard CI / CD processes, as a build step in your Build.fs or Azure DevOps / AppVeyor / Travis step etc.
flowchart BT subgraph dest[Web server e.g. https://contoso.com] saturn(Saturn myapp.dll) db[(transactional data)] assets>static assets] saturn -- api/customers --- db saturn -- bundle.js --- assets end subgraph src[CI/CD Server] exec>deployment script] vite(Vite) dotnet(dotnet publish) source(F# source code) exec -- bundle.js --- vite exec -- myapp.dll --- dotnet vite --- source dotnet --- source end src -- file copy --> dest"},{"location":"faq/faq-build/#client-asset-hosting-alternatives","title":"Client asset hosting alternatives","text":"Rather than hosting your client-side content and application inside your web server, you can opt to host your static content from some other service that supports hosting of HTTP content, such as Azure Blobs, or a content hosting service. In such a case, you'll need to consider how to route traffic to your back-end API from your client application (as they are hosted on different domains), as well as handle any potential CORS issues.
"},{"location":"faq/faq-troubleshooting/","title":"Troubleshooting","text":""},{"location":"faq/faq-troubleshooting/#run-error-due-to-nodenpm-version","title":"Run error due to node/npm version","text":"You may receive an error when trying to run the app, e.g. the current version might require {\"node\":\"~18 || ~20\",\"npm\":\"~9 || ~10\"} but your locally installed versions are different. Ideally we'd like to install different versions side-by-side, which we can do using Node Version Manager.
Once NVM is installed, identify the version of Node that you'd like to install by checking this matrix. For our example here we can identify version 20.10.0 as satifying both the Node and npm version requirements. To install this version for the current project run:
nvm install 20.10.0\nnvm use 20.10.0\nThe output from these commands will also tell you which version of npm is linked to the Node version, but if you do not currently have that version of npm installed you need to install it manually with the command:
npm install -g npm@10.2.4\nThe version numbers may vary depending on the SAFE Stack version you are using.
You should now be able to run the app successfully.
"},{"location":"faq/faq-troubleshooting/#socketprotocolerror-in-debug-console","title":"SocketProtocolError in Debug Console","text":"You may see the following SocketProtocolError message in the Debug Console once you have started your SAFE application.
WebSocket connection to 'ws://localhost:8000/socketcluster/' failed: Error during WebSocket handshake: Unexpected response code: 404
Whilst these messages can be safely ignored, you can eliminate them by installing Redux Dev Tools in the launched Chrome instance as described in the debugging prerequisites section.
"},{"location":"faq/faq-troubleshooting/#node-process-does-not-stop-after-stopping-the-vs-code-debugger","title":"Node Process does not stop after stopping the VS Code debugger","text":"VS Code does not kill the Fable process when you stop the debugger, leaving it running as a \"zombie\". In such a case, you will have to explicitly kill the process otherwise it will hold onto port 8080 and prevent you starting new instances. This should be easily doable by sending Ctrl+C in the Terminal window in VS Code for Watch Client task. Tracked here.
A project created from SAFE template might issue the following warning from Webpack upon building the JavaScript bundle:
WARNING in entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (244 KiB). This can impact web performance.\nWe're striving to optimise the bundle size, however with a number of different options and dependencies it's not that easy to stay below the Webpack recommended limit.
To minimize the bundle size in your project you can try restricting browser compatibility by modifying the Babel Preset targets for Browserslist and thus using less polyfills.
For more info, see this issue.
"},{"location":"faq/faq-troubleshooting/#server-port-change","title":"Server port change","text":"The port that the server runs on changed from 8085 to 5000 (the ASP.NET Core default) in v4 of the SAFE Template. This was to make it compatible with deployment to Azure App Service on Linux.
"},{"location":"features/feature-azurefunctions/","title":"Working with Azure functions","text":""},{"location":"features/feature-azurefunctions/#going-serverless-with-safe","title":"Going serverless with SAFE","text":"With SAFE-Stack you can easily take advantage of serverless computing via Azure Functions.
With Functions-As-A-Service (FAAS) you can focus on building your business logic and don't need to worry about provisioning and maintaining servers (hence \"serverless\"). Azure Functions provide a managed compute platform with high reliability. If you use a \"consumption plan\" it scales on demand and you only get billed for the actual runtime of your code.
"},{"location":"features/feature-azurefunctions/#potential-use-cases","title":"Potential use cases","text":"For SAFE apps we see various use cases for FAAS:
The Azure Portal allows you to create and edit Functions and their source code via an online editor.
For a short test go to the portal, click the \"New\" button and search for \"Function App\". Click through the wizard to create a new Function App. Open the app when it's created and add a new function. Pick \"Timer\" as scenario and F# as language.
Replace the contents of function.json with:
{\n\"bindings\": [\n {\n \"name\": \"myTimer\",\n \"type\": \"timerTrigger\",\n \"direction\": \"in\",\n \"schedule\": \"0 * * * * *\"\n }\n],\n\"disabled\": false\n}\nand replace the run.fsx with the following F# code:
open System\n\nlet minutesSince (d: DateTime) =\n(DateTime.Now - d).TotalMinutes\n\nlet run(myTimer: TimerInfo, log: TraceWriter) =\nlet meetupStart = new DateTime(2017, 11, 8, 19, 0, 0)\n\nminutesSince meetupStart\n|> int\n|> sprintf \"Our meetup has been running for %d minutes\"\n|> log.Info\nNow observe the logs to see that the function runs every minute and outputs the message about the meetup duration.
While it seems very convenient, the online editor should only be used for testing and prototyping. In SAFE-Stack you usually benefit from reusing your domain model at various places see Client/Server - so we recommend to use \"precompiled Azure Functions\" as described below.
"},{"location":"features/feature-azurefunctions/#deployment","title":"Deployment","text":"In SAFE-Stack scenarios we recommend all deployments should be automated. Here, we discuss two options for deploying your functions apps into Azure.
"},{"location":"features/feature-azurefunctions/#azure-functions-core-tools","title":"Azure Functions Core Tools","text":"In the case of Function Apps the excellent Azure Functions Core Tools can be used. If you use core tools version 2 then the following should be added to your build/deploy script:
dotnet publish -c Release\nfunc azure functionapp publish [FunctionApp Name]\nThis will compile your Function App in release mode and push it to the Azure portal.
In the case of a CI server etc., you will need to install the Functions Core Tools on the server and once per functions app log into the CI machine and explicitly authenticate it manually (see the Functions Core Tools docs).
"},{"location":"features/feature-azurefunctions/#https-upload","title":"HTTPS Upload","text":"Since Azure Functions sits on top of Azure App Service, the same mechanisms for deployment there also exist here. In this case, you can use the exact same HTTPS upload capabilities of the App Service to upload a zip of your functions app into your Functions app. The standard SAFE Template can generate this for you for the core SAFE application as part of the FAKE script; the exact same mechanism can be utilised for your functions app.
As per the standard App Service, HTTPS upload uses a user/pass supplied in the header of the zip which is PUT into the functions app. This user / pass can be taken from the App Service in the Azure Portal directly, or extracted during deployment of your ARM template (as per the FAKE script does for the App Service).
"},{"location":"features/feature-clientserver-basics/","title":"Sharing Types and Code","text":""},{"location":"features/feature-clientserver-basics/#sharing-types","title":"Sharing Types","text":"Sharing your domain types and contracts between client and server is extremely simple. Thanks to Fable's excellent F# transpilation into JavaScript, you can use all standard F# language features such as Records, Tuples and Discriminated Unions without worry. To share types across both your client and server project, first create a project in your repository called e.g Shared.fsproj. This project will contain any assets that should be shared across the client and server e.g. types and functions.
Then, create files with your types in the project as needed e.g
type Customer = { Id : int; Name : string }\nReference this project from your server project. You can now reference those types on the server.
<Project Sdk=\"Microsoft.NET.Sdk\">\n...\n <ItemGroup>\n<ProjectReference Include=\"..\\Shared\\Shared.fsproj\" />\n</ItemGroup>\n...\n</Project>\nFinally, reference this project in your client project (as above). You can now reference those types on the client; Fable will automatically convert your F# types into JavaScript in the background.
"},{"location":"features/feature-clientserver-basics/#sharing-behaviour","title":"Sharing Behaviour","text":"You can also share behaviour using the same mechanism at that for sharing types. This is extremely useful for e.g shared validation or business logic that needs to occur on both client and server.
Fable will translate your functions into native JavaScript, and will even translate many calls to the .NET base class library into corresponding JavaScript! This allows you to compile your domain model and domain logic to many many different targets including:
You can read more about this on the Fable website.
"},{"location":"features/feature-clientserver-basics/#conditional-sharing","title":"Conditional sharing","text":"When sharing assets between client and server, you may wish to have different implementations for the \"client\" and \"server\" sides. For example, if the client-side version of a function should call an NPM package but the server-side version should use a NuGet package. This is a more advanced scenario where you may require different implementations for the JS and .NET version of code. In such situations, you can use #IF directives to conditionally compile code for either platform - see the Fable website for more information.
Using F# on both client and server is at the core of the SAFE stack, as it simplifies the way we think about building web applications by using the same language, idioms and in many cases sharing our code and domain models.
However, building a client and a server app requires a fundamentally different way of thinking. On the server side we build stateless APIs in Saturn that map HTTP requests to internal functionality, whereas on the frontend we use the Elmish model, implementing the model-view-update pattern: a stateful pattern that lets us think about the application state as it evolves while the application is running.
Even though we use the same language across platforms, applying these two different programming models forces us to switch our way of thinking back and forth when writing code for the client and for the server. This is where the Elmish.Bridge library comes into play: it brings the Elmish programming model to the server and unifies the way we write the application as a whole.
"},{"location":"features/feature-clientserver-bridge/#how-does-elmish-work-on-the-server","title":"How does Elmish work on the server?","text":"Think of Elmish on the server as the model-view-update pattern but without the view part. Instead, you only need to implement init and update functions to manage the server state as it evolves while the server is running.
update functions on client and server can exchange data via message passing.Let's see a simple example of how this might work in practice:
// Client-side\nlet update msg state =\nmatch msg with\n| LoadUsers ->\n// send the message to the server\nstate, Cmd.bridgeSend ServerMsg.LoadUsers\n| UsersLoaded users ->\n// receive message from the server\nlet nextState = { state with Users = users }\nnextState, Cmd.none\n\n// Server-side\nlet update clientDispatch msg state =\nmatch msg with\n| ServerMsg.LoadUsers ->\nlet loadUsersCmd =\nCmd.ofAsync\ngetUsersFromDb // unit -> Async<User list>\n() // input arg = unit\nUsersLoadedFromDb // User list -> ServerMsg\nDoNothing // ServerMsg\nstate, loadUsersCmd\n\n| ServerMsg.UsersLoadedFromDbSuccess users ->\n// answer the current connected client with data\nclientDispatch (ClientMsg.UsersLoaded users)\nstate, Cmd.none\n\n| ServerMsg.DoNothing ->\nstate, Cmd.none\nThe above example mimics what would have been a GET request to the server to get user data from database. However, now the client sends a fire-and-forget message to the server to load users, and at some point the server messages the current client back with the results. Notice that the server could have decided to do other things than just messaging the client back: for example, it could have broadcasted the same message to other clients updating their local state of the users.
There are many scenarios where it makes sense to use Elmish.Bridge:
The biggest distinction between using this and \"raw\" Saturn is that your web server becomes a stateful service. This introduces several differences for application design.
The server state has a lifespan equal to the that of the process under which the server instance is running. This means if the server application restarts then the server state will be reset.
The server state is local to the server instance. This means that if you run multiple web servers, they won't be sharing the same server state by default.
As of now there is no built-in persistence for the state, but you can implement this yourself using any number of persistance layers such as Redis Cache, Azure Tables or Blobs etc.
In addition Elmish.Bridge does not use standard HTTP verbs for communication, but rather websockets. Therefore, it is not a suitable technology for an open web server that can serve requests from other sources than Elmish.Bridge clients.
"},{"location":"features/feature-clientserver-bridge/#learn-more-about-elmishbridge","title":"Learn more about Elmish.Bridge","text":"Head over to Elmish.Bridge to learn more.
"},{"location":"features/feature-clientserver-http/","title":"Client Server communication over HTTP","text":"Communicating over raw HTTP using Saturn has three main steps.
"},{"location":"features/feature-clientserver-http/#1-load-your-data","title":"1. Load your data","text":"Start by creating a function on your server that returns some data:
let loadCustomersFromDb() =\n[ { Id = 1; Name = \"Joe Bloggs\" } ]\n/// Returns the results of loadCustomersFromDb as JSON.\nlet getCustomers next ctx =\njson (loadCustomersFromDb()) next ctx\nYou can opt to combine both of the above functions into one, depending on your preferences, but it's often good practice to separate your data access from serving data in HTTP endpoints.
Also note the next and ctx arguments. These are used by Giraffe as part of its HTTP pipeline and are required by the json function (Note you can also use Successful.Ok instead of json, which will offer XML serialization as well).
Now expose the api method using Saturn's router construct and add it to your overall application scope:
let myApis = router {\nget \"/api/customers/\" getCustomers\n}\nFor simple endpoints you may elect to embed the API call directly in the scope (and use partial application to omit the next and ctx arguments):
let myApis = router {\nget \"/api/customers/\" (json (loadCustomersFromDb()))\n}\nFinally, call the endpoint from your client application.
promise { let! customers = Fetch.fetchAs<Customer list> \"api/customers\" (Decode.Auto.generateDecoder()) []\n// do more with customers here...\n}\nNote the use of the promise { } computation expression. This behaves similarly to async { } blocks that you might already know, whilst the fetchAs function retrieves data from the HTTP endpoint specified. The JSON is deserialized as a Customer array using an automatically-generated \"decoder\" (see the section on serialization for more information).
Alongside raw HTTP, you can also use Fable.Remoting, which provides an RPC-style mechanism for calling server endpoints. With Remoting, you don't need to worry about the details of serialization or of how to consume the endpoint - instead, remoting lets you define you client-server interactions as a shared type that is commonly referred to as a protocol or contract.
"},{"location":"features/feature-clientserver-remoting/#1-define-a-protocol","title":"1. Define a protocol","text":"Each field of the record is either of type Async<T> or a function that returns Async<T>, for example:
type ICustomerApi = {\ngetCustomers : unit -> Async<Customer list>\nfindCustomerByName : string -> Async<Customer option>\n}\nOn the server you would implement the protocol as follows:
let getCustomers() =\nasync {\nreturn [\n{ Id = 1; Name = \"John Doe\" }\n{ Id = 2; Name = \"Jane Smith\" } ]\n}\n\nlet findCustomerByName (name: string) = async {\nlet! allCustomers = getCustomers()\nreturn allCustomers |> List.tryFind (fun c -> c.Name = name)\n}\n\n\nlet customerApi : ICustomerApi = {\ngetCustomers = getCustomers\nfindCustomerByName = findCustomerByName\n}\nAfter exposing an HttpHandler from customerApi you can start calling the API from the client.
let api = Remoting.createApi() |> Remoting.buildProxy<ICustomerApi>\n\nasync {\nlet! customers = api.getCustomers()\nfor customer in customers do\nprintfn \"#%d => %s\" customer.Id customer.Name\n}\nNotice here, there is no need to configure routes or JSON serialization, worry about HTTP verbs, or even involve yourself with the Giraffe pipeline. If you open your browser network tab, you can easily inspect what remoting is doing behind the scenes.
"},{"location":"features/feature-clientserver-serialization/","title":"Serialization in SAFE","text":""},{"location":"features/feature-clientserver-serialization/#serialization-basics-with-thoth","title":"Serialization basics with Thoth","text":"If you are using the standard SAFE Template (V3 +), you do not need to worry about serialization, as this is taken care of for you by Fable Remoting. However, if you are \"rolling your own\" communication channel or want to create an \"open\" API for multiple consumers, this article may be relevant for you.
When using basic HTTP communication between the client and server, you'll need to consider how to deserialize data from JSON to F# types.
In order to guarantee that the serialization / deserialization routines between client and server are compatible, you should replace the JSON converter in Giraffe / Saturn with the Thoth library's serializer. This is the same library as that used in Fable for deserialization, and so will work seamlessly together.
let configureSerialization (services:IServiceCollection) =\nservices.AddSingleton<Giraffe.Serialization.Json.IJsonSerializer>(Thoth.Json.Giraffe.ThothSerializer())\nThe Thoth library makes use of decoders to convert JSON into F# values. There are generally two main approaches to take when doing this: automatic and manual decoders.
Assume the following Customer record for the remaining examples.
type Customer =\n{ Id : int\nName : string }\nAutomatic decoders are the quickest and easier way to deserialize data. It works by Thoth trying to decode JSON automatically from a raw string to an F# type using automatic mapping rules. In the sample below, we fetch data from the /api/customers endpoint and have Thoth create a strongly-typed Decoder for a Customer array.
fetchAs<Customer []> \"/api/customers\" (Decode.Auto.generateDecoder()) []\nIf the serialization fails, Thoth will create an Error (rather than Ok) value for this.
Be aware that automatic decoders are designed to work with primitives, collections, F# records, tuples and discriminated unions but cannot deserialize classes.
"},{"location":"features/feature-clientserver-serialization/#improving-efficiency-with-cached-decoders","title":"Improving efficiency with cached decoders","text":"You can reuse decoders when you know you'll be calling them often:
// let-bound value that exists outside of the update function\nlet customerDecoder = Decode.Auto.generateDecoder<Customer>()\n\n// inside the update function\nFetch.fetchAs (sprintf \"api/customers\") (Decode.array customerDecoder [])\nNotice how the decoder is bound to a single Customer, and not an array. This way, we can also reuse the decoder on other routes, for example api/customers/1 which would return a single Customer object rather than a collection.
Manual decoders give you total control over how you rehydrate an object from JSON. Use them when:
You create a manual decoder as follows:
let customerDecoder : Decoder<Customer> =\nDecode.object\n(fun get ->\n{ Id = get.Required.Field \"id\" Decode.int\nName = get.Optional.Field \"customerName\" Decode.string |> Option.defaultValue \"\" })\nYou can now replace the automatically generated decoder from earlier. You can also \"manually\" decode JSON to Customers as follows:
Decode.fromString customerDecoder \"\"\"{ \"id\": 67, \"customerName\": \"Joe Bloggs\" }\"\"\"\nIf decoding fails on any field, an error case will be returned.
"},{"location":"features/feature-clientserver/","title":"Sharing Overview","text":"One of the most powerful features of SAFE is the ability to seamlessly share code across client and server.
"},{"location":"features/feature-clientserver/#sharing-basics","title":"Sharing Basics","text":"The basics of code sharing across client and server include:
These two core areas are explained in more detail here.
"},{"location":"features/feature-clientserver/#sending-messages-between-client-and-server","title":"Sending messages between client and server","text":"In addition to types and messages, there are several technologies available in SAFE that allow you to send messages from client to server (and from server to client). Each has their own strengths and weaknesses:
Fable Remoting provides an excellent way to quickly get up and running with the SAFE stack. You can rapidly create contracts and have guaranteed type-safety between both client and server. Consider using remoting for rapid prototyping, since JSON serialization and HTTP routing is handled by the library, you only think of your client-server code in terms of types and stateless functions. Fable remoting is our recommended option for SAFE Stack apps where you \"own\" the client and server. However, if you need full control over the HTTP channel for returning specific status codes, using custom HTTP verbs or working with headers, then remoting might not for be you.
The raw HTTP model provided by Saturn with router { } requires you to construct routes manually and does not guarantee that the client and endpoint have the same contract (you have to specify the same type on both sides yourself). However, using the raw HTTP model gives you total control over the routing and verbs used. If you have a public API that is exposed not just to your own application but to third-parties, or you need more fine grained control over your routes and data, you should use this approach.
Lastly, Elmish.Bridge provides an alternative way of modelling client/server communication. Unlike the other two mechanisms, Elmish Bridge provides the same Elmish model on the server as well as the client, as well as the ability to send notifications from the server back to connected clients via websockets. However, the Bridge model is inherently stateful, which means that a server restart could impact all connected clients.
Fable.Remoting Raw HTTP Elmish.Bridge Client / Server support Very easy Easy Very Easy State model Stateless Stateless Stateful \"Open\" API? Yes, with limitations Yes No HTTP Verbs? POST, GET Fully Configurable None Push messages? No With Channels Yes Pipeline Control? Limited Full LimitedConsider using a combination of multiple endpoints supporting combinations of the above to suit your needs!
"},{"location":"features/feature-hmr/","title":"Hot Module Replacement","text":"Hot Module Replacement (HMR) allows to update the UI of an application while it is running, without a full reload. In SAFE stack apps, this can dramatically speed up the development for web and mobile GUIs, since there is no need to \"stop\" and \"reload\" an application. Instead, you can make changes to your views and have them immediately update in the browser, without the need to restart the application.
"},{"location":"features/feature-hmr/#how-does-it-work","title":"How does it work?","text":"In case of web development, the Vite development server will automatically refresh the changed parts of your elmish views whenever you save a file. Alternatively, in the case of mobile app development, this is achieved through React Native's own bundler.
"},{"location":"features/feature-hmr/#why-does-it-work-so-well-with-safe","title":"Why does it work so well with SAFE?","text":"Since SAFE uses the Model-View-Update architecture with immutable models, the application state only changes when a message is processed; this fits the HMR model very nicely. Here's an example of HMR in action to change the input of a textbox to automatically convert the input to upper case.
"},{"location":"features/feature-hmr/#further-reading","title":"Further reading","text":"Server-Side Rendering (SSR) means that some parts of your application code can run on both the server and the client. For React this means that you can render your components directly to HTML on the server side (e.g. via a node.js server), which allows for better search engine optimization (SEO) and gives a faster initial response, especially on mobile devices.
The browser typically receives a static HTML site and starts updating the UI immediately; React's bundle code will be downloaded asynchronously and when it completes, the client-side JavaScript will take over via React's hydrate functionality. In the JavaScript ecosystem this is also known as an \"isomorphic\" or \"universal\" app.
"},{"location":"features/feature-ssr/#why-use-ssr","title":"Why use SSR?","text":""},{"location":"features/feature-ssr/#pros","title":"Pros","text":"In SAFE, SSR can be done using fable-react. Its approach is a little different from those you might have seen in the JavaScript ecosystem, as it takes a purely F# approach: you render your Elmish views directly on .NET Core, with all the benefits of the .NET Core runtime.
"},{"location":"features/feature-ssr/#further-reading","title":"Further reading","text":"Follow the following pattern and headings and the guide below.
"},{"location":"recipes/template/#best-practices","title":"Best practices","text":"Start by writing a short introduction of a few sentences. Explain what the recipe is about, and problems it solves. Which technologies does it utilise, and what are the alternatives etc.?
Remember to link the first instance of any technology to the appropriate docs elsewhere within this site, or to the homepage of the technology (or both!).
"},{"location":"recipes/template/#step-by-step-guide","title":"Step-by-step Guide","text":"Write clear instructions on how to get to the desired outcome. The step-by-step instructions should be clear, short, easy to understand with possibly a use case and an example at the end if suitable.
If you have a step in this section that is relevant to some other recipe we have here in the docs, such as adding a package to a SAFE app, link it to that relevant page.
"},{"location":"recipes/build/add-build-script/","title":"How do I add build automation to the project?","text":""},{"location":"recipes/build/add-build-script/#fake","title":"FAKE","text":"Fake is a DSL for build tasks that is modular, extensible and easy to start with. Fake allows you to easily build, bundle, deploy your app and more by executing a single command.
The standard template comes with a FAKE project by default, so this recipe only applies to the minimal template.
"},{"location":"recipes/build/add-build-script/#1-create-a-build-project","title":"1. Create a build project","text":"Create a new console app called 'Build' at the root of your solution
dotnet new console -lang f# -n Build -o .\nWe are creating the project directly at the root of the solution in order to allow us to execute the build without needing to navigate into a subfolder.
"},{"location":"recipes/build/add-build-script/#2-create-a-build-script","title":"2. Create a build script","text":"Open the project you just created in your IDE and rename the module it contains from Program.fs to Build.fs.
This renaming isn't explicitly necessary, however it keeps your solution consistent with other SAFE apps and is a better name for the file really.
If you just rename the file directly rather than in your IDE, then the Build project won't be able to find it unless you edit the Build.fsproj file as well
Open Build.fs and paste in the following code.
open Fake.Core\nopen Fake.IO\nopen System\n\nlet redirect createProcess =\ncreateProcess\n|> CreateProcess.redirectOutputIfNotRedirected\n|> CreateProcess.withOutputEvents Console.WriteLine Console.WriteLine\n\nlet createProcess exe arg dir =\nCreateProcess.fromRawCommandLine exe arg\n|> CreateProcess.withWorkingDirectory dir\n|> CreateProcess.ensureExitCode\n\nlet dotnet = createProcess \"dotnet\"\n\nlet npm =\nlet npmPath =\nmatch ProcessUtils.tryFindFileOnPath \"npm\" with\n| Some path -> path\n| None -> failwith \"npm was not found in path.\"\ncreateProcess npmPath\n\nlet run proc arg dir =\nproc arg dir\n|> Proc.run\n|> ignore\n\nlet execContext = Context.FakeExecutionContext.Create false \"build.fsx\" [ ]\nContext.setExecutionContext (Context.RuntimeContext.Fake execContext)\n\nTarget.create \"Clean\" (fun _ -> Shell.cleanDir (Path.getFullName \"deploy\"))\n\nTarget.create \"InstallClient\" (fun _ -> run npm \"install\" \".\")\n\nTarget.create \"Run\" (fun _ ->\nrun dotnet \"build\" (Path.getFullName \"src/Shared\")\n[ dotnet \"watch run\" (Path.getFullName \"src/Server\")\ndotnet \"fable watch --run npx vite\" (Path.getFullName \"src/Client\") ]\n|> Seq.toArray\n|> Array.map redirect\n|> Array.Parallel.map Proc.run\n|> ignore\n)\n\nopen Fake.Core.TargetOperators\n\nlet dependencies = [\n\"Clean\"\n==> \"InstallClient\"\n==> \"Run\"\n]\n\n[<EntryPoint>]\nlet main args =\ntry\nmatch args with\n| [| target |] -> Target.runOrDefault target\n| _ -> Target.runOrDefault \"Run\"\n0\nwith e ->\nprintfn \"%A\" e\n1\nRun the following command
dotnet sln add Build.fsproj\nYou will need to install the following dependencies:
Fake.Core.Target\nFake.IO.FileSystem\nWe recommend migrating to Paket. It is possible to use FAKE without Paket, however this will not be covered in this recipe.
"},{"location":"recipes/build/add-build-script/#5-run-the-app","title":"5. Run the app","text":"At the root of the solution, run dotnet paket install to install all your dependencies.
If you now execute dotnet run, the default target will be run. This will build the app in development mode and launch it locally.
To learn more about targets and FAKE in general, see Getting Started with FAKE.
"},{"location":"recipes/build/bundle-app/","title":"How do I bundle my SAFE application?","text":"When developing your SAFE application, the local runtime experience uses Vite to run the client and redirect API calls to the server on a different port. However, when you deploy your application, you'll need to run your Saturn server which will serve up statically-built client resources (HTML, JavaScript, CSS etc.).
"},{"location":"recipes/build/bundle-app/#1-run-the-fake-script","title":"1. Run the FAKE script","text":"If you created your SAFE app using the recommended defaults, your application already has a FAKE script which will do the bundling for you. You can create a bundle using the following command:
dotnet run Bundle\nThis will build and package up both the client and server and place them into the /deploy folder at the root of the repository.
See here for more details on this build target.
"},{"location":"recipes/build/bundle-app/#testing-the-bundle","title":"Testing the bundle","text":"deploy folder at the root of your repository.Server.exe application.http://localhost:5000.You should now see your SAFE application.
"},{"location":"recipes/build/bundle-app/#further-reading","title":"Further reading","text":"See this article for more information on architectural concerns regarding the move from dev to production and bundling SAFE Stack applications.
"},{"location":"recipes/build/docker-image/","title":"How do I build with docker?","text":"Using Docker makes it possible to deploy your application as a docker container or release an image on docker hub. This recipe walks you through creating a Dockerfile and automating the build and test process with Docker Hub.
Create a .dockerignore file with the same contents as .gitignore
cp .gitignore .dockerignore\ncopy .gitignore .dockerignore\nNow, add the following lines to the .dockerignore file:
.git\nCreate a Dockerfile with the following contents:
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build\n\n# Install node\nARG NODE_MAJOR=20\nRUN apt-get update\nRUN apt-get install -y ca-certificates curl gnupg\nRUN mkdir -p /etc/apt/keyrings\nRUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg\nRUN echo \"deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main\" | tee /etc/apt/sources.list.d/nodesource.list\nRUN apt-get update && apt-get install nodejs -y\n\nWORKDIR /workspace\nCOPY . .\nRUN dotnet tool restore\nRUN dotnet run Bundle\n\nFROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine\nCOPY --from=build /workspace/deploy /app\nWORKDIR /app\nEXPOSE 5000\nENTRYPOINT [ \"dotnet\", \"Server.dll\" ]\nThis uses multistage builds to keep the final image small.
"},{"location":"recipes/build/docker-image/#3-building-and-running-with-docker-locally","title":"3. Building and running with docker locally","text":"docker build -t my-safe-app .docker run -it -p 8080:8080 my-safe-appBecause the build is done entirely in docker, Docker Hub automated builds can be setup to automatically build and push the docker image.
"},{"location":"recipes/build/docker-image/#4-testing-the-server","title":"4. Testing the server","text":"Create a docker-compose.server.test.yml file with the following contents:
version: '3.4'\nservices:\n sut:\n build:\n target: build\n context: .\n working_dir: /workspace/tests/Server\n command: dotnet run\ndocker-compose -f docker-compose.server.test.yml up --build The template is not currently setup for automating the client tests in ci.
Docker Hub can also run automated tests for you.
Follow the instructions to enable Autotest on docker hub.
"},{"location":"recipes/build/docker-image/#5-making-the-docker-build-faster","title":"5. Making the docker build faster","text":"Not recommended for most applications
If you often build with docker locally, you may wish to make the build faster by optimising the Dockerfile for caching. For example, it is not necessary to download all paket and npm dependencies on every build unless there have been changes to the dependencies.
Furthermore, the client and server can be built in separate build stages so that they are cached independently. Enable Docker BuildKit to build them concurrently.
This comes at the expense of making the dockerfile more complex; if any changes are made to the build such as adding new projects or migrating package managers, the dockerfile must be updated accordingly.
The following should be a good starting point but is not guaranteed to work.
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build\n\n# Install node\nARG NODE_MAJOR=20\nRUN apt-get update\nRUN apt-get install -y ca-certificates curl gnupg\nRUN mkdir -p /etc/apt/keyrings\nRUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg\nRUN echo \"deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main\" | tee /etc/apt/sources.list.d/nodesource.list\nRUN apt-get update && apt-get install nodejs -y\n\nWORKDIR /workspace\nCOPY .config .config\nRUN dotnet tool restore\nCOPY .paket .paket\nCOPY paket.dependencies paket.lock ./\n\nFROM build as server-build\nCOPY src/Shared src/Shared\nCOPY src/Server src/Server\nRUN cd src/Server && dotnet publish -c release -o ../../deploy\n\nFROM build as client-build\nCOPY package.json package-lock.json ./\nRUN npm install\nCOPY src/Shared src/Shared\nCOPY src/Client src/Client\n# tailwind.config.js needs to be in the dir where the\n# vite build command is run from otherwise styles will\n# be missing from the bundle\nCOPY src/Client/tailwind.config.js .\nRUN dotnet fable src/Client --run npx vite build src/Client\n\nFROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine\nCOPY --from=server-build /workspace/deploy /app\nCOPY --from=client-build /workspace/deploy /app\nWORKDIR /app\nEXPOSE 5000\nENTRYPOINT [ \"dotnet\", \"Server.dll\" ]\nFAKE is a tool for build automation. The standard SAFE template comes with a ready-made build project at the root of the solution that provides support for many common SAFE tasks.
If you would prefer not to use FAKE, you can of course simply ignore it, but this recipes shows how to completely remove it from your repository. It is important to note that having removed FAKE, you will have to follow a more manual approach to each of these processes. This recipe will only include instructions on how to run the application after removing FAKE.
Note that the minimal template does not use FAKE by default, and this recipe only applies to the standard template.
"},{"location":"recipes/build/remove-fake/#1-build-project","title":"1. Build project","text":"Delete Build.fs, Build.fsproj, Helpers.fs, paket.references at the root of the solution.
Remove the following dependencies
dotnet paket remove Fake.Core.Target\ndotnet paket remove Fake.IO.FileSystem\ndotnet paket remove Farmer\nNow that you have removed the FAKE application dependencies, you will have to separately run the server and the client.
"},{"location":"recipes/build/remove-fake/#1-start-the-server","title":"1. Start the Server","text":"Navigate to src/Server inside a terminal and execute dotnet run.
Navigate to src/Client inside a terminal and execute the following:
dotnet tool restore\nnpm install\ndotnet fable watch -o output -s --run npx vite\nThe app will now be running at http://localhost:8080/. Navigate to this address in a browser to see your app running.
See this guide to learn how to package a SAFE application for deployment to e.g. Azure.
"},{"location":"recipes/client-server/fable-remoting/","title":"How Do I Add Support for Fable Remoting?","text":"Fable Remoting is a type-safe RPC communication layer for SAFE apps. It uses HTTP behind the scenes, but allows you to program against protocols that exist across the application without needing to think about the HTTP plumbing, and is a great fit for the majority of SAFE applications.
Note that the standard template uses Fable Remoting. This recipe only applies to the minimal template.
"},{"location":"recipes/client-server/fable-remoting/#1-install-nuget-packages","title":"1. Install NuGet Packages","text":"Add Fable.Remoting.Giraffe to the Server and Fable.Remoting.Client to the Client.
See How Do I Add a NuGet Package to the Server and How Do I Add a NuGet Package to the Client.
"},{"location":"recipes/client-server/fable-remoting/#2-create-the-api-protocol","title":"2. Create the API protocol","text":"You now need to create the protocol, or contract, of the API we\u2019ll be creating. Insert the following below the Route module in Shared.fs:
type IMyApi =\n{ hello : unit -> Async<string> }\nWe need to provide a basic routing function in order to ensure client and server communicate on the same endpoint. Find the Route module in src/Shared/Shared.fs and replace it with the following:
module Route =\nlet builder typeName methodName =\nsprintf \"/api/%s/%s\" typeName methodName\nWe now need to provide an implementation of the protocol on the server. Open src/Server/Server.fs and insert the following right after the open statements:
let myApi =\n{ hello = fun () -> async { return \"Hello from SAFE!\" } }\nWe now need to \"adapt\" Fable Remoting into the ASP.NET pipeline by converting it into a Giraffe HTTP Handler. Don't worry - this is not hard. Find webApp in Server.fs and replace it with the following:
open Fable.Remoting.Server\nopen Fable.Remoting.Giraffe\n\nlet webApp =\nRemoting.createApi()\n|> Remoting.withRouteBuilder Route.builder // use the routing function from step 3\n|> Remoting.fromValue myApi // use the myApi implementation from step 4\n|> Remoting.buildHttpHandler // adapt it to Giraffe's HTTP Handler\nWe now need a corresponding client proxy in order to be able to connect to the server. Open src/Client/Client.fs and insert the following right after the Msg type:
open Fable.Remoting.Client\n\nlet myApi =\nRemoting.createApi()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.buildProxy<IMyApi>\nReplace the following two lines in the init function in Client.fs:
let getHello() = Fetch.get<unit, string> Route.hello\nlet cmd = Cmd.OfPromise.perform getHello () GotHello\nwith this:
let cmd = Cmd.OfAsync.perform myApi.hello () GotHello\nAt this point, the app should work just as it did before. Now, expanding the API and adding a new endpoint is as easy as adding a new field to the API protocol we defined in Shared.fs, editing the myApi record in Server.fs with the implementation, and finally making calls from the proxy.
First off, you need to create a SAFE app, install the relevant dependencies, and wire them up to be available for use in your F# Fable code.
dotnet new SAFE\ndotnet tool restore\nAdd bulma to your project: follow this recipe
Install Fable.Form.Simple.Bulma using Paket:
dotnet paket add Fable.Form.Simple.Bulma -p Client\nInstall bulma and fable-form-simple-bulma npm packages:
npm add fable-form-simple-bulma\nnpm add bulma\nRename src/Client/Index.css to Index.scss
Update the import in App.fs
...\nimportSideEffects \"./index.scss\"\n...\n...\n- importSideEffects \"./index.css\"\n+ importSideEffects \"./index.scss\"\n...\nImport bulma and fable-form-simple in Index.scss
@import \"bulma/bulma.sass\";\n@import \"fable-form-simple-bulma/index.scss\";\n...\nRemove the Bulma stylesheet link from ./src/Client/index.html, as it is no longer needed:
<link rel=\"icon\" type=\"image/png\" href=\"/favicon.png\"/>\n- <link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\">\n <link rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css\">\nWith the above preparation done, you can use Fable.Form.Simple.Bulma in your ./src/Client/Index.fs file.
Open the newly added namespaces:
Index.fsopen Fable.Form.Simple\nopen Fable.Form.Simple.Bulma\nCreate type Values to represent each input field on the form (a single textbox), and create a type Form which is an alias for Form.View.Model<Values>:
type Values = { Todo: string }\ntype Form = Form.View.Model<Values>\nIn the Model type definition, replace Input: string with Form: Form
type Model = { Todos: Todo list; Form: Form }\n-type Model = { Todos: Todo list; Input: string }\n+type Model = { Todos: Todo list; Form: Form }\nUpdate the init function to reflect the change in Model:
let model = { Todos = []; Form = Form.View.idle { Todo = \"\" } }\n-let model = { Todos = []; Input = \"\" }\n+let model = { Todos = []; Form = Form.View.idle { Todo = \"\" } }\nChange Msg discriminated union - replace the SetInput case with FormChanged of Form, and add string data to the AddTodo case:
type Msg =\n| GotTodos of Todo list\n| FormChanged of Form\n| AddTodo of string\n| AddedTodo of Todo\ntype Msg =\n | GotTodos of Todo list\n- | SetInput of string\n- | AddTodo\n+ | FormChanged of Form\n+ | AddTodo of string\n | AddedTodo of Todo\nModify the update function to handle the changed Msg cases:
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch msg with\n| GotTodos todos -> { model with Todos = todos }, Cmd.none\n| FormChanged form -> { model with Form = form }, Cmd.none\n| AddTodo todo ->\nlet todo = Todo.create todo\nlet cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\nmodel, cmd\n| AddedTodo todo ->\nlet newModel =\n{ model with\nTodos = model.Todos @ [ todo ]\nForm =\n{ model.Form with\nState = Form.View.Success \"Todo added\"\nValues = { model.Form.Values with Todo = \"\" } } }\nnewModel, Cmd.none\nlet update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\n match msg with\n | GotTodos todos -> { model with Todos = todos }, Cmd.none\n- | SetInput value -> { model with Input = value }, Cmd.none\n+ | FormChanged form -> { model with Form = form }, Cmd.none\n- | AddTodo ->\n- let todo = Todo.create model.Input\n- let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n- { model with Input = \"\" }, cmd\n+ | AddTodo todo ->\n+ let todo = Todo.create todo\n+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n+ model, cmd\n- | AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none\n+ | AddedTodo todo ->\n+ let newModel =\n+ { model with\n+ Todos = model.Todos @ [ todo ]\n+ Form =\n+ { model.Form with\n+ State = Form.View.Success \"Todo added\"\n+ Values = { model.Form.Values with Todo = \"\" } } }\n+ newModel, Cmd.none\nCreate form. This defines the logic of the form, and how it responds to interaction:
let form : Form.Form<Values, Msg, _> =\nlet todoField =\nForm.textField\n{\nParser = Ok\nValue = fun values -> values.Todo\nUpdate = fun newValue values -> { values with Todo = newValue }\nError = fun _ -> None\nAttributes =\n{\nLabel = \"New todo\"\nPlaceholder = \"What needs to be done?\"\nHtmlAttributes = []\n}\n}\n\nForm.succeed AddTodo\n|> Form.append todoField\nIn the function todoAction, remove the existing form view. Then replace it using Form.View.asHtml to render the view:
let private todoAction model dispatch =\nForm.View.asHtml\n{\nDispatch = dispatch\nOnChange = FormChanged\nAction = Action.SubmitOnly \"Add\"\nValidation = Validation.ValidateOnBlur\n}\nform\nmodel.Form\n let private todoAction model dispatch =\n- Html.div [\n- ...\n- ]\n+ Form.View.asHtml\n+ {\n+ Dispatch = dispatch\n+ OnChange = FormChanged\n+ Action = Action.SubmitOnly \"Add\"\n+ Validation = Validation.ValidateOnBlur\n+ }\n+ form\n+ model.Form\nWith the basic structure in place, it's easy to add functionality to the form. For example, the changes necessary to add a high priority checkbox are pretty small.
"},{"location":"recipes/client-server/messaging-post/","title":"How do I send and receive data using POST?","text":"This recipe shows how to create an endpoint on the server and hook up it up to the client using HTTP POST. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
A POST endpoint is normally used to send data from the client to the server in the body, for example from a form. This is useful when we need to supply more data than can easily be provided in the URI.
You may wish to use POST for \"write\" operations and use GETs for \"reads\", however this is a highly opinionated topic that is beyond the scope of this recipe.
"},{"location":"recipes/client-server/messaging-post/#im-using-the-standard-template-fable-remoting","title":"I'm using the standard template (Fable Remoting)","text":"Fable Remoting takes care of deciding whether to use POST or GET etc. - you don't have to worry about this. Refer to this recipe for more details.
"},{"location":"recipes/client-server/messaging-post/#im-using-the-minimal-template-raw-http","title":"I'm using the minimal template (Raw HTTP)","text":""},{"location":"recipes/client-server/messaging-post/#in-shared","title":"In Shared","text":""},{"location":"recipes/client-server/messaging-post/#1-create-contract","title":"1. Create contract","text":"Create the type that will store the payload sent from the client to the server.
type SaveCustomerRequest =\n{ Name : string\nAge : int }\nCreate a new function saveCustomer that will call the server. It supplies the customer to save, which is serialized and sent to the server in the body of the message.
let saveCustomer customer =\nlet save customer = Fetch.post<SaveCustomerRequest, int> (\"/api/customer\", customer)\nCmd.OfPromise.perform save customer CustomerSaved\nThe generic arguments of Fetch.post are the input and output types. The example above shows that the input is of type SaveCustomerRequest with the response will contain an integer value. This may be the ID generated by the server for the save operation.
This can now be called from within your update function e.g.
| SaveCustomer request ->\nmodel, saveCustomer request\n| CustomerSaved generatedId ->\n{ model with GeneratedCustomerId = Some generatedId; Message = \"Saved customer!\" }, Cmd.none\nCreate a function that can extract the payload from the body of the request using Giraffe's built-in model binding support:
open FSharp.Control.Tasks\nopen Giraffe\nopen Microsoft.AspNetCore.Http\nopen Shared\n\n/// Extracts the request from the body and saves to the database.\nlet saveCustomer next (ctx:HttpContext) = task {\nlet! customer = ctx.BindModelAsync<SaveCustomerRequest>()\ndo! Database.saveCustomer customer\nreturn! Successful.OK \"Saved customer\" next ctx\n}\nTie your function into the router, using the post verb instead of get.
let webApp = router {\npost \"/api/customer\" saveCustomer // Add this\n}\nThis recipe shows how to create an endpoint on the server and hook up it up to the client. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
"},{"location":"recipes/client-server/messaging/#im-using-the-standard-template-fable-remoting","title":"I'm using the standard template (Fable Remoting)","text":"Fable Remoting is a library which allows you to create client/server messaging without any need to think about HTTP verbs or serialization etc.
"},{"location":"recipes/client-server/messaging/#in-shared","title":"In Shared","text":""},{"location":"recipes/client-server/messaging/#1-update-contract","title":"1. Update contract","text":"Add your new endpoint onto an existing API contract e.g. ITodosApi. Because Fable Remoting exposes your API through F# on client and server, you get type safety across both.
type ITodosApi =\n{ getCustomer : int -> Async<Customer option> }\nCreate a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required.
let loadCustomer customerId = async {\nreturn Some { Name = \"My Customer\" }\n}\nNote the use of async here. Fable Remoting uses async workflows, and not tasks. You can write functions that use task, but will have to at some point map to async using Async.AwaitTask.
Tie the function you've just written into the API implementation.
let todosApi =\n{ ///...\ngetCustomer = loadCustomer\n}\nTest out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc. See here for more details on the required format.
"},{"location":"recipes/client-server/messaging/#on-the-client","title":"On the client","text":""},{"location":"recipes/client-server/messaging/#1-call-the-endpoint","title":"1. Call the endpoint","text":"Create a new function loadCustomer that will call the endpoint.
let loadCustomer customerId =\nCmd.OfAsync.perform todosApi.getCustomer customerId LoadedCustomer\nNote the final value supplied, CustomerLoaded. This is the Msg case that will be sent into the Elmish loop once the call returns, with the returned data. It should take in a value that matches the type returned by the Server e.g. CustomerLoaded of Customer option. See here for more information.
This can now be called from within your update function e.g.
| LoadCustomer customerId ->\nmodel, loadCustomer customerId\nThis recipe shows how to create a GET endpoint on the server and consume it on the client using the Fetch API.
"},{"location":"recipes/client-server/messaging/#on-the-server_1","title":"On the Server","text":""},{"location":"recipes/client-server/messaging/#1-write-implementation_1","title":"1. Write implementation","text":"Create a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required.
open Saturn\nopen FSharp.Control.Tasks\n\n/// Loads a customer from the DB and returns as a Customer in json.\nlet loadCustomer (customerId:int) next ctx = task {\nlet customer = { Name = \"My Customer\" }\nreturn! json customer next ctx\n}\nNote how we parameterise this function to take in the customerId as the first argument. Any parameters you need should be supplied in this manner. If you do not need any parameters, just omit them and leave the next and ctx ones.
This example does not cover dealing with \"missing\" data e.g. invalid customer ID is found.
"},{"location":"recipes/client-server/messaging/#2expose-your-function","title":"2.Expose your function","text":"Tie the function into the router with a route.
let webApp = router {\ngetf \"/api/customer/%i\" loadCustomer // Add this\n}\nNote the use of getf rather than get. If you do not need any parameters, just use get. See here for reference docs on the use of the Saturn router.
Test out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc.
"},{"location":"recipes/client-server/messaging/#on-the-client_1","title":"On the client","text":""},{"location":"recipes/client-server/messaging/#1-call-the-endpoint_1","title":"1. Call the endpoint","text":"Create a new function loadCustomer that will call the endpoint.
This example uses Thoth.Fetch to download and deserialise the response.
let loadCustomer customerId =\nlet loadCustomer () = Fetch.get<unit, Customer> (sprintf \"/api/customer/%i\" customerId)\nCmd.OfPromise.perform loadCustomer () CustomerLoaded\nNote the final value supplied, CustomerLoaded. This is the Msg case that will be sent into the Elmish loop once the call returns, with the returned data. It should take in a value that matches the type returned by the Server e.g. CustomerLoaded of Customer. See here for more information.
An alternative (and slightly more succinct) way of writing this is:
let loadCustomer customerId =\nlet loadCustomer = sprintf \"/api/customer/%i\" >> Fetch.get<unit, Customer>\nCmd.OfPromise.perform loadCustomer customerId CustomerLoaded\nThis can now be called from within your update function e.g.
| LoadCustomer customerId ->\nmodel, loadCustomer customerId\nThis recipe demonstrates the steps you need to take to store new data on the client using the MVU pattern, which is typically read from the Server. You will learn the steps required to modify the model, update and view functions to handle a button click which requests data from the server and handles the response.
"},{"location":"recipes/client-server/mvu-roundtrip/#in-shared","title":"In Shared","text":""},{"location":"recipes/client-server/mvu-roundtrip/#1-create-shared-domain","title":"1. Create shared domain","text":"Create a type in the Shared project which will act as the contract type between client and server. As SAFE compiles F# into JavaScript for you, you only need a single definition which will automatically be shared.
type Customer = { Name : string }\nModify the Msg type to have two new messages:
type Msg =\n// other messages ...\n| LoadCustomer of customerId:int // Add this\n| CustomerLoaded of Customer // Add this\nYou will see that this symmetrical pattern is often followed in MVU:
Update the Model to store the Customer once it is loaded:
type Model =\n{ // ...\nTheCustomer : Customer option }\nMake TheCustomer optional so that it can be initialised as None (see next step).
Update the init function to provide default data
let model =\n{ // ...\nTheCustomer = None }\nUpdate your view to initiate the LoadCustomer event. Here, we create a button that will start loading customer 42 on click:
let view model dispatch =\nHtml.div [\n// ...\nHtml.button [ prop.onClick (fun _ -> dispatch (LoadCustomer 42)) prop.text \"Load Customer\"\n]\n]\nModify the update function to handle the new messages:
let update msg model =\nmatch msg with\n// ....\n| LoadCustomer customerId ->\n// Implementation to connect to the server to be defined.\n| CustomerLoaded c ->\n{ model with TheCustomer = Some c }, Cmd.none\nThe code to fire off the message to the server differs depending on the client / server communication you are using and normally whether you are reading or writing data. See here for more information.
"},{"location":"recipes/client-server/saturn-to-giraffe/","title":"How do I use Giraffe instead of Saturn?","text":"Saturn is a functional alternative to MVC and Razor which sits on top of Giraffe. Giraffe itself is a functional wrapper around the ASP.NET Core web framework, making it easier to work with when using F#.
Since Saturn is built on top of Giraffe, migrating to using \"raw\" Giraffe is relatively simple to do.
"},{"location":"recipes/client-server/saturn-to-giraffe/#bootstrapping-the-application","title":"Bootstrapping the Application","text":""},{"location":"recipes/client-server/saturn-to-giraffe/#1-open-libraries","title":"1. Open libraries","text":"Navigate to the Server module in the Server project.
Remove
open Saturn\nopen Giraffe\nopen Microsoft.AspNetCore.Builder\nopen Microsoft.Extensions.DependencyInjection\nopen Microsoft.Extensions.Hosting\nopen Microsoft.AspNetCore.Hosting\nIn the same module, we need to replace the Server's application computation expression with some functions which set up the default host, configure the application and register services.
Remove this
let app =\napplication {\n// ...setup functions\n}\n\n[<EntryPoint>]\nlet main _ =\nrun app\n0\nand replace it with this
let configureApp (app : IApplicationBuilder) =\napp\n.UseStaticFiles()\n.UseGiraffe webApp\n\nlet configureServices (services : IServiceCollection) =\nservices\n.AddGiraffe() |> ignore\n\n[<EntryPoint>]\nlet main _ =\nHost.CreateDefaultBuilder()\n.ConfigureWebHostDefaults(\nfun webHostBuilder ->\nwebHostBuilder\n.Configure(configureApp)\n.ConfigureServices(configureServices)\n.UseWebRoot(\"public\")\n|> ignore)\n.Build()\n.Run()\n0\nIf you are using the standard SAFE template, there is nothing more you need to do, as routing is taken care of by Fable Remoting.
If however you are using the minimal template, you will need to replace the Saturn router expression with the Giraffe equivalent.
Replace this
let webApp =\nrouter {\nget Route.hello (json \"Hello from SAFE!\")\n}\nwith this
let webApp = route Route.hello >=> json \"Hello from SAFE!\"\nThe steps shown here are the minimal necessary to get a SAFE app running using Giraffe.
As with any Server setup however, there are many more optional parameters that you may wish to configure, such as caching, response compression and serialisation options as seen in the default SAFE templates amongst many others.
See the Giraffe and ASP.NET Core host builder, application builder and service collection docs for more information on this.
"},{"location":"recipes/client-server/serve-a-file-from-the-backend/","title":"Serve a file from the back-end","text":"In SAFE apps, you can send a file from the server to the client as well as you can send any other type of data.
"},{"location":"recipes/client-server/serve-a-file-from-the-backend/#1-define-the-route","title":"1. Define the route","text":"Since the standard template uses Fable.Remoting, we need to edit our API definition first. Find your API type definition in Shared.fs. It's usually the last block of code. The one you see here is named ITodoAPI. Edit this definition to have the download member you see below.
type ITodoAPI =\n{ //...other routes \ndownload : unit -> Async<byte[]> }\nOpen the Server.fs file and find the API that implements the definition we've just edited. It should now have an error since we're not matching the definition at the moment. Add the following route to it
//...other functions in todosApi\ndownload =\nfun () -> async {\nlet byteArray = System.IO.File.ReadAllBytes(\"file.txt\")\nreturn byteArray\n}\nMake sure to replace \"file.txt\" with your file that is placed in src/Server or relative path
Since the download function is asynchronous, we can't just call it anywhere in our view. The way we're going to deal with this is to create a Msg case and handle it in our update funciton.
type Msg =\n//...other cases\n| DownloadFile\n| FileDownloaded of byte[]\nlet update (msg: Msg) (model: Model): Model * Cmd<Msg> =\nmatch msg with\n//...other cases\n| DownloadFile -> model, Cmd.OfAsync.perform todosApi.download () FileDownloaded\n| FileDownloaded file ->\nfile.SaveFileAs(\"downloaded-file.txt\")\nmodel, Cmd.none // You can do something else here\nThe SaveFileAs function detects the mime-type/content-type automatically based on the file extension of the file input
Html.button [\nprop.onClick (fun _ -> dispatch DownloadFile)\nprop.text \"Click to download\" ]\nHaving added this last snippet of code into the view function, you will be able to download the file by clicking the button that will now be displayed in your UI. For more information visit the Fable.Remoting documentation
SAFE Stack makes it easy to catch and handle exceptions raised by the server on the client.
"},{"location":"recipes/client-server/server-errors-on-client/#1-update-the-model","title":"1. Update the Model","text":"Update the model to store the error details that we receive from the server. Find the Model type in src/Client/Index.fs and add it the following Errors field:
type Model =\n{ ... // the rest of the fields\nErrors: string list }\nNow, bind an empty list to the field record inside the init function:
let model =\n{ ... // the rest of the fields\nErrors = [] }\nWe now add a new message to handle errors that we get back from the server after making a request. Add the following case to the Msg type:
type Msg =\n| ... // other message cases\n| GotError of exn\nIn this simple example, we will simply capture the Message of the exception. Add the following line to the end of the pattern match inside the update function:
| GotError ex ->\n{ model with Errors = ex.Message :: model.Errors }, Cmd.none\nWe now have to connect up the server response to the new message we created. Elmish has support for this through the either Cmd functions (instead of the perform functions). Make the following changes to your server call:
let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo \u2026and replace it with the following:
let cmd = Cmd.OfAsync.either todosApi.addTodo todo AddedTodo GotError\nNow, if you get an exception from the Server, its message will be added to the Errors field of the Model type. Instead of throwing the error, you can now display a meaningful text to the user like so:
In the function todoAction in src/Client/Index.fs add the following:
Html.button [ //other button properties\n]\nfor msg in model.Errors do\nHtml.p msg\nIn the todosApi in src/Server/Server.fs replace the addTodo with the following:
addTodo =\nfun todo -> async {\nfailwith \"Something went wrong\"\nreturn\nmatch Storage.addTodo todo with\n| Ok() -> todo\n| Error e -> failwith e\n}\nand when you try to add a todo then you will see the error message from the server.
"},{"location":"recipes/client-server/share-code/","title":"How Do I Share Code Types Between the Client and the Server?","text":"SAFE Stack makes it really simple and easy to share code between the client and the server, since both of them are written in F#. The client side is transpiled into JavaScript by Fable, whilst the server side is compiled down to .NET CIL. Serialization between both happens in the background, so you don't have to worry about it.
"},{"location":"recipes/client-server/share-code/#types","title":"Types","text":"Let's say the you have the following type in src/Server/Server.fs:
type Customer =\n{ Id : Guid\nName : string\nEmail : string\nPhoneNumber : string }\nAnd you have the following function that is used to validate this Customer type in src/Client/Index.fs:
let customerIsValid customer =\n(Guid.Empty = customer.Id\n|| String.IsNullOrEmpty customer.Name\n|| String.IsNullOrEmpty customer.Email\n|| String.IsNullOrEmpty customer.PhoneNumber)\n|> not\nIf at any point you realise you need to use both the Customer type and the customerIsValid function both in the Client and the Server, all you need to do is to move both of them to Shared project. You can either put them in the Shared.fs file, or create your own file in the Shared project (eg. Customer.fs). After this, you will be able to use both the Customer type and the customerIsValid function in both the Client and the Server.
SAFE comes out of the box with [Fable.Remoting] or [Thoth] for serialization. These will handle transport of data seamlessly for you.
"},{"location":"recipes/client-server/share-code/#considerations","title":"Considerations","text":"Be careful not to place code in Shared.fs that depends on a Client or Server-specific dependency. If your code depends on Fable for example, in most cases it will not be suitable to place it in Shared, since it can only be used in Client. Similarly, if your types rely on .NET specific types in e.g. the framework class library (FCL), beware. Fable has built-in mappings for popular .NET types e.g. System.DateTime and System.Math, but you will have to write your own mappers otherwise.
Fable makes it quick and easy to upload files from the client.
"},{"location":"recipes/client-server/upload-file-from-client/#1-create-a-file","title":"1. Create a File","text":"Create a file in the client project named FileUpload.fs somewhere before the Index.fs file and insert the following:
module FileUpload\n\nopen Feliz\nopen Fable.Core.JsInterop\nThen, add the following. The reader.onload block will be executed once we select and confirm a file to be uploaded. Read the FileReader docs to find out more.
let handleFileEvent onLoad (fileEvent:Browser.Types.Event) =\nlet files:Browser.Types.FileList = !!fileEvent.target?files\nif files.length > 0 then\nlet reader = Browser.Dom.FileReader.Create()\nreader.onload <- (fun _ -> reader.result |> unbox |> onLoad)\nreader.readAsArrayBuffer(files.[0])\nInsert the following block of code at the end of FileUpload.fs. This function will create a UI element to be used to upload files.
let createFileUpload onLoad =\nHtml.input [ prop.type' \"file\"\nprop.label \"Choose a file\"\nprop.onChange (handleFileEvent onLoad)\n]\nHaving followed all these steps, you can now use the createFileUpload function in Index.fs to create the UI element for uploading files.
FileUpload.createFileUpload (HandleFile >> dispatch)\nOne thing to note is that HandleFile is a case of the discriminated union type Msg that's in Index.fs.
type Msg =\n// other messages\n| HandleFile of Browser.Types.Event\n\nlet update msg model =\nmatch msg with\n//other messages\n| HandleFile event ->\n// do what you need with the file\nThere are many ways to supply configuration settings e.g. connection strings to your application, and the official ASP .NET documentation explains in great detail the various options you have available.
"},{"location":"recipes/developing-and-testing/app-configuration/#configuration-of-the-server","title":"Configuration of the Server","text":"In this recipe, we show how to add configuration using an appsettings.json configuration file.
Never store secrets in plain text files such as appsettings.json - our recommendation is to use it for non-secret configuration data that is shared across your development team; see here for more guidance.
appsettings.json. It does not need to be added to the project file.{\n\"MyKey\": \"My appsettings.json Value\"\n}\nServer.fs, ensure that your API builder functions take in an HTTPContext as an argument and change the construction of your Fable Remoting endpoint to supply one: ++open Microsoft.AspNetCore.Http\n\n--let todosApi = {\n++let todosApi (context: HttpContext) = {\n\n...\n\n-- |> Remoting.fromValue todosApi\n++ |> Remoting.fromContext todosApi\ncontext to get a handle to the IConfiguration object, which allows you to access settings regardless of what infrastructure you are using to store them e.g. appsettings.json, environment variables etc. ++open Giraffe\n++open Microsoft.Extensions.Configuration\n\nlet todosApi (context: HttpContext) =\n++ let cfg = context.GetService<IConfiguration>()\n++ let value = cfg[\"MyKey\"] // \"My appsettings.json Value\"\nNote that the todosApi function will be called on every single ASP .NET request. It is safe to \"capture\" the cfg value and use it across multiple API methods.
User Secrets are an alternative way of storing secrets which, although still stored in plain text files, are not stored in your repository folder and therefore less at risk to accidentally committing into source control. However, Saturn currently disables User Secrets as part of its startup routine, and you must manually turn them back on:
++type DummyType() = class end\n\nlet app = application {\n++ host_config (fun hostBuilder ->\n++ hostBuilder.ConfigureAppConfiguration(fun _ configBuilder ->\n++ configBuilder.AddUserSecrets<DummyType>()\n++ |> ignore\n++ )\n++ )\n}\nYou can then access the IConfiguration as before, and user secrets values will be accessible.
Configuration of the client can be done in many ways, but generally a simple strategy is to have an API endpoint which is called on startup that provides any settings required by the client.
"},{"location":"recipes/developing-and-testing/debug-safe-app/","title":"How do I debug a SAFE app?","text":""},{"location":"recipes/developing-and-testing/debug-safe-app/#im-using-visual-studio","title":"I'm using Visual Studio","text":"In order to debug Server code from Visual Studio, we need set the correct URLs in the project's debug properties.
"},{"location":"recipes/developing-and-testing/debug-safe-app/#debugging-the-server","title":"Debugging the Server","text":""},{"location":"recipes/developing-and-testing/debug-safe-app/#1-configure-launch-settings","title":"1. Configure launch settings","text":"You can do this through the Server project's Properties/Debug editor or by editing the launchSettings.json file in src/Server/Properties
After selecting the debug profile that you wish to edit (IIS Express or Server), you will need to set the App URL field to http://localhost:5000 and Launch browser field to http://localhost:8080. The process is very similar for VS Mac.
Once this is done, you can expect your launchSettings.json file to look something like this:
{\n\"iisSettings\": {\n\"windowsAuthentication\": false,\n\"anonymousAuthentication\": true,\n\"iisExpress\": {\n\"applicationUrl\": \"http://localhost:5000/\",\n\"sslPort\": 44330\n}\n},\n\"profiles\": {\n\"IIS Express\": {\n\"commandName\": \"IISExpress\",\n\"launchBrowser\": true,\n\"launchUrl\": \"http://localhost:8080/\",\n\"environmentVariables\": {\n\"ASPNETCORE_ENVIRONMENT\": \"Development\"\n}\n},\n\"Server\": {\n\"commandName\": \"Project\",\n\"launchBrowser\": true,\n\"launchUrl\": \"http://localhost:8080\",\n\"environmentVariables\": {\n\"ASPNETCORE_ENVIRONMENT\": \"Development\"\n},\n\"applicationUrl\": \"http://localhost:5000\"\n}\n}\n}\nSince you will be running the server directly through Visual Studio, you cannot use a FAKE script to start the application. Launch the Client directly by running the following command in src/Client
dotnet fable watch -o output -s --run npx vite\nSet the server as your Startup project, either using the drop-down menu at the top of the IDE or by right clicking on the project itself and selecting Set as Startup Project. Select the profile that you set up earlier and wish to launch from the drop-down at the top of the IDE. Either press the Play button at the top of the IDE or hit F5 on your keyboard to start the Server debugging and launch a browser pointing at the website.
"},{"location":"recipes/developing-and-testing/debug-safe-app/#debugging-the-client","title":"Debugging the Client","text":"Although we write our client-side code using F#, it is being converted into JavaScript at runtime by Fable and executed in the browser. However, we can still debug it via the magic of source mapping. If you are using Visual Studio, you cannot directly connect to the browser debugger. You can, however, debug your client F# code using the browser's development tools.
"},{"location":"recipes/developing-and-testing/debug-safe-app/#1-set-breakpoints-in-client-code","title":"1. Set breakpoints in Client code","text":"The exact instructions will depend on your browser, but essentially it simply involves:
VS Code allows \"full stack\" debugging i.e. both the client and server. Prerequisites that you should install:
"},{"location":"recipes/developing-and-testing/debug-safe-app/#install-prerequisites","title":"Install Prerequisites","text":"ctrl+shift+d to open the debug pane.Run and Debug buttonThe server is now running. You can use the bar at the top of your screen to pause, restart or kill the debugger
"},{"location":"recipes/developing-and-testing/debug-safe-app/#debug-the-client","title":"Debug the Client","text":"dotnet fable watch -o output -s --run npx vite from <repo root>/src/Client/. ctrl+shift+p and run Debug: Open Link. http://localhost:8080/. This will launch a browser which is pointed at the URL and connect the debugger to it. If you find that your breakpoints aren't being hit, try stopping the Client, disconnecting the debugger and re-launching them both.
To find out more about the VS Code debugger, see here.
"},{"location":"recipes/developing-and-testing/testing-the-client/","title":"How do I test the client?","text":"Testing on the client is a little different than on the server.
This is because the code which is ultimately being executed in the browser is JavaScript, translated from F# by Fable, and so it must be tested in a JavaScript environment.
Furthermore, code that is shared between the Client and Server must be tested in both a dotnet environment and a JavaScript environment.
The SAFE template uses a library called Fable.Mocha which allows us to run the same tests in both environments. It mirrors the Expecto API and works in much the same way.
"},{"location":"recipes/developing-and-testing/testing-the-client/#im-using-the-standard-template","title":"I'm using the standard template","text":"If you are using the standard template then there is nothing more you need to do in order to start testing your Client.
In the tests/Client folder, there is a project named Client.Tests with a single script demonstrating how to use Mocha to test the TODO sample.
Note the compiler directive here which makes sure that the Shared tests are only included when executing in a JavaScript (Fable) context. They are covered by Expecto under dotnet as you can see in Server.Tests.fs.
In order to run the tests, instead of starting your application using
dotnet run\ndotnet run Runtests\nOnce the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
This command builds and runs the Server test project too. If you want to run the Client tests alone, you can simply launch the test server using npm run test:live, which executes a command stored in package.json.
If you are using the minimal template, you will need to first configure a test project as none are included.
"},{"location":"recipes/developing-and-testing/testing-the-client/#1-add-a-test-project","title":"1. Add a test project","text":"Create a .Net library called Client.Tests in the tests/Client subdirectory using the following commands:
dotnet new classlib -lang F# -n Client.Tests -o tests/Client\ndotnet sln add tests/Client\nReference the Client project from the Client.Tests project:
dotnet add tests/Client reference src/Client\nRun the following command:
dotnet add tests/Client package Fable.Mocha\nAdd this function to Client.fs in the Client project
let sayHello name = $\"Hello {name}\"\nReplace the contents of tests/Client/Library.fs with the following code:
module Tests\n\nopen Fable.Mocha\n\nlet client = testList \"Client\" [\ntestCase \"Hello received\" <| fun _ ->\nlet hello = Client.sayHello \"SAFE V3\"\n\nExpect.equal hello \"Hello SAFE V3\" \"Unexpected greeting\"\n]\n\nlet all =\ntestList \"All\"\n[\nclient\n]\n\n[<EntryPoint>]\nlet main _ = Mocha.runTests all\nAdd a file called index.html to the tests/Client folder with following contents:
<!DOCTYPE html>\n<html>\n <head>\n <title>SAFE Client Tests</title>\n </head>\n <body>\n <script type=\"module\" src=\"/output/Library.js\"></script>\n </body>\n</html>\nAdd a file called vite.config.mts to tests/Client:
import { defineConfig } from \"vite\";\n\n// https://vitejs.dev/config/\nexport default defineConfig({\n server: {\n port: 8081\n }\n});\nnpm install\ncd tests/Client\ndotnet fable watch -o output --run npx vite\nOnce the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
Testing your Server code in a SAFE app is just the same as in any other dotnet app, and you can use the same tools and frameworks that you are familiar with. These include all of the usual suspects such as NUnit, XUnit, FSUnit, Expecto, FSCheck, AutoFixture etc.
In this guide we will look at using Expecto, as this is included with the standard SAFE template.
"},{"location":"recipes/developing-and-testing/testing-the-server/#im-using-the-standard-template","title":"I'm using the standard template","text":""},{"location":"recipes/developing-and-testing/testing-the-server/#using-the-expecto-runner","title":"Using the Expecto runner","text":"If you are using the standard template, then there is nothing more you need to do in order to start testing your Server code.
In the tests/Server folder, there is a project named Server.Tests with a single script demonstrating how to use Expecto to test the TODO sample.
In order to run the tests, instead of starting your application using
dotnet run\nyou should instead use
dotnet run RunTests\nThis method builds and runs the Client test project too, which can be slow. If you want to run the Server tests alone, you can simply navigate to the tests/Server directory and run the project using dotnet run.
If you would like to use dotnet tests from the command line or the test runner that comes with Visual Studio, there are a couple of extra steps to follow.
"},{"location":"recipes/developing-and-testing/testing-the-server/#1-install-the-test-adapters","title":"1. Install the Test Adapters","text":"Run the following commands at the root of your solution:
dotnet paket add Microsoft.NET.Test.Sdk -p Server.Tests\ndotnet paket add YoloDev.Expecto.TestSdk -p Server.Tests\nOpen your ServerTests.fsproj file and add the following element:
<PropertyGroup>\n<GenerateProgramFile>false</GenerateProgramFile>\n</PropertyGroup>\nTo allow your tests to be discovered, you will need to decorate them with a [<Tests>] attribute.
The provided test would look like this:
[<Tests>]\nlet server = testList \"Server\" [\ntestCase \"Adding valid Todo\" <| fun _ ->\nlet storage = Storage()\nlet validTodo = Todo.create \"TODO\"\nlet expectedResult = Ok ()\n\nlet result = storage.AddTodo validTodo\n\nExpect.equal result expectedResult \"Result should be ok\"\nExpect.contains (storage.GetTodos()) validTodo \"Storage should contain new todo\"\n]\nThere are now two ways to run these tests.
From the command line, you can just run
dotnet test tests/Server\nAlternatively, if you are using Visual Studio or VS Mac you can make use of the built-in test explorers.
"},{"location":"recipes/developing-and-testing/testing-the-server/#im-using-the-minimal-template","title":"I'm using the minimal template","text":"If you are using the minimal template, you will need to first configure a test project as none are included.
"},{"location":"recipes/developing-and-testing/testing-the-server/#1-add-a-test-project","title":"1. Add a test project","text":"Create a .Net console project called Server.Tests in the tests/Server folder.
dotnet new console -lang F# -n Server.Tests -o tests/Server\ndotnet sln add tests/Server\nReference the Server project from the Server.Tests project:
dotnet add tests/Server reference src/Server\nRun the following command:
dotnet add tests/Server package Expecto\nUpdate the Server.fs file in the Server project to extract the message logic from the router like so:
let getMessage () = \"Hello from SAFE!\"\n\nlet webApp =\nrouter {\nget Route.hello (getMessage () |> json )\n}\nReplace the contents of tests/Server/Program.fs with the following:
open Expecto\n\nlet server = testList \"Server\" [\ntestCase \"Message returned correctly\" <| fun _ ->\nlet expectedResult = \"Hello from SAFE!\" let result = Server.getMessage()\nExpect.equal result expectedResult \"Result should be ok\"\n]\n\n[<EntryPoint>]\nlet main _ = runTestsWithCLIArgs [] [||] server\ndotnet run -p tests/Server\nThis will print out the results in the console window
"},{"location":"recipes/developing-and-testing/testing-the-server/#7-using-dotnet-test-or-the-visual-studio-test-explorer","title":"7. Using dotnet test or the Visual Studio Test Explorer","text":"Add the libraries Microsoft.NET.Test.Sdk and YoloDev.Expecto.TestSdk to your Test project, using NuGet.
The way you do this will depend on whether you are using NuGet directly or via Paket. See this recipe for more details.
You can now add [<Test>] attributes to your tests so that they can be discovered, and then run them using the dotnet tooling in the same way as explained earlier for the standard template.
Sometimes you need to use a JS library directly, instead of using it through a wrapper library that makes it easy to use from F# code. In this case you need to import a module from the library. Here are the most common import patterns used in JS.
"},{"location":"recipes/javascript/import-js-module/#default-export","title":"Default export","text":""},{"location":"recipes/javascript/import-js-module/#setup","title":"Setup","text":"In most cases components use the default export syntax which is when the the component being exported from the module becomes available. For example, if the module being imported below looked something like:
// module-name\nconst foo = () => \"hello\"\n\nexport default foo\nfoo. import foo from 'module-name' // JS\nlet foo = importDefault \"module-name\" // F#\nTo ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element.
Browser.Dom.console.log(\"imported value\", foo)\nAn example of this in use is how React is imported
import React from \"react\"\n\n// Although in the newer versions of React this is uneeded\nIn some cases components can use the named export syntax. In the below case \"module-name\" has an object/function/class that is called bar. By referncing it below it is brought into the current scope. For example, if the module below contained something like:
export const bar (x,y) => x + y import { bar } from \"module-name\" // JS\nlet bar = import \"bar\" \"module-name\" // F#\nTo ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element.
Browser.Dom.console.log(\"imported value\", bar)\nAn example of this is how React hooks are imported
import { useState } from \"react\"\nIn rare cases you may have to import an entire module's contents and provide an alias in the below case we named it myModule. You can now use dot notation to access anything that is exported from module-name. For example, if the module being imported below includes an export to a function doAllTheAmazingThings() you could access it like:
myModule.doAllTheAmazingThings()\nimport * as myModule from 'module-name' // JS\nlet myModule = importAll \"module-name\" // F#\nTo ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element.
Browser.Dom.console.log(\"imported value\", myModule)\nAn example of this is another way to import React
import * as React from \"react\"\n\n// Uncommon since importDefault is the standard\nSee the Fable docs for more ways to import modules and use JavaScript from Fable.
"},{"location":"recipes/javascript/third-party-react-package/","title":"Add Support for a Third Party React Library","text":"To use a third-party React library in a SAFE application, you need to write an F# wrapper around it. There are two ways for doing this - using Feliz or using Fable.React.
"},{"location":"recipes/javascript/third-party-react-package/#prerequisites","title":"Prerequisites","text":"This recipe uses the react-d3-speedometer NPM package for demonstration purposes. Add it to your Client before continuing.
"},{"location":"recipes/javascript/third-party-react-package/#feliz-setup","title":"Feliz - Setup","text":"If you don't already have Feliz installed, add it to your client. In the Client projects Index.fs add the following snippets
open Fable.Core.JsInterop\nWithin the view function
Feliz.Interop.reactApi.createElement (importDefault \"react-d3-speedometer\", createObj [\n\"minValue\" ==> 0\n\"maxValue\" ==> 100\n\"value\" ==> 10\n])\ncreateElement from Feliz.ReactApi.IReactApi takes the component you're wrapping react-d3-speedometer, the props that component takes and creates a ReactComponent we can use in F#.importDefault from Fable.Core.JsInterop is giving us access to the component and is equivalent to import ReactSpeedometer from \"react-d3-speedometer\"\nThe reason for using importDefault is the documentation for the component uses a default export \"ReactSpeedometer\". Please find a list of common import statetments at the end of this recipe
As a quick check to ensure that the library is being imported and we have no typos you can console.log the following at the top within the view function
Browser.Dom.console.log(\"REACT-D3-IMPORT\", importDefault \"react-d3-speedometer\")\nIn the console window (which can be reached by right-clicking and selecting Insepct Element) you should see some output from the above log. If nothing is being seen you may need a slightly different import statement, please refer to this recipe.
createObj from Fable.Core.JsInterop takes a sequence of string * obj which is a prop name and value for the component, you can find the full prop list for react-d3-speedometer here.==> (short hand for prop.custom) to transform the sequence into a JavaScript object createObj [\n\"minValue\" ==> 0\n\"maxValue\" ==> 10\n]\nIs equivalent to
{ minValue: 0, maxValue: 10 }\nThat's the bare minimum needed to get going!
"},{"location":"recipes/javascript/third-party-react-package/#next-steps-for-feliz","title":"Next steps for Feliz","text":"Once your component is working you may want to extract out the logic so that it can be used in multiple pages of your app. For a full detailed tutorial head over to this blog post!
"},{"location":"recipes/javascript/third-party-react-package/#fablereact-setup","title":"Fable.React - Setup","text":""},{"location":"recipes/javascript/third-party-react-package/#1-create-a-new-file","title":"1. Create a new file","text":"Create an empty file named ReactSpeedometer.fs in the Client project above Index.fs and insert the following statements at the beginning of the file.
module ReactSpeedometer\n\nopen Fable.Core\nopen Fable.Core.JsInterop\nopen Fable.React\nProp represents the props of the React component. In this recipe, we're using the props listed here for react-d3-speedometer. We model them in Fable.React using a discriminated union.
type Prop =\n| Value of int\n| MinValue of int\n| MaxValue of int | StartColor of string\nOne difference to note is that we use PascalCase rather than camelCase.
Note that we can model any props here, both simple values and \"event handler\"-style ones.
"},{"location":"recipes/javascript/third-party-react-package/#3-write-the-component","title":"3. Write the Component","text":"Add the following function to the file. Note that the last argument passed into the ofImport function is a list of ReactElements to be used as children of the react component. In this case, we are passing an empty list since the component doesn't have children.
let reactSpeedometer (props : Prop list) : ReactElement =\nlet propsObject = keyValueList CaseRules.LowerFirst props // converts Props to JS object\nofImport \"default\" \"react-d3-speedometer\" propsObject [] // import the default function/object from react-d3-speedometer\nWith all these in place, you can use the React element in your client like so:
open ReactSpeedometer\n\nreactSpeedometer [\nProp.Value 10 // Since Value is already decalred in HTMLAttr you can use Prop.Value to tell the F# compiler its of type Prop and not HTMLAttr\nMaxValue 100\nMinValue 0 StartColor \"red\"\n]\nWhen you want to call a JavaScript library from your Client, it is easy to import and reference it using NPM.
Run the following command:
npm install name-of-package\nThis will download the package into the solution's node_modules folder.
You will also see a reference to the package in the Client's package.json file:
\"dependencies\": {\n\"name-of-package\": \"^1.0.0\"\n}\nAdding packages to the Client project is a very similar process to the Server, with a few key differences:
Any references to the Server directory should be Client
Client code written in F# is converted into JavaScript using Fable. Because of this, we must be careful to only reference libraries which are Fable compatible.
If the NuGet package uses any JS libraries you must install them. For simplicity, use Femto to sync - if the NuGet package is compatible - or install via NPM manually, if not.
There are lots of great libraries available to choose from.
"},{"location":"recipes/package-management/add-nuget-package-to-server/","title":"How do I add a NuGet package to the Server?","text":"You can add NuGet packages to the server to give it more capabilities. You can download a wide variety of packages from the official NuGet site.
In this example we will add the FsToolkit ErrorHandling package package.
"},{"location":"recipes/package-management/add-nuget-package-to-server/#1-add-the-package","title":"1. Add the package","text":"Navigate to the root directory of your solution and run:
dotnet paket add FsToolkit.ErrorHandling -p Server\nThis will add an entry to both the solution paket.dependencies file and the Server project's paket.reference file, as well as update the lock file with the updated dependency graph.
For a detailed explanation of package management using Paket, visit the official docs.
"},{"location":"recipes/package-management/migrate-to-nuget/","title":"How do I migrate to NuGet from Paket?","text":"Note that the minimal template uses NuGet by default. This recipe only applies to the full template.
Paket is a fully featured package manager that acts as an alternative to the NuGet package manager commonly used in .NET.
It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
For most use cases, we would recommend sticking with Paket. If, however, you are in a position where you wish to remove it and revert back to the NuGet package manager, you can easily do so with the following steps.
"},{"location":"recipes/package-management/migrate-to-nuget/#1-remove-paket-targets-import-from-fsproj-files","title":"1. Remove Paket targets import from .fsproj files","text":"In every project's .fsproj file you will find the following line. Remove it and save.
<Import Project=\"..\\..\\.paket\\Paket.Restore.targets\" />\nYou will find this file at the root of your solution. Remove it from your solution if included and then delete it.
"},{"location":"recipes/package-management/migrate-to-nuget/#3-add-project-dependencies-via-nuget","title":"3. Add project dependencies via NuGet","text":"Each project directory will contain a paket.references file. This lists all the NuGet packages that the project requires.
Inside a new ItemGroup in the project's .fsproj file you will need to add an entry for each of these packages.
<ItemGroup>\n<PackageReference Include=\"Azure.Core\" Version=\"1.24\" />\n<PackageReference Include=\"AnotherPackage\" Version=\"2.0.1\" />\n<!--...add entry for each package in the references file...-->\n</ItemGroup>\nYou can find the version of each package in the paket.lock file at the root of the solution. The version number is contained in brackets next to the name of the package at the first level of indentation. For example, in this case Azure.Core is version 1.24:
Azure.Core (1.24)\n Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)\n System.Diagnostics.DiagnosticSource (>= 4.6)\n System.Memory.Data (>= 1.0.2)\n System.Numerics.Vectors (>= 4.5)\n System.Text.Encodings.Web (>= 4.7.2)\n System.Text.Json (>= 4.7.2)\n System.Threading.Tasks.Extensions (>= 4.5.4)\nOnce you have added all of your dependencies to the relevant .fsproj files, you can remove the folowing files and folders from your solution.
Files: * paket.lock * paket.dependencies * all of the paket.references files
Folders: * .paket * paket-files
If you open .config/dotnet-tools.json you will find an entry for paket. Remove it.
Alternatively, run
dotnet tool uninstall paket\nPaket is a fully featured package manager that acts as an alternative to the NuGet package manager.
It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
Note that the standard template uses Paket by default. This recipe only applies to the minimal template.
"},{"location":"recipes/package-management/migrate-to-paket/#1-install-and-restore-paket","title":"1. Install and restore Paket","text":"dotnet tool install paket\ndotnet tool restore\nRun this command to move existing NuGet references to Paket from your packages.config or .fsproj file:
dotnet paket convert-from-nuget\nThis will add three files to your solution, all of which should be committed to source control:
For a more detailed explanation of this process see the official migration guide.
In the case where you have added a NuGet project to a solution which is already using paket, run this command with the option --force.
If you are working in Visual Studio and wish to see your Paket files in the Solution Explorer, you will need to add both the paket.lock and any paket.references files created in your project directories during the last step to your solution.
"},{"location":"recipes/package-management/sync-nuget-and-npm-packages/","title":"How do I ensure NPM and NuGet packages stay in sync?","text":"SAFE Stack uses Fable bindings, which are NuGet packages that provide idiomatic and type-safe wrappers around native JavaScript APIs. These bindings often rely on third-party JavaScript libraries distributed via the NPM registry. This leads to the problem of keeping both the NPM package in sync with its corresponding NuGet F# wrapper. Femto is a dotnet CLI tool that solves this issue.
For in-depth information about Femto, see Introducing Femto.
"},{"location":"recipes/package-management/sync-nuget-and-npm-packages/#1-install-femto","title":"1. Install Femto","text":"Navigate to the root folder of the solution and execute the following command:
dotnet tool install femto\nIn the root directory, run the following:
dotnet femto ./src/Client\nalternatively, you can call femto directly from ./src/Client:
cd ./src/Client\ndotnet femto\nThis will give you a report of discrepancies between the NuGet packages and the NPM packages for the project, as well as steps to take in order to resolve them.
"},{"location":"recipes/package-management/sync-nuget-and-npm-packages/#3-resolve-dependencies","title":"3. Resolve Dependencies","text":"To sync your NPM dependencies with your NuGet dependencies, you can either manually follow the steps returned by step 2, or resolve them automatically using the following command:
dotnet femto ./src/Client --resolve\nKeeping your NPM dependencies in sync with your NuGet packages is now as easy as repeating step 3. Of course, you can instead repeat the step 2 and resolve packages manually, too.
"},{"location":"recipes/patterns/add-dependency-injection/","title":"Use Dependency Injection","text":"This recipe is not a detailed discussion of the pros and cons of Dependency Injection (DI) compared to other patterns. It simply illustrates how to use it within a SAFE Stack application!
Create a class that you wish to inject with a dependency (in this example, we use the built-in IConfiguration type that is included in ASP .NET):
open Microsoft.Extensions.Configuration\n\ntype DatabaseRepository(config:IConfiguration) =\nmember _.SaveDataToDb (text:string) =\nlet connectionString = config[\"SqlConnectionString\"]\n// Connect to SQL using the above connection string etc.\nOk 1\nInstead of functions or modules, DI in .NET and F# only works with classes.
Register your type with ASP .NET during startup within the application { } block.
++ open Microsoft.Extensions.DependencyInjection\n\n application {\n //...\n++ service_config (fun services -> services.AddSingleton<DatabaseRepository>())\nThis section of the official ASP .NET Core article explain the distinction between different lifetime registrations, such as Singleton and Transient.
Ensure that your Fable Remoting API can access the HttpContext type by using the fromContext builder function.
-- |> Remoting.fromValue createFableRemotingApi\n++ |> Remoting.fromContext createFableRemotingApi\nWithin your Fable Remoting API, use the supplied context to retrieve your dependency:
++ open Microsoft.AspNetCore.Http\n\n let createFableRemotingApi\n++ (context:HttpContext) =\n++ let dbRepository = context.GetService<DatabaseRepository>()\n // ...\n // Return the constructed API record value...\nGiraffe provides the GetService<'T> extension to allow you to quickly retrieve a dependency from the HttpContext.
This will instruct ASP .NET to get a handle to the DatabaseRepository object; ASP .NET will automatically supply the IConfiguration object to the constructor. Whether a new DatabaseRepository object is constructed on each call depends on the lifetime you have registered it with.
You can have your types depend on other types that you create, as long as they are registering into ASP .NET Core's DI container using methods such as AddSingleton etc.
The default template uses in-memory storage. This recipe will show you how to replace the in-memory storage with LiteDB in the form of LiteDB.FSharp.
"},{"location":"recipes/storage/use-litedb/#1-add-litedbfsharp","title":"1. Add LiteDB.FSharp","text":"Add the LiteDB.FSharp NuGet package to the server project.
"},{"location":"recipes/storage/use-litedb/#2-create-the-database","title":"2. Create the database","text":"Replace the use of the ResizeArray in the Storage type with a database and collection:
open LiteDB.FSharp\nopen LiteDB\n\ntype Storage () =\nlet database =\nlet mapper = FSharpBsonMapper()\nlet connStr = \"Filename=Todo.db;mode=Exclusive\"\nnew LiteDatabase (connStr, mapper)\nlet todos = database.GetCollection<Todo> \"todos\"\nLiteDb is a file-based database, and will create the file if it does not exist automatically.
This will create a database file Todo.db in the Server folder. The option mode=Exclusive is added for MacOS support (see this issue).
See here for more information on connection string arguments.
See the official docs for details on constructor arguments.
"},{"location":"recipes/storage/use-litedb/#3-implement-the-rest-of-the-repository","title":"3. Implement the rest of the repository","text":"Replace the implementations of GetTodos and AddTodo as follows:
/// Retrieves all todo items.\nmember _.GetTodos () =\ntodos.FindAll () |> List.ofSeq\n\n/// Tries to add a todo item to the collection.\nmember _.AddTodo (todo:Todo) =\nif Todo.isValid todo.Description then\ntodos.Insert todo |> ignore\nOk ()\nelse\nError \"Invalid todo\"\nModify the existing \"priming\" so that it first checks if there are any records in the database before inserting data:
if storage.GetTodos() |> Seq.isEmpty then\nstorage.AddTodo(Todo.create \"Create new SAFE project\") |> ignore\nstorage.AddTodo(Todo.create \"Write your app\") |> ignore\nstorage.AddTodo(Todo.create \"Ship it !!!\") |> ignore\nAdd the CLIMutable attribute to the Todo record in Shared.fs
[<CLIMutable>]\ntype Todo =\n{ Id : Guid\nDescription : string }\nThis is required to allow LiteDB to hydrate (read) data into F# records.
"},{"location":"recipes/storage/use-litedb/#all-done","title":"All Done!","text":"The easiest way to get a database running locally is using Docker. You can find the installer on their website. Once docker is installed, use the following command to spin up a database server
docker run -e \"ACCEPT_EULA=Y\" -e \"MSSQL_SA_PASSWORD=<your password>\" -p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest\n1) In the \"Connections\" tab, click the \"New Connection\" button
2) Enter your connection details, leaving the \"Database\" dropdown set to <Default>.
USE master\nGO\nIF NOT EXISTS (\nSELECT name\nFROM sys.databases\nWHERE name = N'SafeTodo'\n)\nCREATE DATABASE [SafeTodo];\nGO\nIF SERVERPROPERTY('ProductVersion') > '12'\nALTER DATABASE [SafeTodo] SET QUERY_STORE=ON;\nGO\nNOTE: Alternatively, if you don't want to manually create the new database, you can install the \"New Database\" extension in Azure Data Studio which gives you a \"New Database\" option when right clicking the \"Databases\" folder.
"},{"location":"recipes/storage/use-sqlprovider-ssdt/#create-a-todos-table","title":"Create a \"Todos\" Table","text":"CREATE TABLE [dbo].[Todos]\n(\n[Id] UNIQUEIDENTIFIER NOT NULL PRIMARY KEY,\n[Description] NVARCHAR(500) NOT NULL,\n[IsDone] BIT NOT NULL\n)\nAt this point, you should have a SAFE Stack solution and a minimal \"SafeTodo\" SQL Server database with a \"Todos\" table. Next, we will use Azure Data Studio with the \"SQL Database Projects\" extension to create a new SSDT (SQL Server Data Tools) .sqlproj that will live in our SAFE Stack .sln.
1) Install the \"SQL Database Projects\" extension.
2) Right click the SafeTodo database and choose \"Create Project From Database\" (this option is added by the \"SQL Database Projects\" extension)
3) Configure a path within your SAFE Stack solution folder and a project name and then click \"Create\". NOTE: If you choose to create an \"ssdt\" subfolder as I did, you will need to manually create this subfolder first.
4) You should now be able to view your SQL Project by clicking the \"Projects\" tab in Azure Data Studio.
5) Finally, right click the SafeTodoDB project and select \"Build\". This will create a .dacpac file which we will use in the next step.
"},{"location":"recipes/storage/use-sqlprovider-ssdt/#create-a-todorepository-using-the-new-ssdt-provider-in-sqlprovider","title":"Create a TodoRepository Using the new SSDT provider in SQLProvider","text":""},{"location":"recipes/storage/use-sqlprovider-ssdt/#installing-sqlprovider-from-nuget","title":"Installing SQLProvider from NuGet","text":"Install dependencies SqlProvider and Microsoft.Data.SqlClient
dotnet paket add SqlProvider -p Server\ndotnet paket add Microsoft.Data.SqlClient -p Server\nNext, we will wire up our type provider to generate database types based on the compiled .dacpac file.
1) In the Server project, create a new file, Database.fs. (this should be above Server.fs).
module Database\nopen FSharp.Data.Sql\n\n[<Literal>]\nlet SsdtPath = __SOURCE_DIRECTORY__ + @\"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac\"\n\ntype DB = SqlDataProvider<\nCommon.DatabaseProviderTypes.MSSQLSERVER_SSDT,\nSsdtPath = SsdtPath,\nUseOptionTypes = Common.NullableColumnType.OPTION\n>\n\n//TO RELOAD SCHEMA: 1) uncomment the line below; 2) save; 3) recomment; 4) save again and wait.\n//DB.GetDataContext().``Design Time Commands``.ClearDatabaseSchemaCache\n\nlet createContext (connectionString: string) =\nDB.GetDataContext(connectionString)\n2) Create TodoRepository.fs below Database.fs.
module TodoRepository\nopen FSharp.Data.Sql\nopen Database\nopen Shared\n\n/// Get all todos that have not been marked as \"done\". \nlet getTodos (db: DB.dataContext) = query {\nfor todo in db.Dbo.Todos do\nwhere (not todo.IsDone)\nselect { Shared.Todo.Id = todo.Id\nShared.Todo.Description = todo.Description }\n}\n|> List.executeQueryAsync\n\nlet addTodo (db: DB.dataContext) (todo: Shared.Todo) =\nasync {\nlet t = db.Dbo.Todos.Create()\nt.Id <- todo.Id\nt.Description <- todo.Description\nt.IsDone <- false\n\ndo! db.SubmitUpdatesAsync() |> Async.AwaitTask\n}\n3) Create TodoController.fs below TodoRepository.fs.
module TodoController\nopen Database\nopen Shared\n\nlet getTodos (db: DB.dataContext) = TodoRepository.getTodos db |> Async.AwaitTask\n\nlet addTodo (db: DB.dataContext) (todo: Todo) = async {\nif Todo.isValid todo.Description then\ndo! TodoRepository.addTodo db todo\nreturn todo\nelse return failwith \"Invalid todo\"\n}\n4) Finally, replace the stubbed todosApi implementation in Server.fs with our type provided implementation.
module Server\n\nopen Fable.Remoting.Server\nopen Fable.Remoting.Giraffe\nopen Saturn\nopen System\nopen Shared\nopen Microsoft.AspNetCore.Http\n\nlet todosApi =\nlet db = Database.createContext @\"Data Source=localhost,1433;Database=SafeTodo;User ID=sa;Password=<your password>;TrustServerCertificate=True\"\n{ getTodos = fun () -> TodoController.getTodos db\naddTodo = TodoController.addTodo db }\n\nlet webApp =\nRemoting.createApi()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.fromValue todosApi\n|> Remoting.withErrorHandler fableRemotingErrorHandler\n|> Remoting.buildHttpHandler\n\nlet app =\napplication {\nuse_router webApp\nmemory_cache\nuse_static \"public\"\nuse_gzip\n}\n\nrun app\nFrom the VS Code terminal in the SafeTodo folder, launch the app (server and client):
dotnet run
You should now be able to add todos.
"},{"location":"recipes/storage/use-sqlprovider-ssdt/#deployment","title":"Deployment","text":"When creating a Release build for deployment, it is important to note that SQLProvider SSDT expects that the .dacpac file will be copied to the deployed Server project bin folder.
Here are the steps to accomplish this:
1) Modify your Server.fsproj to include the .dacpac file with \"CopyToOutputDirectory\" to ensure that the .dacpac file will always exist in the Server project bin folder.
<ItemGroup>\n <None Include=\"..\\{relative path to SSDT project}\\ssdt\\SafeTodo\\bin\\$(Configuration)\\SafeTodoDB.dacpac\" Link=\"SafeTodoDB.dacpac\">\n <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>\n </None>\n\n { other files... }\n</ItemGroup>\n2) In your Server.Database.fs file, you should also modify the SsdtPath binding so that it can build the project in either Debug or Release mode:
[<Literal>]\n#if DEBUG\nlet SsdtPath = __SOURCE_DIRECTORY__ + @\"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac\"\n#else\nlet SsdtPath = __SOURCE_DIRECTORY__ + @\"/../../ssdt/SafeTodoDB/bin/Release/SafeTodoDB.dacpac\"\n#endif\nNOTE: This assumes that your SSDT .sqlproj will be built in Release mode (you can build it manually, or use a FAKE build script to handle this).
"},{"location":"recipes/ui/add-bulma/","title":"How do I add Bulma to a SAFE project?","text":"Bulma is a free open-source UI framework based on flexbox that helps you create modern and responsive layouts.
When using Feliz (the standard for a SAFE app), follow the instructions below. When using Fable.React, use the Fulma wrapper for Bulma.
"},{"location":"recipes/ui/add-bulma/#1-add-the-felizbulma-nuget-package-to-the-client-project","title":"1. Add the Feliz.Bulma NuGet package to the client project","text":"dotnet paket add Feliz.Bulma -p Client\nindex.html","text":" ...\n <head>\n ...\n+ <link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css\">\n</head>\n ...\nopen Feliz.Bulma\n\nBulma.button.button [\nstr \"Click me!\"\n]\nDaisyUI is a component library for Tailwind CSS. To use the library from within F# we will use Feliz.DaisyUI (Github).
Open a terminal at ./src/Client
Add daisyUI JS dependencies using NPM: npm i -D daisyui@latest
Add Feliz.DaisyUI .NET dependency...
dotnet paket add Feliz.DaisyUIdotnet add package Feliz.DaisyUIUpdate the tailwind.config.js file's module.exports.plugins array; add require(\"daisyui\")
module.exports = {\ncontent: [\n'.index.html',\n'./**/*.fs',\n],\ntheme: {\nextend: {},\n},\nplugins: [\nrequire('daisyui'),\n],\n}\nOpen the daisyUI namespace wherever you want to use it. YourFileHere.fs
open Feliz.DaisyUI\nCongratulations, now you can use daisyUI components! Documentation can be found at https://dzoukr.github.io/Feliz.DaisyUI/
Feliz is a wrapper for the base React DSL library that emphasises consistency, lightweight formatting, discoverable attributes and full type-safety. The default SAFE Template already uses Feliz.
"},{"location":"recipes/ui/add-feliz/#using-feliz","title":"Using Feliz","text":"dotnet paket add Feliz -p Client\nopen Feliz\n\nHtml.button [\nprop.style [ style.marginLeft 5 ]\nprop.onClick (fun _ -> setCount(count - 1))\nprop.text \"Decrement\"\n]\nFontAwesome is the most popular icon set out there and will provide you with a handful of free icons as well as a multitude of premium icons. The standard SAFE template has out-of-the-box support for FontAwesome. You can just start using it in your Client code like so:
open Feliz\n\nHtml.i [ prop.className \"fas fa-star\" ]\nIf you don't need the full features of Feliz we suggest using Fable.FontAwesome.Free.
Add Fable.FontAwesome.Free NuGet Package to the Client project.
See How do I add a Nuget package to the Client?.
"},{"location":"recipes/ui/add-fontawesome/#2-the-cdn-link","title":"2. The CDN Link","text":"Open the index.html file and add the following line to the head element:
<link rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css\">\nopen Fable.FontAwesome\n\nIcon.icon [\nFa.i [ Fa.Solid.Star ] [ ]\n]\nNow you can use FontAwesome in your code
"},{"location":"recipes/ui/add-routing-with-separate-models/","title":"How do I add routing to a SAFE app with separate model for every page?","text":"Written for SAFE template version 4.2.0
If your application has multiple separate components, there is no need to have one big, complex model that manages all the state for all components. In this recipe we separate the information of the todo list out of the main Model, and give the todo list application its own route. We also add a \"Page not found\" page.
Install Feliz.Router in the client project
dotnet paket add Feliz.Router -p Client\nTo include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router\nMove the following functions and types to a new TodoList Module in a file TodoList.fs:
private access modifieralso open Shared, Fable.Remoting.Client, Elmish and Feliz
module TodoList\n\nopen Shared\nopen Fable.Remoting.Client\nopen Elmish\nopen Feliz\n\ntype Model = { Todos: Todo list; Input: string }\n\ntype Msg =\n| GotTodos of Todo list\n| SetInput of string\n| AddTodo\n| AddedTodo of Todo\n\nlet todosApi =\nRemoting.createApi ()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.buildProxy<ITodosApi>\n\nlet init () =\nlet model = { Todos = []; Input = \"\" }\nlet cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos\nmodel, cmd\n\nlet update msg model =\nmatch msg with\n| GotTodos todos -> { model with Todos = todos }, Cmd.none\n| SetInput value -> { model with Input = value }, Cmd.none\n| AddTodo ->\nlet todo = Todo.create model.Input\n\nlet cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n\n{ model with Input = \"\" }, cmd\n| AddedTodo todo ->\n{\nmodel with\nTodos = model.Todos @ [ todo ]\n},\nCmd.none\n\nlet private todoAction model dispatch =\nHtml.div [\nprop.className \"flex flex-col sm:flex-row mt-4 gap-4\"\nprop.children [\nHtml.input [\nprop.className\n\"shadow appearance-none border rounded w-full py-2 px-3 outline-none focus:ring-2 ring-teal-300 text-grey-darker\"\nprop.value model.Input\nprop.placeholder \"What needs to be done?\"\nprop.autoFocus true\nprop.onChange (SetInput >> dispatch)\nprop.onKeyPress (fun ev ->\nif ev.key = \"Enter\" then\ndispatch AddTodo)\n]\nHtml.button [\nprop.className\n\"flex-no-shrink p-2 px-12 rounded bg-teal-600 outline-none focus:ring-2 ring-teal-300 font-bold text-white hover:bg-teal disabled:opacity-30 disabled:cursor-not-allowed\"\nprop.disabled (Todo.isValid model.Input |> not)\nprop.onClick (fun _ -> dispatch AddTodo)\nprop.text \"Add\"\n]\n]\n]\n\nlet view model dispatch =\nHtml.div [\nprop.className \"bg-white/80 rounded-md shadow-md p-4 w-5/6 lg:w-3/4 lg:max-w-2xl\"\nprop.children [\nHtml.ol [\nprop.className \"list-decimal ml-6\"\nprop.children [\nfor todo in model.Todos do\nHtml.li [ prop.className \"my-1\"; prop.text todo.Description ]\n]\n]\n\ntodoAction model dispatch\n]\n]\nCreate a new Model in the Index module, to keep track of the open page
type Page =\n| TodoList of TodoList.Model\n| NotFound type Model = { CurrentPage: Page }\nAdd a Msg type with a case of TodoList.Msg
type Msg =\n| TodoListMsg of TodoList.Msg\nCreate an update function (we moved the original one to TodoList). Handle the TodoListMsg by updating the TodoList Model. Wrap the command returned by the update of the todo list in a TodoListMsg before returning it. We expand this function later with other cases that deal with navigation.
let update message model =\nmatch model.CurrentPage, message with\n| TodoList todoList, TodoListMsg todoListMessage ->\nlet newTodoListModel, todoCommand = TodoList.update todoListMessage todoList\n\nlet model = {\nmodel with\nCurrentPage = TodoList newTodoListModel\n}\n\nmodel, todoCommand |> Cmd.map TodoListMsg\nCreate a function initFromUrl; initialize the TodoList app when given the URL of the todo list app. Also return the command that TodoList's init may return, wrapped in a TodoListMsg
let initFromUrl url =\nmatch url with\n| [ \"todo\" ] ->\nlet todoListModel, todoListMsg = TodoList.init ()\nlet model = { CurrentPage = TodoList todoListModel }\n\nmodel, todoListMsg |> Cmd.map TodoListMsg\nAdd a wildcard, so any URLs that are not registered display the \"not found\" page
CodeDiff Index.fslet initFromUrl url =\nmatch url with\n...\n| _ -> { CurrentPage = NotFound }, Cmd.none\n let initFromUrl url =\n match url with\n ...\n+ | _ -> { CurrentPage = NotFound }, Cmd.none\nAdd an init function to Index; return the current page based on Router.currentUrl
let init () =\nRouter.currentUrl ()\n|> initFromUrl\nAdd an UrlChanged case of string list to the Msg type
type Msg =\n...\n| UrlChanged of string list\n type Msg =\n ...\n+ | UrlChanged of string list\nHandle the case in the update function by calling initFromUrl
let update message model =\n...\nmatch model.CurrentPage, message with\n| _, UrlChanged url -> initFromUrl url\n let update message model =\n ...\n+ match model.CurrentPage, message with\n+ | _, UrlChanged url -> initFromUrl url\nComplete the pattern match in the update function, adding a case with a wildcard for both message and model. Return the model, and no command
let update message model =\n...\n| _, _ -> model, Cmd.none\n let update message model =\n ...\n+ | _, _ -> model, Cmd.none\nAdd a function pageContent to the Index module. If the CurrentPage is of TodoList, render the todo list using TodoList.view; in order to dispatch a TodoList.Msg, it needs to be wrapped in a TodoListMsg.
For the NotFound page, return a \"Page not found\" box
let pageContent model dispatch =\nmatch model.CurrentPage with\n| TodoList todoListModel -> TodoList.view todoListModel (TodoListMsg >> dispatch)\n| NotFound -> Html.text \"Page not found\"\nIn the view function, replace the call to todoList with a call to pageContent
let view model dispatch =\n...\npageContent model dispatch\n...\n let view model dispatch =\n ...\n- todoList model dispatch\n+ pageContent model dispatch\n ...\nWrap the content of the view function in a router.children property of a React.router. Also add an onUrlChanged property, that dispatches the 'UrlChanged' message.
let view model dispatch =\nReact.router [\nrouter.onUrlChanged (UrlChanged >> dispatch)\nrouter.children [\nHtml.section [\n...\n]\n]\n]\n let view model dispatch =\n+ React.router [\n+ router.onUrlChanged (UrlChanged >> dispatch)\n+ router.children [\n Html.section [\n ...\n ]\n+ ]\n+ ]\nThe routing should work now. Try navigating to localhost:8080; you should see a page with \"Page not Found\". If you go to localhost:8080/#/todo, you should see the todo app.
# sign
You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
"},{"location":"recipes/ui/add-routing/","title":"How do I add routing to a SAFE app with a shared model for all pages?","text":"When building larger apps, you probably want different pages to be accessible through different URLs. In this recipe, we show you how to add routes to different pages to an application, including adding a \"page not found\" page that is displayed when an unknown URL is entered.
In this recipe we use the simplest approach to storing states for multiple pages, by creating a single state for the full app. A potential benefit of this approach is that the state of a page is not lost when navigating away from it. You will see how that works at the end of the recipe.
"},{"location":"recipes/ui/add-routing/#1-adding-the-feliz-router","title":"1. Adding the Feliz router","text":"Install Feliz.Router in the client project
dotnet paket add Feliz.Router -p Client\nTo include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router\nAdd the current page to the model of the client, using a new Page type
type Page =\n| TodoList\n| NotFound\n\ntype Model =\n{ CurrentPage: Page\nTodos: Todo list\nInput: string }\n+ type Page =\n+ | TodoList\n+ | NotFound\n+\n- type Model = { Todos: Todo list; Input: string }\n+ type Model =\n+ { CurrentPage: Page\n+ Todos: Todo list\n+ Input: string }\nCreate a function to parse a URL to a page, including a wildcard for unmapped pages
let parseUrl url = match url with\n| [\"todo\"] -> Page.TodoList\n| _ -> Page.NotFound\nOn initialization, set the current page
CodeDifflet init () : Model * Cmd<Msg> =\nlet page = Router.currentUrl () |> parseUrl\n\nlet model =\n{ CurrentPage = page\nTodos = []\nInput = \"\" }\n...\nmodel, cmd\n let init () : Model * Cmd<Msg> =\n+ let page = Router.currentUrl () |> parseUrl\n+\n- let model = { Todos = []; Input = \"\" }\n+ let model =\n+ { CurrentPage = page\n+ Todos = []\n+ Input = \"\" }\n ...\n model, cmd\nAdd an action to handle navigation.
To the Msg type, add a PageChanged case of Page
type Msg =\n...\n| PageChanged of Page\n type Msg =\n ...\n+ | PageChanged of Page\nAdd the PageChanged update action
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch msg with\n...\n| PageChanged page -> { model with CurrentPage = page }, Cmd.none\n let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\n match msg with\n ...\n+ | PageChanged page -> { model with CurrentPage = page }, Cmd.none\nRename the view function to todoView
let todoView model dispatch =\nHtml.section [\n...\n]\n- let view model dispatch =\n+ let todoView model dispatch =\n Html.section [\n ...\n ]\nAdd a new view function, that returns the appropriate page
let view model dispatch =\nmatch model.CurrentPage with\n| TodoList -> todoView model dispatch\n| NotFound ->\nHtml.div [\nprop.className \"flex flex-col items-center justify-center h-full\"\nprop.text \"Page not found\"\n]\nAdding UI elements to every page of the website
In this recipe, we moved all the page content to the todoView, but you don't have to. You can add UI you want to display on every page of the application to the view function.
Add the React.Router element as the outermost element of the view. Dispatch the PageChanged event on onUrlChanged
let view (model: Model) (dispatch: Msg -> unit) =\nReact.router [\nrouter.onUrlChanged (parseUrl >> PageChanged >> dispatch)\nrouter.children [\nmatch model.CurrentPage with\n...\n]\n]\n let view (model: Model) (dispatch: Msg -> unit) =\n+ React.router [\n+ router.onUrlChanged (parseUrl >> PageChanged >> dispatch)\n router.children [\n match model.CurrentPage with\n ...\n ]\n ]\nThe routing should work now. Try navigating to localhost:8080; you should see a page with \"Page not Found\". If you go to localhost:8080/#/todo, you should see the todo app.
To see how the state is maintained even when navigating away from the page, type something in the text box and move away from the page by entering another path in the address bar. Then go back to the todo page. The entered text is still there.
# sign
You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
"},{"location":"recipes/ui/add-routing/#10-adding-more-pages","title":"10. Adding more pages","text":"Now that you have set up the routing, adding more pages is simple: add a new case to the Page type; add a route for this page in the parseUrl function; add a function that takes a model and dispatcher to generate your new page, and add a new case to the pattern match inside the view function to display the new case.
The default way to add extra styles is to add them using Tailwind classes. If you wish to use your own CSS stylesheets with SAFE apps, Vite can bundle them up for you.
There are two different approaches to adding your own CSS file, depending on what files you have available.
"},{"location":"recipes/ui/add-style/#method-a-import-into-indexcss","title":"Method A: Import intoindex.css","text":"The default template includes a stylesheet at src/Client/index.css which contains references to Tailwind. The cleanest way to add your own stylesheet is to create a new file e.g. src/Client/custom-style.css and then reference it from index.css.
src/Client, e.g. custom-style.cssindex.css +@import \"./custom-style.css\";\n@tailwind base;\n @tailwind components;\n @tailwind utilities;\nindex.css","text":"In order for Vite to know that there are styles to be bundled, you must import them into your app. By default this is already configured for index.css but if you don't have it set up, not to worry! Follow these steps:
src/Client, e.g. custom-style.cssApp.fs: open Fable.Core.JsInterop\nimportSideEffects \"./custom-style.css\"\nYou can now style your app by writing to the custom-style.css file.
Tailwind is a utility-first CSS framework which can be composed to build any design, directly in your markup.
As of SAFE version 5 (released in December 2023) it is included in the template by default so it can be used straight away.
If you are are using the minimal template or if you are upgrading from an old version of SAFE, continue reading for installation instructions.
Add a stylesheet to the project
Install the required npm packages
npm install -D tailwindcss postcss autoprefixer\ntailwind.config.js npx tailwindcss init\nAmend the tailwind.config.js as follows
/** @type {import('tailwindcss').Config} */\nmodule.exports = {\nmode: \"jit\",\ncontent: [\n\"./index.html\",\n\"./**/*.{fs,js,ts,jsx,tsx}\",\n],\ntheme: {\nextend: {},\n},\nplugins: [],\n}\nCreate a postcss.config.js with the following
module.exports = {\nplugins: {\ntailwindcss: {},\nautoprefixer: {},\n}\n}\nAdd the Tailwind layers to your stylesheet
@tailwind base;\n@tailwind components;\n@tailwind utilities;\nStart using tailwind classes e.g.
for todo in model.Todos do\nHtml.li [\nprop.classes [ \"text-red-200\" ]\nprop.text todo.Description\n]\nRemove the CDN reference from the index template in src/Client/index.html:
<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\">\nAdd styles from NPM. How do I add an NPM package to the client? In this example we will add the Bulma NPM package.
"},{"location":"recipes/ui/cdn-to-npm/#3-add-a-reference-to-your-stylesheet","title":"3. Add a reference to your stylesheet","text":"// Set variables to affect Bulma styles\n$body-color: #c6538c;\n@import 'bulma/bulma.sass';\nBy default, a full SAFE-stack application uses Tailwind CSS for styling. You might not always want to manage your styling using Tailwind, for example because you want to use a CSS framework like Bulma. In this recipe we describe how to fully remove Tailwind
"},{"location":"recipes/ui/remove-tailwind/#1-remove-tailwind-css-classes","title":"1. Remove Tailwind css classes","text":"Tailwind uses classes to style UI elements. In src/Client, search for all occurrences of prop.className and prop.classes and remove them if they are used for Tailwind support. In a vanilla SAFE template installation, this means removing all occurrences of prop.className.
Remove NPM packages that were installed for Tailwind using
npm uninstall tailwindcss postcss autoprefixer\nRemove the following files:
src/Client/postcss.config.js\nsrc/Client/tailwind.config.js\nsrc/Client/index.css\nYour SAFE Stack app is now Tailwind-free.
"},{"location":"recipes/ui/routing-with-elmish/","title":"How do I create multi-page applications with routing and the useElmish hook?","text":"UseElmish is a powerful package that allows you to write standalone components using Elmish. A component built around the UseElmish hook has its own view, state and update function.
In this recipe we add routing to a safe app, and implement the todo list page using the UseElmish hook.
Install Feliz.Router in the Client project
dotnet paket add Feliz.Router -p Client\nInstall Feliz.UseElmish in the Client project
cd src/Client\ndotnet femto install Feliz.UseElmish\nOpen the router in the client project
Index.fsopen Feliz.Router\nCreate a new Module TodoList in the client project. Move the following functions and types to the TodoList Module:
Also open Shared, Fable.Remoting.Client, Elmish and Feliz.
module TodoList\n\nopen Shared\nopen Fable.Remoting.Client\nopen Elmish\n\nopen Feliz\n\ntype Model = { Todos: Todo list; Input: string }\n\ntype Msg =\n| GotTodos of Todo list\n| SetInput of string\n| AddTodo\n| AddedTodo of Todo\n\nlet todosApi =\nRemoting.createApi ()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.buildProxy<ITodosApi>\n\nlet init () =\nlet model = { Todos = []; Input = \"\" }\nlet cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos\nmodel, cmd\n\nlet update msg model =\nmatch msg with\n| GotTodos todos -> { model with Todos = todos }, Cmd.none\n| SetInput value -> { model with Input = value }, Cmd.none\n| AddTodo ->\nlet todo = Todo.create model.Input\n\nlet cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n\n{ model with Input = \"\" }, cmd\n| AddedTodo todo ->\n{\nmodel with\nTodos = model.Todos @ [ todo ]\n},\nCmd.none\n\nlet private todoAction model dispatch =\nHtml.div [\nprop.className \"flex flex-col sm:flex-row mt-4 gap-4\"\nprop.children [\nHtml.input [\nprop.className\n\"shadow appearance-none border rounded w-full py-2 px-3 outline-none focus:ring-2 ring-teal-300 text-grey-darker\"\nprop.value model.Input\nprop.placeholder \"What needs to be done?\"\nprop.autoFocus true\nprop.onChange (SetInput >> dispatch)\nprop.onKeyPress (fun ev ->\nif ev.key = \"Enter\" then\ndispatch AddTodo)\n]\nHtml.button [\nprop.className\n\"flex-no-shrink p-2 px-12 rounded bg-teal-600 outline-none focus:ring-2 ring-teal-300 font-bold text-white hover:bg-teal disabled:opacity-30 disabled:cursor-not-allowed\"\nprop.disabled (Todo.isValid model.Input |> not)\nprop.onClick (fun _ -> dispatch AddTodo)\nprop.text \"Add\"\n]\n]\n]\n\n[<ReactComponent>]\nlet todoList model dispatch =\nHtml.div [\nprop.className \"bg-white/80 rounded-md shadow-md p-4 w-5/6 lg:w-3/4 lg:max-w-2xl\"\nprop.children [\nHtml.ol [\nprop.className \"list-decimal ml-6\"\nprop.children [\nfor todo in model.Todos do\nHtml.li [ prop.className \"my-1\"; prop.text todo.Description ]\n]\n]\n\ntodoAction model dispatch\n]\n]\nopen Feliz.UseElmish in the TodoList Module
TodoList.fsopen Feliz.UseElmish\n...\nIn the todoList module, rename the function todoList to view, and remove the private access modifier. On the first line, call React.useElmish, passing it the init and update functions. Bind the output to model and dispatch
let view model dispatch =\nlet model, dispatch = React.useElmish (init, update, [||])\n...\n-let containerBox model dispatch =\n+let view model dispatch =\n+ let model, dispatch = React.useElmish (init, update, [||])\n ...\nReplace the arguments of the function with unit, and add the ReactComponent attribute to it
[<ReactComponent>]\nlet view () =\n...\n+ [<ReactComponent>]\n- let view model dispatch =\n+ let view () =\n ...\nIn the Index module, create a model that holds the current page
type Page =\n| TodoList\n| NotFound\n\ntype Model =\n{ CurrentPage: Page }\nCreate a function that initializes the app based on an url
Index.fslet initFromUrl url =\nmatch url with\n| [ \"todo\" ] ->\nlet model = { CurrentPage = TodoList }\n\nmodel, Cmd.none\n| _ ->\nlet model = { CurrentPage = NotFound }\n\nmodel, Cmd.none\nCreate a new init function, that fetches the current url, and calls initFromUrl.
let init () = Router.currentUrl () |> initFromUrl\nAdd a Msg type, with an PageChanged case
Index.fs
type Msg = | PageChanged of string list\nupdate function, that reinitializes the app based on an URL Index.fslet update msg model =\nmatch msg with\n| PageChanged url -> initFromUrl url\nAdd a pageContent function to the Index module, that returns the appropriate page content
let pageContent model =\nmatch model.CurrentPage with\n| NotFound -> Html.text \"Page not found\"\n| TodoList -> TodoList.view ()\nIn the view function, replace the call to todoList with a call to pageContent
let view model dispatch =\nHtml.section [\n...\npageContent model\n...\n]\n let view model dispatch =\n Html.section [\n ...\n - todoList view model\n + pageContent model\n ...\n ]\nWrap the content of the view method in a React.Router element's router.children property, and add a router.onUrlChanged property to dispatch the urlChanged message
let view model dispatch =\nReact.router [\nrouter.onUrlChanged ( PageChanged>>dispatch )\nrouter.children [\nHtml.section [\n...\n]\n]\n]\nlet view (model: Model) (dispatch: Msg -> unit) =\n+ React.router [\n+ router.onUrlChanged ( PageChanged>>dispatch )\n+ router.children [\n Html.section [\n ...\n ]\n+ ]\n+ ]\nThe routing should work now. Try navigating to localhost:8080; you should see a page with \"Page not Found\". If you go to localhost:8080/#/todo, you should see the todo app.
# sign
You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
"},{"location":"recipes/upgrading/v2-to-v3/","title":"How do I upgrade from SAFE v2 to v3?","text":"There have been a number of changes between the second and third major versions of the SAFE template. This guide shows you how to upgrade your v2 project to v3.
If you haven't done so already then you will need to install the prequisites listed in the Quick Start guide.
"},{"location":"recipes/upgrading/v2-to-v3/#terminology-for-this-recipe","title":"Terminology for this Recipe:","text":"Download and install the latest SAFE Stack V3 template by running the following command:
dotnet new install SAFE.Template::3.1.1\nCreate a new SAFE project in the safetemp folder. We will use this as a basis for our conversion.
dotnet new SAFE -o safetemp\nWe advise committing or stashing any unsaved changes to your code and making a new branch to perform the upgrade.
You can then test it in isolation and then safely merge back in.
"},{"location":"recipes/upgrading/v2-to-v3/#4-update-dotnet-tools","title":"4. Update dotnet tools","text":"This file lists any custom dotnet tools used.
.config/dotnet-tools.json file.Important! If you have installed extra dotnet tools, you will need to add them back in manually.
"},{"location":"recipes/upgrading/v2-to-v3/#5-update-globaljson","title":"5. Update global.json","text":"global.json filepaket.dependencies file in the root of the solution.paket.lock file.paket.references files.Important If you have installed extra NuGet packages, you will need to add them back in manually to the dependencies and references files.
Run paket to update project references:
dotnet paket install\npaket.lock file.package.json filepackage-lock.json fileImportant If you have installed extra npm packages, you will need to add them back in manually to the dependencies.
"},{"location":"recipes/upgrading/v2-to-v3/#8-update-gitignore","title":"8. Update .gitignore","text":".gitignore file in the root of the solutionbuild.fsx FAKE script.Build.fs fileHelpers.fs fileBuild.fsproj projectpaket.references file (the one directly under the root directory)dotnet sln add Build.fsproj\nImportant If you have made any modifications to the build script e.g. extra targets, you will need to add them back in manually. You will also need to add any packages you added for the build to the paket.references file.
"},{"location":"recipes/upgrading/v2-to-v3/#10-update-the-webpack-config","title":"10. Update the webpack config","text":"webpack.config.js file.webpack.tests.config.js fileImportant If you have made any modifications to the webpack file, you will need to apply them back in manually.
Client.fsprojServer.fsprojShared.fsprojRun
dotnet run\nIf you have problems loading your website, carefully check that you haven't missed out any JavaScript or NuGet packages when overwriting the paket and package files. The console output will usually give you a good guide if this is the case.
"},{"location":"recipes/upgrading/v3-to-v4/","title":"How do I upgrade from SAFE v3 to v4?","text":"This guide shows you how to upgrade your v3 project to v4.
If you haven't done so already then you will need to install the prequisites listed in the Quick Start guide.
"},{"location":"recipes/upgrading/v3-to-v4/#terminology-for-this-recipe","title":"Terminology for this Recipe:","text":"Download and install the latest SAFE Stack V3 template by running the following command:
dotnet new install SAFE.Template\nCreate a new SAFE project in the safetemp folder. We will use this as a basis for our conversion.
dotnet new SAFE -o safetemp\nWe advise committing or stashing any unsaved changes to your code and making a new branch to perform the upgrade.
You can then test it in isolation and then safely merge back in.
"},{"location":"recipes/upgrading/v3-to-v4/#4-update-dotnet-tools","title":"4. Update dotnet tools","text":"This file lists any custom dotnet tools used.
.config/dotnet-tools.json file.Important! If you have installed extra dotnet tools, you will need to add them back in manually.
"},{"location":"recipes/upgrading/v3-to-v4/#5-update-globaljson","title":"5. Update global.json","text":"global.json filepaket.dependencies file in the root of the solution.paket.lock file.paket.references files.Important If you have installed extra NuGet packages, you will need to add them back in manually to the dependencies and references files.
Run paket to update project references:
dotnet paket install\npaket.lock file.package.json filepackage-lock.json fileImportant If you have installed extra npm packages, you will need to add them back in manually to the dependencies.
"},{"location":"recipes/upgrading/v3-to-v4/#8-update-gitignore","title":"8. Update .gitignore","text":".gitignore file in the root of the solutionBuild.fs fileBuild.fsproj fileImportant If you have made any modifications to the build script e.g. extra targets, you will need to add them back in manually.
"},{"location":"recipes/upgrading/v3-to-v4/#10-update-the-webpack-config","title":"10. Update the webpack config","text":"webpack.config.js file.webpack.tests.config.js fileImportant If you have made any modifications to the webpack file, you will need to apply them back in manually.
"},{"location":"recipes/upgrading/v3-to-v4/#11-update-targetframework-in-all-projects","title":"11. Update TargetFramework in all projects","text":"Client.Tests.fsproj fileServer.Tests.fsproj fileShared.Tests.fsproj fileClient.fsproj fileServer.fsproj fileShared.fsproj fileFor all of the above, change <TargetFramework>net5.0</TargetFramework> to <TargetFramework>net6.0</TargetFramework>
Server/Properties/launch.json fileRun
dotnet run\nIf you have problems loading your website, carefully check that you haven't missed out any JavaScript or NuGet packages when overwriting the paket and package files. The console output will usually give you a good guide if this is the case.
"},{"location":"recipes/upgrading/v3-to-v4/#issues","title":"Issues","text":"On mac you might get an error like this:
> dotnet run\ndotnet watch \ud83d\ude80 Started\n/Users/espen/code/dotnet-new-safe-4.1.1/.paket/Paket.Restore.targets(219,5): error MSB3073: The command \"dotnet paket restore --project \"/Users/espen/code/dotnet-new-safe-4.1.1/src/Shared/Shared.fsproj\" --output-path \"obj\" --target-framework \"net6.0\"\" exited with code 134. [/Users/espen/code/dotnet-new-safe-4.1.1/src/Shared/Shared.fsproj]\n\nThe build failed. Fix the build errors and run again.\ndotnet watch \u274c Exited with error code 1\ndotnet watch \u23f3 Waiting for a file to change before restarting dotnet...\n^Cdotnet watch \ud83d\uded1 Shutdown requested. Press Ctrl+C again to force exit.\nIf so, try uninstalling all .NET SDKs and runtimes below 3.0.100. See NET uninstall tool for how to unistall SDKs on mac.
"},{"location":"recipes/upgrading/v4-to-v5/","title":"How do I upgrade from SAFE v4 to v5?","text":""},{"location":"recipes/upgrading/v4-to-v5/#f-tools-and-dependencies","title":"F# tools and dependencies","text":"Get the latest dotnet tools such as Fable and Fantomas into your repository.
dotnet-tools.json file from here.dotnet tool restore.Use our preferred F# formatting style.
.editorconfig file from here.Migrate all dependencies to .NET 8.
Overwrite your global.json file from here.
Update each of your project files to target .NET 8.
<PropertyGroup>\n<TargetFramework>net8.0</TargetFramework>\n</PropertyGroup>\nUpgrade all .NET dependencies to the latest versions for SAFE v5:
dotnet paket remove Fable.React -p Client.dotnet paket remove Feliz.Bulma -p Client.paket.dependencies file from here.paket.lock file from here.paket.references file from here.dotnet paket install to update the Shared project.cd into the required project.dotnet paket add <package> --keep-minor. This will download the latest version of the package you required but will not update any associated dependencies outside of their existing major version.package.json with this file.package-lock.json with this file.webpack.config.jssrc/Client/vite.config.mts file from here.Install Tailwind.
npx tailwindcss init -p in src/Clientsrc/Client/tailwind.config.js file from here.src/Client/index.css file from here.Update HTML and F# code.
src/Client/index.html with this file.src/Client/App.fs, after the existing open declarations open Fable.Core.JsInterop\n\nimportSideEffects \"./index.css\"\ntests/Client/vite.config.mts from here.tests/Client/index.html file from here..fantomasignore from here.In the Build.fs file replace the following lines:
Line 27:
- \"client\", dotnet [ \"fable\"; \"-o\"; \"output\"; \"-s\"; \"--run\"; \"npm\"; \"run\"; \"build\" ] clientPath ]\n+ \"client\", dotnet [ \"fable\"; \"-o\"; \"output\"; \"-s\"; \"--run\"; \"npx\"; \"vite\"; \"build\" ] clientPath ]\nLine 35:
- operating_system OS.Windows\n- runtime_stack Runtime.DotNet60\n+ operating_system OS.Linux\n+ runtime_stack (DotNet \"8.0\")\nLine 51:
- \"client\", dotnet [ \"fable\"; \"watch\"; \"-o\"; \"output\"; \"-s\"; \"--run\"; \"npm\"; \"run\"; \"start\" ] clientPath ]\n+ \"client\", dotnet [ \"fable\"; \"watch\"; \"-o\"; \"output\"; \"-s\"; \"--run\"; \"npx\"; \"vite\" ] clientPath ]\nLine 58:
- \"client\", dotnet [ \"fable\"; \"watch\"; \"-o\"; \"output\"; \"-s\"; \"--run\"; \"npm\"; \"run\"; \"test:live\" ] clientTestsPath ]\n+ \"client\", dotnet [ \"fable\"; \"watch\"; \"-o\"; \"output\"; \"-s\"; \"--run\"; \"npx\"; \"vite\" ] clientTestsPath ]\nNote: If you are using a template created prior to version v4.3, you may have the following string syntax for the dotnet commands and therefore the change you need to make will be slightly different.
- \"client\", dotnet \"fable -o output -s --run npm run build\" clientPath\n+ \"client\", dotnet \"fable -o output -s --run npx vite build\" clientPath\nTailwind CSS Intellisense extension..vscode/settings.json file from here. The regexes in this file are for Feliz style DSL, if you want to support Fable.React DSL you will need to adapt the regexes.Fake is a DSL for build tasks that is modular, extensible and easy to start with. Fake allows you to easily build, bundle, deploy your app and more by executing a single command.
The standard template comes with a FAKE project by default, so this recipe only applies to the minimal template.
"},{"location":"v4-recipes/build/add-build-script/#1-create-a-build-project","title":"1. Create a build project","text":"Create a new console app called 'Build' at the root of your solution
dotnet new console -lang f# -n Build -o .\nWe are creating the project directly at the root of the solution in order to allow us to execute the build without needing to navigate into a subfolder.
"},{"location":"v4-recipes/build/add-build-script/#2-create-a-build-script","title":"2. Create a build script","text":"Open the project you just created in your IDE and rename the module it contains from Program.fs to Build.fs.
This renaming isn't explicitly necessary, however it keeps your solution consistent with other SAFE apps and is a better name for the file really.
If you just rename the file directly rather than in your IDE, then the Build project won't be able to find it unless you edit the Build.fsproj file as well
Open Build.fs and paste in the following code.
open Fake.Core\nopen Fake.IO\nopen System\n\nlet redirect createProcess =\ncreateProcess\n|> CreateProcess.redirectOutputIfNotRedirected\n|> CreateProcess.withOutputEvents Console.WriteLine Console.WriteLine\n\nlet createProcess exe arg dir =\nCreateProcess.fromRawCommandLine exe arg\n|> CreateProcess.withWorkingDirectory dir\n|> CreateProcess.ensureExitCode\n\nlet dotnet = createProcess \"dotnet\"\n\nlet npm =\nlet npmPath =\nmatch ProcessUtils.tryFindFileOnPath \"npm\" with\n| Some path -> path\n| None -> failwith \"npm was not found in path.\"\ncreateProcess npmPath\n\nlet run proc arg dir =\nproc arg dir\n|> Proc.run\n|> ignore\n\nlet execContext = Context.FakeExecutionContext.Create false \"build.fsx\" [ ]\nContext.setExecutionContext (Context.RuntimeContext.Fake execContext)\n\nTarget.create \"Clean\" (fun _ -> Shell.cleanDir (Path.getFullName \"deploy\"))\n\nTarget.create \"InstallClient\" (fun _ -> run npm \"install\" \".\")\n\nTarget.create \"Run\" (fun _ ->\nrun dotnet \"build\" (Path.getFullName \"src/Shared\")\n[ dotnet \"watch run\" (Path.getFullName \"src/Server\")\ndotnet \"fable watch --run webpack-dev-server\" (Path.getFullName \"src/Client\") ]\n|> Seq.toArray\n|> Array.map redirect\n|> Array.Parallel.map Proc.run\n|> ignore\n)\n\nopen Fake.Core.TargetOperators\n\nlet dependencies = [\n\"Clean\"\n==> \"InstallClient\"\n==> \"Run\"\n]\n\n[<EntryPoint>]\nlet main args =\ntry\nmatch args with\n| [| target |] -> Target.runOrDefault target\n| _ -> Target.runOrDefault \"Run\"\n0\nwith e ->\nprintfn \"%A\" e\n1\nRun the following command
dotnet sln add Build.fsproj\nYou will need to install the following dependencies:
Fake.Core.Target\nFake.IO.FileSystem\nWe recommend migrating to Paket. It is possible to use FAKE without Paket, however this will not be covered in this recipe.
"},{"location":"v4-recipes/build/add-build-script/#5-run-the-app","title":"5. Run the app","text":"At the root of the solution, run dotnet paket install to install all your dependencies.
If you now execute dotnet run, the default target will be run. This will build the app in development mode and launch it locally.
To learn more about targets and FAKE in general, see Getting Started with FAKE.
"},{"location":"v4-recipes/build/bundle-app/","title":"How do I bundle my SAFE application?","text":"When developing your SAFE application, the local runtime experience uses WebPack to run the client and redirect API calls to the server on a different port. However, when you deploy your application, you'll need to run your Saturn server which will serve up statically-built client resources (HTML, JavaScript, CSS etc.).
"},{"location":"v4-recipes/build/bundle-app/#im-using-the-standard-template","title":"I'm using the standard template","text":""},{"location":"v4-recipes/build/bundle-app/#1-run-the-fake-script","title":"1. Run the FAKE script","text":"If you created your SAFE app using the recommended defaults, your application already has a FAKE script which will do the bundling for you. You can create a bundle using the following command:
dotnet run Bundle\nThis will build and package up both the client and server and place them into the /deploy folder at the root of the repository.
See here for more details on this build target.
"},{"location":"v4-recipes/build/bundle-app/#im-using-the-minimal-template","title":"I'm using the minimal template","text":"If you created your SAFE app using the minimal option, you need to bundle up the client and server separately.
"},{"location":"v4-recipes/build/bundle-app/#1-bundle-the-client-fable-application","title":"1. Bundle the Client (Fable) application","text":"Execute the following commands:
npm install\n\ndotnet tool restore \n\ndotnet fable src/Client --run webpack\nThis will build the client project and copy all outputs into /deploy/public.
Execute the following commands:
cd src/Server\ndotnet publish -c release -o ../../deploy\nThis will bundle the server project and copy all outputs into the deploy folder.
deploy folder at the root of your repository.Server.exe application.http://localhost:5000.You should now see your SAFE application.
"},{"location":"v4-recipes/build/bundle-app/#further-reading","title":"Further reading","text":"See this article for more information on architectural concerns regarding the move from dev to production and bundling SAFE Stack applications.
"},{"location":"v4-recipes/build/docker-image/","title":"How do I build with docker?","text":"Using Docker makes it possible to deploy your application as a docker container or release an image on docker hub. This recipe walks you through creating a Dockerfile and automating the build and test process with Docker Hub.
Create a .dockerignore file with the same contents as .gitignore
cp .gitignore .dockerignore\ncopy .gitignore .dockerignore\nNow, add the following lines to the .dockerignore file:
.git\nCreate a Dockerfile with the following contents:
FROM mcr.microsoft.com/dotnet/sdk:6.0 as build\n\n# Install node\nRUN curl -sL https://deb.nodesource.com/setup_16.x | bash\nRUN apt-get update && apt-get install -y nodejs\n\nWORKDIR /workspace\nCOPY . .\nRUN dotnet tool restore\n\nRUN dotnet run Bundle\n\n\nFROM mcr.microsoft.com/dotnet/aspnet:6.0-alpine\nCOPY --from=build /workspace/deploy /app\nWORKDIR /app\nEXPOSE 5000\nENTRYPOINT [ \"dotnet\", \"Server.dll\" ]\nThis uses multistage builds to keep the final image small.
"},{"location":"v4-recipes/build/docker-image/#using-the-minimal-template","title":"Using the minimal template?","text":"Replace the line
RUN dotnet run Bundle\nwith
RUN npm install\nRUN dotnet fable src/Client --run webpack\nRUN cd src/Server && dotnet publish -c release -o ../../deploy\ndocker build -t my-safe-app .docker run -it -p 5000:80 my-safe-appBecause the build is done entirely in docker, Docker Hub automated builds can be setup to automatically build and push the docker image.
"},{"location":"v4-recipes/build/docker-image/#4-testing-the-server","title":"4. Testing the server","text":"Create a docker-compose.server.test.yml file with the following contents:
version: '3.4'\nservices:\n sut:\n build:\n target: build\n context: .\n working_dir: /workspace/tests/Server\n command: dotnet run\ndocker-compose -f docker-compose.server.test.yml up --build You can add server tests to the minimal template with the testing the server recipe.
The template is not currently setup for automating the client tests in ci.
Docker Hub can also run automated tests for you.
Follow the instructions to enable Autotest on docker hub.
"},{"location":"v4-recipes/build/docker-image/#5-making-the-docker-build-faster","title":"5. Making the docker build faster","text":"Not recommended for most applications
If you often build with docker locally, you may wish to make the build faster by optimising the Dockerfile for caching. For example, it is not necessary to download all paket and npm dependencies on every build unless there have been changes to the dependencies.
Furthermore, the client and server can be built in separate build stages so that they are cached independently. Enable Docker BuildKit to build them concurrently.
This comes at the expense of making the dockerfile more complex; if any changes are made to the build such as adding new projects or migrating package managers, the dockerfile must be updated accordingly.
The following should be a good starting point but is not guarenteed to work.
FROM mcr.microsoft.com/dotnet/sdk:6.0 as build\n\n# Install node\nRUN curl -sL https://deb.nodesource.com/setup_16.x | bash\nRUN apt-get update && apt-get install -y nodejs\n\nWORKDIR /workspace\nCOPY .config .config\nRUN dotnet tool restore\nCOPY .paket .paket\nCOPY paket.dependencies paket.lock ./\n\nFROM build as server-build\nCOPY src/Shared src/Shared\nCOPY src/Server src/Server\nRUN cd src/Server && dotnet publish -c release -o ../../deploy\n\n\nFROM build as client-build\nCOPY package.json package-lock.json ./\nRUN npm install\nCOPY webpack.config.js ./\nCOPY src/Shared src/Shared\nCOPY src/Client src/Client\nRUN dotnet fable src/Client --run webpack\n\n\nFROM mcr.microsoft.com/dotnet/aspnet:6.0-alpine\nCOPY --from=server-build /workspace/deploy /app\nCOPY --from=client-build /workspace/deploy /app\nWORKDIR /app\nEXPOSE 5000\nENTRYPOINT [ \"dotnet\", \"Server.dll\" ]\nFAKE is a tool for build automation. The standard SAFE template comes with a ready-made build project at the root of the solution that provides support for many common SAFE tasks.
If you would prefer not to use FAKE, you can of course simply ignore it, but this recipes shows how to completely remove it from your repository. It is important to note that having removed FAKE, you will have to follow a more manual approach to each of these processes. This recipe will only include instructions on how to build and deploy the application after removing FAKE.
Note that the minimal template does not use FAKE by default, and this recipe only applies to the standard template.
"},{"location":"v4-recipes/build/remove-fake/#1-build-project","title":"1. Build project","text":"Delete Build.fs, Build.fsproj, Helpers.fs, paket.references at the root of the solution.
Remove the following dependencies
dotnet paket remove Fake.Core.Target\ndotnet paket remove Fake.IO.FileSystem\ndotnet paket remove Farmer\nNow that you have the FAKE dependencies removed, you will have to separately run the server and the client.
"},{"location":"v4-recipes/build/remove-fake/#1-start-the-server","title":"1. Start the Server","text":"Navigate to src/Server inside a terminal and execute dotnet run.
Execute the following commands inside a terminal at the root of the solution.
dotnet tool restore\nnpm install\ndotnet fable src/Client --run webpack-dev-server\nThe app will now be running at http://0.0.0.0:8080/. Navigate to this address in a browser to see your app running.
See this guide to learn how to package a SAFE application for deployment to e.g. Azure.
"},{"location":"v4-recipes/client-server/fable-remoting/","title":"How Do I Add Support for Fable Remoting?","text":"Fable Remoting is a type-safe RPC communication layer for SAFE apps. It uses HTTP behind the scenes, but allows you to program against protocols that exist across the application without needing to think about the HTTP plumbing, and is a great fit for the majority of SAFE applications.
Note that the standard template uses Fable Remoting. This recipe only applies to the minimal template.
"},{"location":"v4-recipes/client-server/fable-remoting/#1-install-nuget-packages","title":"1. Install NuGet Packages","text":"Add Fable.Remoting.Giraffe to the Server and Fable.Remoting.Client to the Client.
See How Do I Add a NuGet Package to the Server and How Do I Add a NuGet Package to the Client.
"},{"location":"v4-recipes/client-server/fable-remoting/#2-create-the-api-protocol","title":"2. Create the API protocol","text":"You now need to create the protocol, or contract, of the API we\u2019ll be creating. Insert the following below the Route module in Shared.fs:
type IMyApi =\n{ hello : unit -> Async<string> }\nWe need to provide a basic routing function in order to ensure client and server communicate on the same endpoint. Find the Route module in src/Shared/Shared.fs and replace it with the following:
module Route =\nlet builder typeName methodName =\nsprintf \"/api/%s/%s\" typeName methodName\nWe now need to provide an implementation of the protocol on the server. Open src/Server/Server.fs and insert the following right after the open statements:
let myApi =\n{ hello = fun () -> async { return \"Hello from SAFE!\" } }\nWe now need to \"adapt\" Fable Remoting into the ASP.NET pipeline by converting it into a Giraffe HTTP Handler. Don't worry - this is not hard. Find webApp in Server.fs and replace it with the following:
open Fable.Remoting.Server\nopen Fable.Remoting.Giraffe\n\nlet webApp =\nRemoting.createApi()\n|> Remoting.withRouteBuilder Route.builder // use the routing function from step 3\n|> Remoting.fromValue myApi // use the myApi implementation from step 4\n|> Remoting.buildHttpHandler // adapt it to Giraffe's HTTP Handler\nWe now need a corresponding client proxy in order to be able to connect to the server. Open src/Client/Client.fs and insert the following right after the Msg type:
open Fable.Remoting.Client\n\nlet myApi =\nRemoting.createApi()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.buildProxy<IMyApi>\nReplace the following two lines in the init function in Client.fs:
let getHello() = Fetch.get<unit, string> Route.hello\nlet cmd = Cmd.OfPromise.perform getHello () GotHello\nwith this:
let cmd = Cmd.OfAsync.perform myApi.hello () GotHello\nAt this point, the app should work just as it did before. Now, expanding the API and adding a new endpoint is as easy as adding a new field to the API protocol we defined in Shared.fs, editing the myApi record in Server.fs with the implementation, and finally making calls from the proxy.
First off, you need to create a SAFE app, install the relevant dependencies, and wire them up to be available for use in your F# Fable code.
Create a new SAFE app and restore local tools:
dotnet new SAFE\ndotnet tool restore\nInstall Fable.Form.Simple.Bulma using Paket:
dotnet paket add --project src/Client/ Fable.Form.Simple.Bulma --version 3.0.0\nInstall bulma and fable-form-simple-bulma npm packages:
npm add fable-form-simple-bulma\nnpm add bulma@0.9.0\nCreate ./src/Client/style.scss with the following contents:
@import \"~bulma\";\n@import \"~fable-form-simple-bulma\";\n+@import \"~bulma\";\n+@import \"~fable-form-simple-bulma\";\nUpdate webpack config to include the new stylesheet:
a. Add a cssEntry property to the CONFIG object:
cssEntry: './src/Client/style.scss',\n+cssEntry: './src/Client/style.scss',\nb. Modify the entry property of the object returned from module.exports to include cssEntry:
entry: isProduction ? {\napp: [resolve(config.fsharpEntry), resolve(config.cssEntry)]\n} : {\napp: resolve(config.fsharpEntry),\nstyle: resolve(config.cssEntry)\n},\n- entry: {\n- app: resolve(config.fsharpEntry)\n- },\n+ entry: isProduction ? {\n+ app: [resolve(config.fsharpEntry), resolve(config.cssEntry)]\n+ } : {\n+ app: resolve(config.fsharpEntry),\n+ style: resolve(config.cssEntry)\n+ },\nRemove the Bulma stylesheet link from ./src/Client/index.html, as it is no longer needed:
<link rel=\"icon\" type=\"image/png\" href=\"/favicon.png\"/>\n- <link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\">\n <link rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css\">\nWith the above preparation done, you can use Fable.Form.Simple.Bulma in your ./src/Client/Index.fs file.
Open the newly added namespaces:
CodeDiff Index.fsopen Fable.Form.Simple\nopen Fable.Form.Simple.Bulma\n+open Fable.Form.Simple\n+open Fable.Form.Simple.Bulma\nCreate type Values to represent each input field on the form (a single textbox), and create a type Form which is an alias for Form.View.Model<Values>:
type Values = { Todo: string }\ntype Form = Form.View.Model<Values>\n+type Values = { Todo: string }\n+type Form = Form.View.Model<Values>\nIn the Model type definition, replace Input: string with Form: Form
type Model = { Todos: Todo list; Form: Form }\n-type Model = { Todos: Todo list; Input: string }\n+type Model = { Todos: Todo list; Form: Form }\nUpdate the init function to reflect the change in Model:
let model = { Todos = []; Form = Form.View.idle { Todo = \"\" } }\n-let model = { Todos = []; Input = \"\" }\n+let model = { Todos = []; Form = Form.View.idle { Todo = \"\" } }\nChange Msg discriminated union - replace the SetInput case with FormChanged of Form, and add string data to the AddTodo case:
type Msg =\n| GotTodos of Todo list\n| FormChanged of Form\n| AddTodo of string\n| AddedTodo of Todo\ntype Msg =\n | GotTodos of Todo list\n- | SetInput of string\n- | AddTodo\n+ | FormChanged of Form\n+ | AddTodo of string\n | AddedTodo of Todo\nModify the update function to handle the changed Msg cases:
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch msg with\n| GotTodos todos -> { model with Todos = todos }, Cmd.none\n| FormChanged form -> { model with Form = form }, Cmd.none\n| AddTodo todo ->\nlet todo = Todo.create todo\nlet cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\nmodel, cmd\n| AddedTodo todo ->\nlet newModel =\n{ model with\nTodos = model.Todos @ [ todo ]\nForm =\n{ model.Form with\nState = Form.View.Success \"Todo added\"\nValues = { model.Form.Values with Todo = \"\" } } }\nnewModel, Cmd.none\nlet update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\n match msg with\n | GotTodos todos -> { model with Todos = todos }, Cmd.none\n- | SetInput value -> { model with Input = value }, Cmd.none\n+ | FormChanged form -> { model with Form = form }, Cmd.none\n- | AddTodo ->\n- let todo = Todo.create model.Input\n- let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n- { model with Input = \"\" }, cmd\n+ | AddTodo todo ->\n+ let todo = Todo.create todo\n+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n+ model, cmd\n- | AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none\n+ | AddedTodo todo ->\n+ let newModel =\n+ { model with\n+ Todos = model.Todos @ [ todo ]\n+ Form =\n+ { model.Form with\n+ State = Form.View.Success \"Todo added\"\n+ Values = { model.Form.Values with Todo = \"\" } } }\n+ newModel, Cmd.none\nCreate form. This defines the logic of the form, and how it responds to interaction:
let form : Form.Form<Values, Msg, _> =\nlet todoField =\nForm.textField\n{\nParser = Ok\nValue = fun values -> values.Todo\nUpdate = fun newValue values -> { values with Todo = newValue }\nError = fun _ -> None\nAttributes =\n{\nLabel = \"New todo\"\nPlaceholder = \"What needs to be done?\"\nHtmlAttributes = []\n}\n}\n\nForm.succeed AddTodo\n|> Form.append todoField\n+let form : Form.Form<Values, Msg, _> =\n+ let todoField =\n+ Form.textField\n+ {\n+ Parser = Ok\n+ Value = fun values -> values.Todo\n+ Update = fun newValue values -> { values with Todo = newValue }\n+ Error = fun _ -> None\n+ Attributes =\n+ {\n+ Label = \"New todo\"\n+ Placeholder = \"What needs to be done?\"\n+ HtmlAttributes = []\n+ }\n+ }\n+\n+ Form.succeed AddTodo\n+ |> Form.append todoField\nIn the function containerBox, remove the existing form view. Then replace it using Form.View.asHtml to render the view:
let containerBox (model: Model) (dispatch: Msg -> unit) =\nBulma.box [\nBulma.content [\nHtml.ol [\nfor todo in model.Todos do\nHtml.li [ prop.text todo.Description ]\n]\n]\nForm.View.asHtml\n{\nDispatch = dispatch\nOnChange = FormChanged\nAction = Form.View.Action.SubmitOnly \"Add\"\nValidation = Form.View.Validation.ValidateOnBlur\n}\nform\nmodel.Form\n]\nlet containerBox (model: Model) (dispatch: Msg -> unit) =\n Bulma.box [\n Bulma.content [\n Html.ol [\n for todo in model.Todos do\n Html.li [ prop.text todo.Description ]\n ]\n ]\n- Bulma.field.div [\n- ... removed for brevity ...\n- ]\n+ Form.View.asHtml\n+ {\n+ Dispatch = dispatch\n+ OnChange = FormChanged\n+ Action = Form.View.Action.SubmitOnly \"Add\"\n+ Validation = Form.View.Validation.ValidateOnBlur\n+ }\n+ form\n+ model.Form\n ]\nWith the basic structure in place, it's easy to add functionality to the form. For example, the changes necessary to add a high priority checkbox are pretty small.
"},{"location":"v4-recipes/client-server/messaging-post/","title":"How do I send and receive data using POST?","text":"This recipe shows how to create an endpoint on the server and hook up it up to the client using HTTP POST. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
A POST endpoint is normally used to send data from the client to the server in the body, for example from a form. This is useful when we need to supply more data than can easily be provided in the URI.
You may wish to use POST for \"write\" operations and use GETs for \"reads\", however this is a highly opinionated topic that is beyond the scope of this recipe.
"},{"location":"v4-recipes/client-server/messaging-post/#im-using-the-standard-template-fable-remoting","title":"I'm using the standard template (Fable Remoting)","text":"Fable Remoting takes care of deciding whether to use POST or GET etc. - you don't have to worry about this. Refer to this recipe for more details.
"},{"location":"v4-recipes/client-server/messaging-post/#im-using-the-minimal-template-raw-http","title":"I'm using the minimal template (Raw HTTP)","text":""},{"location":"v4-recipes/client-server/messaging-post/#in-shared","title":"In Shared","text":""},{"location":"v4-recipes/client-server/messaging-post/#1-create-contract","title":"1. Create contract","text":"Create the type that will store the payload sent from the client to the server.
type SaveCustomerRequest =\n{ Name : string\nAge : int }\nCreate a new function saveCustomer that will call the server. It supplies the customer to save, which is serialized and sent to the server in the body of the message.
let saveCustomer customer =\nlet save customer = Fetch.post<SaveCustomerRequest, int> (\"/api/customer\", customer)\nCmd.OfPromise.perform save customer CustomerSaved\nThe generic arguments of Fetch.post are the input and output types. The example above shows that the input is of type SaveCustomerRequest with the response will contain an integer value. This may be the ID generated by the server for the save operation.
This can now be called from within your update function e.g.
| SaveCustomer request ->\nmodel, saveCustomer request\n| CustomerSaved generatedId ->\n{ model with GeneratedCustomerId = Some generatedId; Message = \"Saved customer!\" }, Cmd.none\nCreate a function that can extract the payload from the body of the request using Giraffe's built-in model binding support:
open FSharp.Control.Tasks\nopen Giraffe\nopen Microsoft.AspNetCore.Http\nopen Shared\n\n/// Extracts the request from the body and saves to the database.\nlet saveCustomer next (ctx:HttpContext) = task {\nlet! customer = ctx.BindModelAsync<SaveCustomerRequest>()\ndo! Database.saveCustomer customer\nreturn! Successful.OK \"Saved customer\" next ctx\n}\nTie your function into the router, using the post verb instead of get.
let webApp = router {\npost \"/api/customer\" saveCustomer // Add this\n}\nThis recipe shows how to create an endpoint on the server and hook up it up to the client. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
"},{"location":"v4-recipes/client-server/messaging/#im-using-the-standard-template-fable-remoting","title":"I'm using the standard template (Fable Remoting)","text":"Fable Remoting is a library which allows you to create client/server messaging without any need to think about HTTP verbs or serialization etc.
"},{"location":"v4-recipes/client-server/messaging/#in-shared","title":"In Shared","text":""},{"location":"v4-recipes/client-server/messaging/#1-update-contract","title":"1. Update contract","text":"Add your new endpoint onto an existing API contract e.g. ITodosApi. Because Fable Remoting exposes your API through F# on client and server, you get type safety across both.
type ITodosApi =\n{ getCustomer : int -> Async<Customer option> }\nCreate a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required.
let loadCustomer customerId = async {\nreturn Some { Name = \"My Customer\" }\n}\nNote the use of async here. Fable Remoting uses async workflows, and not tasks. You can write functions that use task, but will have to at some point map to async using Async.AwaitTask.
Tie the function you've just written into the API implementation.
let todosApi =\n{ ///...\ngetCustomer = loadCustomer\n}\nTest out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc. See here for more details on the required format.
"},{"location":"v4-recipes/client-server/messaging/#on-the-client","title":"On the client","text":""},{"location":"v4-recipes/client-server/messaging/#1-call-the-endpoint","title":"1. Call the endpoint","text":"Create a new function loadCustomer that will call the endpoint.
let loadCustomer customerId =\nCmd.OfAsync.perform todosApi.getCustomer customerId LoadedCustomer\nNote the final value supplied, CustomerLoaded. This is the Msg case that will be sent into the Elmish loop once the call returns, with the returned data. It should take in a value that matches the type returned by the Server e.g. CustomerLoaded of Customer option. See here for more information.
This can now be called from within your update function e.g.
| LoadCustomer customerId ->\nmodel, loadCustomer customerId\nThis recipe shows how to create a GET endpoint on the server and consume it on the client using the Fetch API.
"},{"location":"v4-recipes/client-server/messaging/#on-the-server_1","title":"On the Server","text":""},{"location":"v4-recipes/client-server/messaging/#1-write-implementation_1","title":"1. Write implementation","text":"Create a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required.
open Saturn\nopen FSharp.Control.Tasks\n\n/// Loads a customer from the DB and returns as a Customer in json.\nlet loadCustomer (customerId:int) next ctx = task {\nlet customer = { Name = \"My Customer\" }\nreturn! json customer next ctx\n}\nNote how we parameterise this function to take in the customerId as the first argument. Any parameters you need should be supplied in this manner. If you do not need any parameters, just omit them and leave the next and ctx ones.
This example does not cover dealing with \"missing\" data e.g. invalid customer ID is found.
"},{"location":"v4-recipes/client-server/messaging/#2expose-your-function","title":"2.Expose your function","text":"Tie the function into the router with a route.
let webApp = router {\ngetf \"/api/customer/%i\" loadCustomer // Add this\n}\nNote the use of getf rather than get. If you do not need any parameters, just use get. See here for reference docs on the use of the Saturn router.
Test out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc.
"},{"location":"v4-recipes/client-server/messaging/#on-the-client_1","title":"On the client","text":""},{"location":"v4-recipes/client-server/messaging/#1-call-the-endpoint_1","title":"1. Call the endpoint","text":"Create a new function loadCustomer that will call the endpoint.
This example uses Thoth.Fetch to download and deserialise the response.
let loadCustomer customerId =\nlet loadCustomer () = Fetch.get<unit, Customer> (sprintf \"/api/customer/%i\" customerId)\nCmd.OfPromise.perform loadCustomer () CustomerLoaded\nNote the final value supplied, CustomerLoaded. This is the Msg case that will be sent into the Elmish loop once the call returns, with the returned data. It should take in a value that matches the type returned by the Server e.g. CustomerLoaded of Customer. See here for more information.
An alternative (and slightly more succinct) way of writing this is:
let loadCustomer customerId =\nlet loadCustomer = sprintf \"/api/customer/%i\" >> Fetch.get<unit, Customer>\nCmd.OfPromise.perform loadCustomer customerId CustomerLoaded\nThis can now be called from within your update function e.g.
| LoadCustomer customerId ->\nmodel, loadCustomer customerId\nThis recipe demonstrates the steps you need to take to store new data on the client using the MVU pattern, which is typically read from the Server. You will learn the steps required to modify the model, update and view functions to handle a button click which requests data from the server and handles the response.
"},{"location":"v4-recipes/client-server/mvu-roundtrip/#in-shared","title":"In Shared","text":""},{"location":"v4-recipes/client-server/mvu-roundtrip/#1-create-shared-domain","title":"1. Create shared domain","text":"Create a type in the Shared project which will act as the contract type between client and server. As SAFE compiles F# into JavaScript for you, you only need a single definition which will automatically be shared.
type Customer = { Name : string }\nModify the Msg type to have two new messages:
type Msg =\n// other messages ...\n| LoadCustomer of customerId:int // Add this\n| CustomerLoaded of Customer // Add this\nYou will see that this symmetrical pattern is often followed in MVU:
Update the Model to store the Customer once it is loaded:
type Model =\n{ // ...\nTheCustomer : Customer option }\nMake TheCustomer optional so that it can be initialised as None (see next step).
Update the init function to provide default data
let model =\n{ // ...\nTheCustomer = None }\nUpdate your view to initiate the LoadCustomer event. Here, we create a button that will start loading customer 42 on click:
let view model dispatch =\nHtml.div [\n// ...\nHtml.button [ prop.onClick (fun _ -> dispatch (LoadCustomer 42)) prop.text \"Load Customer\"\n]\n]\nModify the update function to handle the new messages:
let update msg model =\nmatch msg with\n// ....\n| LoadCustomer customerId ->\n// Implementation to connect to the server to be defined.\n| CustomerLoaded c ->\n{ model with TheCustomer = Some c }, Cmd.none\nThe code to fire off the message to the server differs depending on the client / server communication you are using and normally whether you are reading or writing data. See here for more information.
"},{"location":"v4-recipes/client-server/saturn-to-giraffe/","title":"How do I use Giraffe instead of Saturn?","text":"Saturn is a functional alternative to MVC and Razor which sits on top of Giraffe. Giraffe itself is a functional wrapper around the ASP.NET Core web framework, making it easier to work with when using F#.
Since Saturn is built on top of Giraffe, migrating to using \"raw\" Giraffe is relatively simple to do.
"},{"location":"v4-recipes/client-server/saturn-to-giraffe/#bootstrapping-the-application","title":"Bootstrapping the Application","text":""},{"location":"v4-recipes/client-server/saturn-to-giraffe/#1-open-libraries","title":"1. Open libraries","text":"Navigate to the Server module in the Server project.
Remove
open Saturn\nopen Giraffe\nopen Microsoft.AspNetCore.Builder\nopen Microsoft.Extensions.DependencyInjection\nopen Microsoft.Extensions.Hosting\nopen Microsoft.AspNetCore.Hosting\nIn the same module, we need to replace the Server's application computation expression with some functions which set up the default host, configure the application and register services.
Remove this
let app =\napplication {\n// ...setup functions\n}\n\nrun app\nand replace it with this
let configureApp (app : IApplicationBuilder) =\napp\n.UseStaticFiles()\n.UseGiraffe webApp\n\nlet configureServices (services : IServiceCollection) =\nservices\n.AddGiraffe() |> ignore\n\n\nHost.CreateDefaultBuilder()\n.ConfigureWebHostDefaults(\nfun webHostBuilder ->\nwebHostBuilder\n.Configure(configureApp)\n.ConfigureServices(configureServices)\n.UseWebRoot(\"public\")\n|> ignore)\n.Build()\n.Run()\nIf you are using the standard SAFE template, there is nothing more you need to do, as routing is taken care of by Fable Remoting.
If however you are using the minimal template, you will need to replace the Saturn router expression with the Giraffe equivalent.
Replace this
let webApp =\nrouter {\nget Route.hello (json \"Hello from SAFE!\")\n}\nwith this
let webApp = route Route.hello >=> json \"Hello from SAFE!\"\nThe steps shown here are the minimal necessary to get a SAFE app running using Giraffe.
As with any Server setup however, there are many more optional parameters that you may wish to configure, such as caching, response compression and serialisation options as seen in the default SAFE templates amongst many others.
See the Giraffe and ASP.NET Core host builder, application builder and service collection docs for more information on this.
"},{"location":"v4-recipes/client-server/serve-a-file-from-the-backend/","title":"Serve a file from the back-end","text":"In SAFE apps, you can send a file from the server to the client as well as you can send any other type of data. However, there are a few details that make this case unique that varies on whether you use the standard or the minimal template.
"},{"location":"v4-recipes/client-server/serve-a-file-from-the-backend/#i-am-using-the-minimal-template","title":"I am using the minimal template","text":""},{"location":"v4-recipes/client-server/serve-a-file-from-the-backend/#1-add-the-route","title":"1. Add the route","text":"To begin, find the Route module in Shared.fs and create the following route inside it.
let file = \"api/file\"\nFind the webApp in Server.fs. Inside its router expression, add the following get expression.
open FSharp.Control.Tasks.V2\n\nlet webApp =\nrouter {\n//...other handlers\nget Route.file (fun next ctx ->\ntask {\nlet byteArray = System.IO.File.ReadAllBytes(\"~/files/file.xlsx\")\nctx.SetContentType \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\"\nctx.SetHttpHeader \"Content-Disposition\" \"attachment;\"\nreturn! ctx.WriteBytesAsync (byteArray)\n})\n}\nWhat we're doing here is to read a file from the local drive, but where the file is retrieved from is irrelevant. Then, using ctx, which is of type HttpContext, we let the browser know about the type of data this handler is returning. The last line (again, using ctx) writes a byte array to the body of the HTTP response as well as handling some details that goes alongside this process.
Although not perfect, the best solution for handling the file download is creating an invisible download link, clicking it, and then removing it completely. The following block of code is all we need for this. Add it to the Index.fs file, somewhere above the view function.
open Fable.Core.JsInterop\nopen Shared\n\nlet downloadFile () =\nlet anchor = Browser.Dom.document.createElement \"a\"\nanchor?style <- \"display: none\"\nanchor?href <- Route.file\nanchor?download <- \"MyFile.xlsx\"\nanchor.click()\nanchor.remove()\nYou could also pass in the name of the file or the route to be hit as a parameter.
Now, you can call the downloadFile function to initiate the file download.
Since the standard template uses Fable.Remoting, we need to edit our API definition first. Find your API type definition in Shared.fs. It's usually the last block of code. The one you see here is named IFileAPI, but the one you see in Shared.fs will be named differently. Edit this definition to have the download member you see below.
type IFileAPI =\n{ //...other routes \ndownload : unit -> Async<byte[]> }\nOpen the Server.fs file and find the API that implements the definition we've just edited. It should now have an error since we're not matching the definition at the moment. Add the following route to it
let download () = async {\nlet byteArray = System.IO.File.ReadAllBytes(\"/fileFolder/file.xlsx\")\nreturn byteArray\n}\nMake sure to replace \"/fileFolder/file.xlsx\" with the path to your file
"},{"location":"v4-recipes/client-server/serve-a-file-from-the-backend/#3-the-download-function_1","title":"3. The download function","text":"Paste the following code into Index.fs, somewhere above the view function.
let downloadFile () =\nasync {\nlet! downloadedFile = todosApi.download ()\ndownloadedFile.SaveFileAs(\"downloaded-file.xlsx\")\n}\nThe SaveFileAs funcion detects the mime-type/content-type automatically based on the file extension of the file input
Since the downloadFile function is asynchronous, we can't just call it anywhere in our view. The way we're going to deal with this is to create a Msg case and handle it in our update funciton.
type Msg =\n//...other cases\n| DownloadFile\n| FileDownloaded of unit\nlet update (msg: Msg) (model: Model): Model * Cmd<Msg> =\nmatch msg with\n//...other cases\n| DownloadFile -> model, Cmd.OfAsync.perform downloadFile () FileDownloaded\n| FileDownloaded () -> model, Cmd.none // You can do something else here\nHtml.button [\nprop.onClick (fun _ -> dispatch DownloadFile)\nprop.text \"Click to download\" ]\nHaving added this last snippet of code into the view function, you will be able to download the file by clicking the button that will now be displayed in your UI. For more information visit the Fable.Remoting documentation
SAFE Stack makes it easy to catch and handle exceptions raised by the server on the client. Though the way we make a call to the server from the client is different between the standard and the minimal template, the way we handle server errors on the client is the same in principle.
"},{"location":"v4-recipes/client-server/server-errors-on-client/#1-update-the-model","title":"1. Update the Model","text":"Update the model to store the error details that we receive from the server. Find the Model type in src/Client/Index.fs and add it the following Errors field:
type Model =\n{ ... // the rest of the fields\nErrors: string list }\nNow, bind an empty list to the field record inside the init function:
let model =\n{ ... // the rest of the fields\nErrors = [] }\nWe now add a new message to handle errors that we get back from the server after making a request. Add the following case to the Msg type:
type Msg =\n| ... // other message cases\n| GotError of exn\nIn this simple example, we will simply capture the Message of the exception. Add the following line to the end of the pattern match inside the update function:
| GotError ex ->\n{ model with Errors = ex.Message :: model.Errors }, Cmd.none\nThe following steps will vary depending on whether you\u2019re using the standard template or the minimal one.
"},{"location":"v4-recipes/client-server/server-errors-on-client/#4-connect-server-errors-to-elmish","title":"4. Connect Server Errors to Elmish","text":"We now have to connect up the server response to the new message we created. Elmish has support for this through the either Cmd functions (instead of the perform functions). Make the following changes to your server call:
let cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos\n\u2026and replace it with the following:
let cmd = Cmd.OfAsync.either todosApi.getTodos () GotTodos GotError\nlet cmd = Cmd.OfPromise.perform getHello () GotHello\n\u2026and replace it with the following:
let cmd = Cmd.OfPromise.either getHello () GotHello GotError\nNow, if you get an exception from the Server, its message will be added to the Errors field of the Model type. Instead of throwing the error, you can now display a meaningful text to the user like so:
[ for msg in errorMessages do\nHtml.p msg ]\nSAFE Stack makes it really simple and easy to share code between the client and the server, since both of them are written in F#. The client side is transpiled into JavaScript via webpack, whilst the server side is compiled down to .NET CIL. Serialization between both happens in the background, so you don't have to worry about it.
"},{"location":"v4-recipes/client-server/share-code/#types","title":"Types","text":"Let\u2019s say the you have the following type in src/Server/Server.fs:
type Customer =\n{ Id : Guid\nName : string\nEmail : string\nPhoneNumber : string }\nAnd you have the following function that is used to validate this Customer type in src/Client/Index.fs:
let customerIsValid customer =\n(Guid.Empty = customer.Id\n|| String.IsNullOrEmpty customer.Name\n|| String.IsNullOrEmpty customer.Email\n|| String.IsNullOrEmpty customer.PhoneNumber)\n|> not\nIf at any point you realise you need to use both the Customer type and the customerIsValid function both in the Client and the Server, all you need to do is to move both of them to Shared project. You can either put them in the Shared.fs file, or create your own file in the Shared project (eg. Customer.fs). After this, you will be able to use both the Customer type and the customerIsValid function in both the Client and the Server.
SAFE comes out of the box with [Fable.Remoting] or [Thoth] for serialization. These will handle transport of data seamlessly for you.
"},{"location":"v4-recipes/client-server/share-code/#considerations","title":"Considerations","text":"Be careful not to place code in Shared.fs that depends on a Client or Server-specific dependency. If your code depends on Fable for example, in most cases it will not be suitable to place it in Shared, since it can only be used in Client. Similarly, if your types rely on .NET specific types in e.g. the framework class library (FCL), beware. Fable has built-in mappings for popular .NET types e.g. System.DateTime and System.Math, but you will have to write your own mappers otherwise.
Fable makes it quick and easy to upload files from the client. Both the standard and the minimal template comes with Fable support by default.
"},{"location":"v4-recipes/client-server/upload-file-from-client/#1-create-a-file","title":"1. Create a File","text":"Create a file in the client project named FileUpload.fs somewhere before the Index.fs file and insert the following:
module FileUpload\n\nopen Fable.React\nopen Fable.React.Props\nopen Fable.FontAwesome\nopen Fable.Core\nopen Fable.Core.JsInterop\nThen, add the following. The reader.onload block will be executed once we select and confirm a file to be uploaded. Read the FileReader docs to find out more.
let handleFileEvent onLoad (fileEvent:Browser.Types.Event) =\nlet files:Browser.Types.FileList = !!fileEvent.target?files\nif files.length > 0 then\nlet reader = Browser.Dom.FileReader.Create()\nreader.onload <- (fun _ -> reader.result |> unbox |> onLoad)\nreader.readAsArrayBuffer(files.[0])\nThis step varies depending on whether you're using the standard or the minimal template. Apply only the instructions under the appropriate heading.
"},{"location":"v4-recipes/client-server/upload-file-from-client/#im-using-the-standard-template","title":"I'm using the standard template","text":"Insert the following block of code at the end of FileUpload.fs. This function will create a UI element to be used to upload files. Click here to find out more about Bulma's file input component.
open Feliz.Bulma\n\nlet createFileUpload onLoad =\nBulma.file [\nBulma.fileLabel.label [\nBulma.fileInput [\nprop.onChange (handleFileEvent onLoad)\n]\nBulma.fileCta [\nBulma.fileLabel.label \"Choose a file...\"\n]\n]\n]\nInsert the following block of code at the end of FileUpload.fs. This function will create a UI element to be used to upload files.
let createFileUpload onLoad =\nlet input = document.createElement \"INPUT\"\ninput.onchange <- (handleFileEvent onLoad)\nHaving followed all these steps, you can now use the createFileUpload function in Index.fs to create the UI element for uploading files. One thing to note is that HandleFile is a case of the discriminated union type Msg that's in Index.fs. You can use this message case to send the file from the client to the server.
FileUpload.createFileUpload (HandleFile >> dispatch)\nIn order to debug Server code from Visual Studio, we need set the correct URLs in the project's debug properties.
"},{"location":"v4-recipes/developing-and-testing/debug-safe-app/#debugging-the-server","title":"Debugging the Server","text":""},{"location":"v4-recipes/developing-and-testing/debug-safe-app/#1-configure-launch-settings","title":"1. Configure launch settings","text":"You can do this through the Server project's Properties/Debug editor or by editing the launchSettings.json file which is in the properties folder.
After selecting the debug profile that you wish to edit (IIS Express or Server), you will need to set the App URL field to http://localhost:5000 and Launch browser field to http://localhost:8080. The process is very similar for VS Mac.
Once this is done, you can expect your launchSettings.json file to look something like this:
{\n\"iisSettings\": {\n\"windowsAuthentication\": false,\n\"anonymousAuthentication\": true,\n\"iisExpress\": {\n\"applicationUrl\": \"http://localhost:5000/\",\n\"sslPort\": 44330\n}\n},\n\"profiles\": {\n\"IIS Express\": {\n\"commandName\": \"IISExpress\",\n\"launchBrowser\": true,\n\"launchUrl\": \"http://localhost:8080/\",\n\"environmentVariables\": {\n\"ASPNETCORE_ENVIRONMENT\": \"Development\"\n}\n},\n\"Server\": {\n\"commandName\": \"Project\",\n\"launchBrowser\": true,\n\"launchUrl\": \"http://localhost:8080\",\n\"environmentVariables\": {\n\"ASPNETCORE_ENVIRONMENT\": \"Development\"\n},\n\"applicationUrl\": \"http://localhost:5000\"\n}\n}\n}\nSince you will be running the server directly through Visual Studio, you cannot use a FAKE script to start the application, so launch the client directly using e.g. npm run start.
Set the server as your Startup project, either using the drop-down menu at the top of the IDE or by right clicking on the project itself and selecting Set as Startup Project. Select the profile that you set up earlier and wish to launch from the drop-down at the top of the IDE. Either press the Play button at the top of the IDE or hit F5 on your keyboard to start the Server debugging and launch a browser pointing at the website.
"},{"location":"v4-recipes/developing-and-testing/debug-safe-app/#debugging-the-client","title":"Debugging the Client","text":"Although we write our client-side code using F#, it is being converted into JavaScript at runtime by Fable and executed in the browser. However, we can still debug it via the magic of source mapping. If you are using Visual Studio, you cannot directly connect to the browser debugger. You can, however, debug your client F# code using the browser's development tools.
"},{"location":"v4-recipes/developing-and-testing/debug-safe-app/#1-set-breakpoints-in-client-code","title":"1. Set breakpoints in Client code","text":"The exact instructions will depend on your browser, but essentially it simply involves:
VS Code allows \"full stack\" debugging i.e. both the client and server. Prerequisites that you should install:
"},{"location":"v4-recipes/developing-and-testing/debug-safe-app/#0-install-prerequisites","title":"0. Install Prerequisites","text":"Open the Command Palette using Ctrl+Shift+P and run Debug: Add Configuration.... This will ask you to choose a debugger; select Ionide LaunchSettings.
This will create a launch.json file in the root of your solution and also open it in the editor.
The only change required is to point it at the Server application, by replacing the program line with this:
\"program\": \"${workspaceFolder}/src/Server/bin/Debug/net6.0/Server.dll\",\nTasks: Configure Task.Create tasks.json file from template. This will show you a list of pre-configured templates..NET Core.\"options\": {\"cwd\": \"src/Server\"}, as shown below:{\n// See https://go.microsoft.com/fwlink/?LinkId=733558\n// for the documentation about the tasks.json format\n\"version\": \"2.0.0\",\n\"tasks\": [\n{\n\"label\": \"build\",\n\"command\": \"dotnet\",\n\"type\": \"shell\",\n\"options\": {\"cwd\": \"src/Server\"}, \"args\": [\n\"build\",\n\"debug-pt3.sln\",\n// Ask dotnet build to generate full paths for file names.\n\"/property:GenerateFullPaths=true\",\n// Do not generate summary otherwise it leads to duplicate errors in Problems panel\n\"/consoleloggerparameters:NoSummary\"\n],\n\"group\": \"build\",\n\"presentation\": {\n\"reveal\": \"silent\"\n},\n\"problemMatcher\": \"$msCompile\"\n}\n]\n}\nEither hit F5 or open the Debugging pane and press the Play button to build and launch the Server with the debugger attached. Observe that the Debug Console panel will show output from the server. The server is now running and you can set breakpoints and view the callstack etc.
"},{"location":"v4-recipes/developing-and-testing/debug-safe-app/#5-debug-the-client","title":"5. Debug the Client","text":"dotnet fable watch -o output -s --run npm run start from <repo root>/src/Client/.Debug: Open Link.http://localhost:8080/. This will launch a browser which is pointed at the URL and connect the debugger to it..fs.js files within VS Code.If you find that your breakpoints aren't being hit, try stopping the Client, disconnecting the debugger and re-launching them both.
To find out more about the VS Code debugger, see here.
"},{"location":"v4-recipes/developing-and-testing/testing-the-client/","title":"How do I test the client?","text":"Testing on the client is a little different than on the server.
This is because the code which is ultimately being executed in the browser is JavaScript, translated from F# by Fable, and so it must be tested in a JavaScript environment.
Furthermore, code that is shared between the Client and Server must be tested in both a dotnet environment and a JavaScript environment.
The SAFE template uses a library called Fable.Mocha which allows us to run the same tests in both environments. It mirrors the Expecto API and works in much the same way.
"},{"location":"v4-recipes/developing-and-testing/testing-the-client/#im-using-the-standard-template","title":"I'm using the standard template","text":"If you are using the standard template then there is nothing more you need to do in order to start testing your Client.
In the tests/Client folder, there is a project named Client.Tests with a single script demonstrating how to use Mocha to test the TODO sample.
Note the compiler directive here which makes sure that the Shared tests are only included when executing in a JavaScript (Fable) context. They are covered by Expecto under dotnet as you can see in Server.Tests.fs.
"},{"location":"v4-recipes/developing-and-testing/testing-the-client/#1-launch-the-test-server","title":"1. Launch the test server","text":"In order to run the tests, instead of starting your application using
dotnet run\ndotnet run Runtests\nOnce the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
This command builds and runs the Server test project too. If you want to run the Client tests alone, you can simply launch the test server using npm run test:live, which executes a command stored in package.json.
If you are using the minimal template, you will need to first configure a test project as none are included.
"},{"location":"v4-recipes/developing-and-testing/testing-the-client/#1-add-a-test-project","title":"1. Add a test project","text":"Create a .Net library called Client.Tests in the tests/Client subdirectory using the following commands:
dotnet new ClassLib -lang F# -n Client.Tests -o tests/Client\ndotnet sln add tests/Client\nReference the Client project from the Client.Tests project:
dotnet add tests/Client reference src/Client\nRun the following command:
dotnet add tests/Client package Fable.Mocha\nAdd this function to Client.fs in the Client project
let sayHello name = $\"Hello {name}\"\nReplace the contents of tests/Client/Library.fs with the following code:
module Tests\n\nopen Fable.Mocha\n\nlet client = testList \"Client\" [\ntestCase \"Hello received\" <| fun _ ->\nlet hello = Client.sayHello \"SAFE V3\"\n\nExpect.equal hello \"Hello SAFE V3\" \"Unexpected greeting\"\n]\n\nlet all =\ntestList \"All\"\n[\nclient\n]\n\n[<EntryPoint>]\nlet main _ = Mocha.runTests all\nAdd a file called index.html to the tests/Client folder with following contents:
<!DOCTYPE html>\n<html>\n <head>\n <title>SAFE Client Tests</title>\n </head>\n <body>\n </body>\n</html>\nAdd a file called webpack.tests.config.js to the root directory with the following contents:****
// Template for webpack.config.js in Fable projects\n// Find latest version in https://github.com/fable-compiler/webpack-config-template\n\n// In most cases, you'll only need to edit the CONFIG object (after dependencies)\n// See below if you need better fine-tuning of Webpack options\n\n// Dependencies. Also required: core-js, @babel/core,\n// @babel/preset-env, babel-loader, sass, sass-loader, css-loader, style-loader, file-loader, resolve-url-loader\nvar path = require('path');\nvar webpack = require('webpack');\nvar HtmlWebpackPlugin = require('html-webpack-plugin');\nvar CopyWebpackPlugin = require('copy-webpack-plugin');\n\nvar CONFIG = {\n// The tags to include the generated JS and CSS will be automatically injected in the HTML template\n// See https://github.com/jantimon/html-webpack-plugin\nindexHtmlTemplate: 'tests/Client/index.html',\nfsharpEntry: 'tests/Client/Library.fs.js',\noutputDir: 'tests/Client',\nassetsDir: 'tests/Client',\ndevServerPort: 8081,\n// When using webpack-dev-server, you may need to redirect some calls\n// to a external API server. See https://webpack.js.org/configuration/dev-server/#devserver-proxy\ndevServerProxy: undefined,\nbabel: undefined\n}\n\n// If we're running the webpack-dev-server, assume we're in development mode\nvar isProduction = !process.argv.find(v => v.indexOf('webpack-dev-server') !== -1);\nvar environment = isProduction ? 'production' : 'development';\nprocess.env.NODE_ENV = environment;\nconsole.log('Bundling for ' + environment + '...');\n\n// The HtmlWebpackPlugin allows us to use a template for the index.html page\n// and automatically injects <script> or <link> tags for generated bundles.\nvar commonPlugins = [\nnew HtmlWebpackPlugin({\nfilename: 'index.html',\ntemplate: resolve(CONFIG.indexHtmlTemplate)\n})\n];\n\nmodule.exports = {\n// In development, split the JavaScript and CSS files in order to\n// have a faster HMR support. In production bundle styles together\n// with the code because the MiniCssExtractPlugin will extract the\n// CSS in a separate files.\nentry: {\napp: resolve(CONFIG.fsharpEntry)\n},\n// Add a hash to the output file name in production\n// to prevent browser caching if code changes\noutput: {\npath: resolve(CONFIG.outputDir),\nfilename: isProduction ? '[name].[hash].js' : '[name].js'\n},\nmode: isProduction ? 'production' : 'development',\ndevtool: isProduction ? 'source-map' : 'eval-source-map',\noptimization: {\nsplitChunks: {\nchunks: 'all'\n},\n},\n// Besides the HtmlPlugin, we use the following plugins:\n// PRODUCTION\n// - MiniCssExtractPlugin: Extracts CSS from bundle to a different file\n// To minify CSS, see https://github.com/webpack-contrib/mini-css-extract-plugin#minimizing-for-production\n// - CopyWebpackPlugin: Copies static assets to output directory\n// DEVELOPMENT\n// - HotModuleReplacementPlugin: Enables hot reloading when code changes without refreshing\nplugins: isProduction ?\ncommonPlugins.concat([\nnew CopyWebpackPlugin({ patterns: [{ from: resolve(CONFIG.assetsDir) }] }),\n])\n: commonPlugins.concat([\nnew webpack.HotModuleReplacementPlugin(),\n]),\nresolve: {\n// See https://github.com/fable-compiler/Fable/issues/1490\nsymlinks: false\n},\n// Configuration for webpack-dev-server\ndevServer: {\npublicPath: '/',\ncontentBase: resolve(CONFIG.assetsDir),\nhost: '0.0.0.0',\nport: CONFIG.devServerPort,\nproxy: CONFIG.devServerProxy,\nhot: true,\ninline: true\n},\nmodule: {\nrules: [\n\n]\n}\n};\n\nfunction resolve(filePath) {\nreturn path.isAbsolute(filePath) ? filePath : path.join(__dirname, filePath);\n}\nnpm install\ndotnet fable watch src/Client --run webpack-dev-server --config webpack.tests.config\nOnce the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
Testing your Server code in a SAFE app is just the same as in any other dotnet app, and you can use the same tools and frameworks that you are familiar with. These include all of the usual suspects such as NUnit, XUnit, FSUnit, Expecto, FSCheck, AutoFixture etc.
In this guide we will look at using Expecto, as this is included with the standard SAFE template.
"},{"location":"v4-recipes/developing-and-testing/testing-the-server/#im-using-the-standard-template","title":"I'm using the standard template","text":""},{"location":"v4-recipes/developing-and-testing/testing-the-server/#using-the-expecto-runner","title":"Using the Expecto runner","text":"If you are using the standard template, then there is nothing more you need to do in order to start testing your Server code.
In the tests/Server folder, there is a project named Server.Tests with a single script demonstrating how to use Expecto to test the TODO sample.
In order to run the tests, instead of starting your application using
dotnet run\nyou should instead use
dotnet run RunTests\nThis method builds and runs the Client test project too, which can be slow. If you want to run the Server tests alone, you can simply navigate to the tests/Server directory and run the project using dotnet run.
If you would like to use dotnet tests from the command line or the test runner that comes with Visual Studio, there are a couple of extra steps to follow.
"},{"location":"v4-recipes/developing-and-testing/testing-the-server/#1-install-the-test-adapters","title":"1. Install the Test Adapters","text":"Run the following commands at the root of your solution:
dotnet paket add Microsoft.NET.Test.Sdk -p Server.Tests\ndotnet paket add YoloDev.Expecto.TestSdk -p Server.Tests\nOpen your ServerTests.fsproj file and add the following element:
<PropertyGroup>\n<GenerateProgramFile>false</GenerateProgramFile>\n</PropertyGroup>\nTo allow your tests to be discovered, you will need to decorate them with a [<Tests>] attribute.
The provided test would look like this:
[<Tests>]\nlet server = testList \"Server\" [\ntestCase \"Adding valid Todo\" <| fun _ ->\nlet storage = Storage()\nlet validTodo = Todo.create \"TODO\"\nlet expectedResult = Ok ()\n\nlet result = storage.AddTodo validTodo\n\nExpect.equal result expectedResult \"Result should be ok\"\nExpect.contains (storage.GetTodos()) validTodo \"Storage should contain new todo\"\n]\nThere are now two ways to run these tests.
From the command line, you can just run
dotnet test tests/Server\nAlternatively, if you are using Visual Studio or VS Mac you can make use of the built-in test explorers.
"},{"location":"v4-recipes/developing-and-testing/testing-the-server/#im-using-the-minimal-template","title":"I'm using the minimal template","text":"If you are using the minimal template, you will need to first configure a test project as none are included.
"},{"location":"v4-recipes/developing-and-testing/testing-the-server/#1-add-a-test-project","title":"1. Add a test project","text":"Create a .Net 5 console project called Server.Tests in the tests/Server folder.
dotnet new console -lang F# -n Server.Tests -o tests/Server\ndotnet sln add tests/Server\nReference the Server project from the Server.Tests project:
dotnet add tests/Server reference src/Server\nRun the following command:
dotnet add tests/Server package Expecto\nUpdate the Server.fs file in the Server project to extract the message logic from the router like so:
let getMessage () = \"Hello from SAFE!\"\n\nlet webApp =\nrouter {\nget Route.hello (getMessage () |> json )\n}\nReplace the contents of tests/Server/Program.fs with the following:
open Expecto\n\nlet server = testList \"Server\" [\ntestCase \"Message returned correctly\" <| fun _ ->\nlet expectedResult = \"Hello from SAFE!\" let result = Server.getMessage()\nExpect.equal result expectedResult \"Result should be ok\"\n]\n\n[<EntryPoint>]\nlet main _ = runTests defaultConfig server\ndotnet run -p tests/Server\nThis will print out the results in the console window
"},{"location":"v4-recipes/developing-and-testing/testing-the-server/#7-using-dotnet-test-or-the-visual-studio-test-explorer","title":"7. Using dotnet test or the Visual Studio Test Explorer","text":"Add the libraries Microsoft.NET.Test.Sdk and YoloDev.Expecto.TestSdk to your Test project, using NuGet.
The way you do this will depend on whether you are using NuGet directly or via Paket. See this recipe for more details.
You can now add [<Test>] attributes to your tests so that they can be discovered, and then run them using the dotnet tooling in the same way as explained earlier for the standard template.
Hot reload is a great time-saving technology and something that every developer will find useful. Whenever changes are made to code, they are immediately reflected in the running application without needing to manually redeploy. The specific way that this is achieved depends on the nature of the application.
In a SAFE app we have two distinct components, the Client and the Server. Whether you are using the minimal or standard SAFE template, there is nothing more you need to do in order to get started with hot reload.
"},{"location":"v4-recipes/developing-and-testing/using-hot-reload/#client-reloading","title":"Client reloading","text":"If you deploy your application and then make a change in the Client, after a moment it will be reflected in the browser without a full re-deployment. Importantly, the state of your application will be retained across the deployment, so you can continue where you left off. This is achieved using the hot module replacement functionality provided by webpack.
"},{"location":"v4-recipes/developing-and-testing/using-hot-reload/#to-add-hot-module-replacement-manually","title":"To Add Hot Module Replacement manually","text":"If your client project has been hand-rolled, or you simply wish to see how to add it from scratch:
"},{"location":"v4-recipes/developing-and-testing/using-hot-reload/#1-configure-the-webpack-dev-server","title":"1. Configure the Webpack Dev Server","text":"Add the following to the devServer object of your webpack config:
var devServer = {\n// other fields elided...\nhot: true,\nproxy : {\n// Redirect websocket requests that start with /socket/ to the server on the port 5000\n// This is used by Hot Module Replacement\n'/socket/**': {\ntarget: 'http://localhost:5000',\nws: true\n}\n}\n}\nImport and create an instance HotModuleReplacementPlugin at the top of the webpack configuration file, and ensure that the plugin is added to module.exports:
// Import and create the HMR plugin\nvar { HotModuleReplacementPlugin } = require('webpack');\nvar hmrPlugin = new HotModuleReplacementPlugin();\n\n// other configuration...\n\nmodule.exports = {\n// Add the HMR plugin to the module\nplugins : [ /* other plugins... */, hmrPlugin ]\n}\nFirst, add the Fable.Elmish.Hmr package to the client:
dotnet add package Fable.Elmish.Hmr\nThen, open the Elmish.HMR namespace in your app:
#if DEBUG\nopen Elmish.Debug\nopen Elmish.HMR\n#endif\nBest practice is to include hot module reloading in debug (not production) mode only, since production applications will not benefit from HMR and will only result in an increased bundle size.
"},{"location":"v4-recipes/developing-and-testing/using-hot-reload/#server-reloading","title":"Server reloading","text":"Server reloading isn't quite as fully automated.
If you make a change in the Server code and save your work, the project will automatically rebuild and launch itself. Once this is complete however you will need to refresh your browser to see any visual changes.
If you are using the minimal template, you need to make sure you launch the Server using dotnet watch run rather than just dotnet run. The standard template takes care of this step for you using its FAKE build script. If you have already restored your NuGet dependencies, you can get a little boost in restart speed by using dotnet watch run --no-restore as well.
Sometimes you need to use a JS library directly, instead of using it through a wrapper library that makes it easy to use from F# code. In this case you need to import a module from the library. Here are the most common import patterns used in JS.
"},{"location":"v4-recipes/javascript/import-js-module/#default-export","title":"Default export","text":""},{"location":"v4-recipes/javascript/import-js-module/#setup","title":"Setup","text":"In most cases components use the default export syntax which is when the the component being exported from the module becomes available. For example, if the module being imported below looked something like:
// module-name\nconst foo = () => \"hello\"\n\nexport default foo\nfoo. import foo from 'module-name' // JS\nlet foo = importDefault \"module-name\" // F#\nTo ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element.
Browser.Dom.console.log(\"imported value\", foo)\nAn example of this in use is how React is imported
import React from \"react\"\n\n// Although in the newer versions of React this is uneeded\nIn some cases components can use the named export syntax. In the below case \"module-name\" has an object/function/class that is called bar. By referncing it below it is brought into the current scope. For example, if the module below contained something like:
export const bar (x,y) => x + y import { bar } from \"module-name\" // JS\nlet bar = import \"bar\" \"module-name\" // F#\nTo ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element.
Browser.Dom.console.log(\"imported value\", bar)\nAn example of this is how React hooks are imported
import { useState } from \"react\"\nIn rare cases you may have to import an entire module's contents and provide an alias in the below case we named it myModule. You can now use dot notation to access anything that is exported from module-name. For example, if the module being imported below includes an export to a function doAllTheAmazingThings() you could access it like:
myModule.doAllTheAmazingThings()\nimport * as myModule from 'module-name' // JS\nlet myModule = importAll \"module-name\" // F#\nTo ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element.
Browser.Dom.console.log(\"imported value\", myModule)\nAn example of this is another way to import React
import * as React from \"react\"\n\n// Uncommon since importDefault is the standard\nSee the Fable docs for more ways to import modules and use JavaScript from Fable.
"},{"location":"v4-recipes/javascript/third-party-react-package/","title":"Add Support for a Third Party React Library","text":"To use a third-party React library in a SAFE application, you need to write an F# wrapper around it. There are two ways for doing this - using Fable.React or using Feliz.
"},{"location":"v4-recipes/javascript/third-party-react-package/#prerequisites","title":"Prerequisites","text":"This recipe uses the react-d3-speedometer NPM package for demonstration purposes. Add it to your Client before continuing.
"},{"location":"v4-recipes/javascript/third-party-react-package/#fablereact-setup","title":"Fable.React - Setup","text":""},{"location":"v4-recipes/javascript/third-party-react-package/#1-create-a-new-file","title":"1. Create a new file","text":"Create an empty file named ReactSpeedometer.fs in the Client project above Index.fs and insert the following statements at the beginning of the file.
module ReactSpeedometer\n\nopen Fable.Core\nopen Fable.Core.JsInterop\nopen Fable.React\nProp represents the props of the React component. In this recipe, we're using the props listed here for react-d3-speedometer. We model them in Fable.React using a discriminated union.
type Prop =\n| Value of int\n| MinValue of int\n| MaxValue of int | StartColor of string\nOne difference to note is that we use PascalCase rather than camelCase.
Note that we can model any props here, both simple values and \"event handler\"-style ones.
"},{"location":"v4-recipes/javascript/third-party-react-package/#3-write-the-component","title":"3. Write the Component","text":"Add the following function to the file. Note that the last argument passed into the ofImport function is a list of ReactElements to be used as children of the react component. In this case, we are passing an empty list since the component doesn't have children.
let reactSpeedometer (props : Prop list) : ReactElement =\nlet propsObject = keyValueList CaseRules.LowerFirst props // converts Props to JS object\nofImport \"default\" \"react-d3-speedometer\" propsObject [] // import the default function/object from react-d3-speedometer\nWith all these in place, you can use the React element in your client like so:
open ReactSpeedometer\n\nreactSpeedometer [\nProp.Value 10 // Since Value is already decalred in HTMLAttr you can use Prop.Value to tell the F# compiler its of type Prop and not HTMLAttr\nMaxValue 100\nMinValue 0 StartColor \"red\"\n]\nIf you don't already have Feliz installed, add it to your client. In the Client projects Index.fs add the following snippets
open Fable.Core.JsInterop\nWithin the view function
Feliz.Interop.reactApi.createElement (importDefault \"react-d3-speedometer\", createObj [\n\"minValue\" ==> 0\n\"maxValue\" ==> 100\n\"value\" ==> 10\n])\ncreateElement from Feliz.ReactApi.IReactApi takes the component you're wrapping react-d3-speedometer, the props that component takes and creates a ReactComponent we can use in F#.importDefault from Fable.Core.JsInterop is giving us access to the component and is equivalent to import ReactSpeedometer from \"react-d3-speedometer\"\nimportDefault is the documentation for the component uses a default export \"ReactSpeedometer\". Please find a list of common import statetments at the end of this recipeAs a quick check to ensure that the library is being imported and we have no typos you can console.log the following at the top within the view function
Browser.Dom.console.log(\"REACT-D3-IMPORT\", importDefault \"react-d3-speedometer\")\ncreateObj from Fable.Core.JsInterop takes a sequence of string * obj which is a prop name and value for the component, you can find the full prop list for react-d3-speedometer here.==> (short hand for prop.custom) to transform the sequence into a JavaScript object createObj [\n\"minValue\" ==> 0\n\"maxValue\" ==> 10\n]\n{ minValue: 0, maxValue: 10 }\nThat's the bare minimum needed to get going!
"},{"location":"v4-recipes/javascript/third-party-react-package/#next-steps-for-feliz","title":"Next steps for Feliz","text":"Once your component is working you may want to extract out the logic so that it can be used in multiple pages of your app. For a full detailed tutorial head over to this blog post!
"},{"location":"v4-recipes/package-management/add-npm-package-to-client/","title":"How do I add an NPM package to the Client?","text":"When you want to call a JavaScript library from your Client, it is easy to import and reference it using NPM.
Run the following command:
npm install name-of-package\nThis will download the package into the solution's node_modules folder.
You will also see a reference to the package in the Client's package.json file:
\"dependencies\": {\n\"name-of-package\": \"^1.0.0\"\n}\nAdding packages to the Client project is a very similar process to the Server, with a few key differences:
Any references to the Server directory should be Client
Client code written in F# is converted into JavaScript using Fable. Because of this, we must be careful to only reference libraries which are Fable compatible.
If the NuGet package uses any JS libraries you must install them. For simplicity, use Femto to sync - if the NuGet package is compatible - or install via NPM manually, if not.
There are lots of great libraries available to choose from.
"},{"location":"v4-recipes/package-management/add-nuget-package-to-server/","title":"How do I add a NuGet package to the Server?","text":"You can add NuGet packages to the server to give it more capabilities. You can download a wide variety of packages from the official NuGet site.
In this example we will add the FsToolkit ErrorHandling package package.
"},{"location":"v4-recipes/package-management/add-nuget-package-to-server/#im-using-the-standard-template-paket","title":"I'm using the standard template (Paket)","text":""},{"location":"v4-recipes/package-management/add-nuget-package-to-server/#1-add-the-package","title":"1. Add the package","text":"Navigate to the root directory of your solution and run:
dotnet paket add FsToolkit.ErrorHandling -p Server\nThis will add an entry to both the solution paket.dependencies file and the Server project's paket.reference file, as well as update the lock file with the updated dependency graph.
Find information on how you can convert your project from NuGet to Paket here.
For a detailed explanation of package management using Paket, visit the official docs.
"},{"location":"v4-recipes/package-management/add-nuget-package-to-server/#im-using-the-minimal-template-nuget","title":"I'm using the minimal template (NuGet)","text":""},{"location":"v4-recipes/package-management/add-nuget-package-to-server/#1-navigate-to-the-server-project-directory","title":"1. Navigate to the Server project directory","text":""},{"location":"v4-recipes/package-management/add-nuget-package-to-server/#2-add-the-package","title":"2. Add the package","text":"Run the following command:
dotnet add package FsToolkit.ErrorHandling\nOnce you have done this, you will find an element in your fsproj file which looks like this:
<ItemGroup>\n<PackageReference Include=\"FsToolkit.ErrorHandling\" Version=\"1.4.3\" />\n</ItemGroup>\nYou can also achieve the same thing using the Visual Studio Package Manager, the VS Mac Package Manager or the Package Manager Console.
For a detailed explanation of package management using NuGet, visit the official docs.
"},{"location":"v4-recipes/package-management/migrate-to-nuget/","title":"How do I migrate to NuGet from Paket?","text":"Note that the minimal template uses NuGet by default. This recipe only applies to the full template.
Paket is a fully featured package manager that acts as an alternative to the NuGet package manager commonly used in .NET.
It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
For most use cases, we would recommend sticking with Paket. If, however, you are in a position where you wish to remove it and revert back to the NuGet package manager, you can easily do so with the following steps.
"},{"location":"v4-recipes/package-management/migrate-to-nuget/#1-remove-paket-targets-import-from-fsproj-files","title":"1. Remove Paket targets import from .fsproj files","text":"In every project's .fsproj file you will find the following line. Remove it and save.
<Import Project=\"..\\..\\.paket\\Paket.Restore.targets\" />\nYou will find this file at the root of your solution. Remove it from your solution if included and then delete it.
"},{"location":"v4-recipes/package-management/migrate-to-nuget/#3-add-project-dependencies-via-nuget","title":"3. Add project dependencies via NuGet","text":"Each project directory will contain a paket.references file. This lists all the NuGet packages that the project requires.
Inside a new ItemGroup in the project's .fsproj file you will need to add an entry for each of these packages.
<ItemGroup>\n<PackageReference Include=\"Azure.Core\" Version=\"1.24\" />\n<PackageReference Include=\"AnotherPackage\" Version=\"2.0.1\" />\n<!--...add entry for each package in the references file...-->\n</ItemGroup>\nYou can find the version of each package in the paket.lock file at the root of the solution. The version number is contained in brackets next to the name of the package at the first level of indentation. For example, in this case Azure.Core is version 1.24:
Azure.Core (1.24)\n Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)\n System.Diagnostics.DiagnosticSource (>= 4.6)\n System.Memory.Data (>= 1.0.2)\n System.Numerics.Vectors (>= 4.5)\n System.Text.Encodings.Web (>= 4.7.2)\n System.Text.Json (>= 4.7.2)\n System.Threading.Tasks.Extensions (>= 4.5.4)\nOnce you have added all of your dependencies to the relevant .fsproj files, you can remove the folowing files and folders from your solution.
Files: * paket.lock * paket.dependencies * all of the paket.references files
Folders: * .paket * paket-files
If you open .config/dotnet-tools.json you will find an entry for paket. Remove it.
Alternatively, run
dotnet tool uninstall paket\nPaket is a fully featured package manager that acts as an alternative to the NuGet package manager.
It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
Note that the standard template uses Paket by default. This recipe only applies to the minimal template.
"},{"location":"v4-recipes/package-management/migrate-to-paket/#1-install-and-restore-paket","title":"1. Install and restore Paket","text":"dotnet tool install paket\ndotnet tool restore\nRun this command to move existing NuGet references to Paket from your packages.config or .fsproj file:
dotnet paket convert-from-nuget\nThis will add three files to your solution, all of which should be committed to source control:
For a more detailed explanation of this process see the official migration guide.
In the case where you have added a NuGet project to a solution which is already using paket, run this command with the option --force.
If you are working in Visual Studio and wish to see your Paket files in the Solution Explorer, you will need to add both the paket.lock and any paket.references files created in your project directories during the last step to your solution.
"},{"location":"v4-recipes/package-management/sync-nuget-and-npm-packages/","title":"How do I ensure NPM and NuGet packages stay in sync?","text":"SAFE Stack uses Fable bindings, which are NuGet packages that provide idiomatic and type-safe wrappers around native JavaScript APIs. These bindings often rely on third-party JavaScript libraries distributed via the NPM registry. This leads to the problem of keeping both the NPM package in sync with its corresponding NuGet F# wrapper. Femto is a dotnet CLI tool that solves this issue.
For in-depth information about Femto, see Introducing Femto.
"},{"location":"v4-recipes/package-management/sync-nuget-and-npm-packages/#1-install-femto","title":"1. Install Femto","text":"Navigate to the root folder of the solution and execute the following command:
dotnet tool install femto\nIn the root directory, run the following:
dotnet femto ./src/Client\nalternatively, you can call femto directly from ./src/Client:
cd ./src/Client\ndotnet femto\nThis will give you a report of discrepancies between the NuGet packages and the NPM packages for the project, as well as steps to take in order to resolve them.
"},{"location":"v4-recipes/package-management/sync-nuget-and-npm-packages/#3-resolve-dependencies","title":"3. Resolve Dependencies","text":"To sync your NPM dependencies with your NuGet dependencies, you can either manually follow the steps returned by step 2, or resolve them automatically using the following command:
dotnet femto ./src/Client --resolve\nKeeping your NPM dependencies in sync with your NuGet packages is now as easy as repeating step 3. Of course, you can instead repeat the step 2 and resolve packages manually, too.
"},{"location":"v4-recipes/storage/use-litedb/","title":"How Do I Use LiteDB?","text":"The default template uses in-memory storage. This recipe will show you how to replace the in-memory storage with LiteDB in the form of LiteDB.FSharp.
If you're using the minimal template, the first steps will show you how to add a LiteDB database; the remaining section of this recipe are designed to work off the default template's starter app.
"},{"location":"v4-recipes/storage/use-litedb/#1-add-litedbfsharp","title":"1. Add LiteDB.FSharp","text":"Add the LiteDB.FSharp NuGet package to the server project.
"},{"location":"v4-recipes/storage/use-litedb/#2-create-the-database","title":"2. Create the database","text":"Replace the use of the ResizeArray in the Storage type with a database and collection:
open LiteDB.FSharp\nopen LiteDB\n\ntype Storage () =\nlet database =\nlet mapper = FSharpBsonMapper()\nlet connStr = \"Filename=Todo.db;mode=Exclusive\"\nnew LiteDatabase (connStr, mapper)\nlet todos = database.GetCollection<Todo> \"todos\"\nLiteDb is a file-based database, and will create the file if it does not exist automatically.
This will create a database file Todo.db in the Server folder. The option mode=Exclusive is added for MacOS support (see this issue).
See here for more information on connection string arguments.
See the official docs for details on constructor arguments.
"},{"location":"v4-recipes/storage/use-litedb/#3-implement-the-rest-of-the-repository","title":"3. Implement the rest of the repository","text":"Replace the implementations of GetTodos and AddTodo as follows:
/// Retrieves all todo items.\nmember _.GetTodos () =\ntodos.FindAll () |> List.ofSeq\n\n/// Tries to add a todo item to the collection.\nmember _.AddTodo (todo:Todo) =\nif Todo.isValid todo.Description then\ntodos.Insert todo |> ignore\nOk ()\nelse\nError \"Invalid todo\"\nModify the existing \"priming\" so that it first checks if there are any records in the database before inserting data:
if storage.GetTodos() |> Seq.isEmpty then\nstorage.AddTodo(Todo.create \"Create new SAFE project\") |> ignore\nstorage.AddTodo(Todo.create \"Write your app\") |> ignore\nstorage.AddTodo(Todo.create \"Ship it !!!\") |> ignore\nAdd the CLIMutable attribute to the Todo record in Shared.fs
[<CLIMutable>]\ntype Todo =\n{ Id : Guid\nDescription : string }\nThis is required to allow LiteDB to hydrate (read) data into F# records.
"},{"location":"v4-recipes/storage/use-litedb/#all-done","title":"All Done!","text":"1) In the \"Connections\" tab, click the \"New Connection\" button
2) Enter your connection details, leaving the \"Database\" dropdown set to <Default>.
USE master\nGO\nIF NOT EXISTS (\nSELECT name\nFROM sys.databases\nWHERE name = N'SafeTodo'\n)\nCREATE DATABASE [SafeTodo];\nGO\nIF SERVERPROPERTY('ProductVersion') > '12'\nALTER DATABASE [SafeTodo] SET QUERY_STORE=ON;\nGO\nNOTE: Alternatively, if you don't want to manually create the new database, you can install the \"New Database\" extension in Azure Data Studio which gives you a \"New Database\" option when right clicking the \"Databases\" folder.
"},{"location":"v4-recipes/storage/use-sqlprovider-ssdt/#create-a-todos-table","title":"Create a \"Todos\" Table","text":"CREATE TABLE [dbo].[Todos]\n(\n[Id] UNIQUEIDENTIFIER NOT NULL PRIMARY KEY,\n[Description] NVARCHAR(500) NOT NULL,\n[IsDone] BIT NOT NULL\n)\nAt this point, you should have a SAFE Stack solution and a minimal \"SafeTodo\" SQL Server database with a \"Todos\" table. Next, we will use Azure Data Studio with the \"SQL Database Projects\" extension to create a new SSDT (SQL Server Data Tools) .sqlproj that will live in our SAFE Stack .sln.
1) Install the \"SQL Database Projects\" extension.
2) Right click the SafeTodo database and choose \"Create Project From Database\" (this option is added by the \"SQL Database Projects\" extension)
3) Configure a path within your SAFE Stack solution folder and a project name and then click \"Create\". NOTE: If you choose to create an \"ssdt\" subfolder as I did, you will need to manually create this subfolder first.
4) You should now be able to view your SQL Project by clicking the \"Projects\" tab in Azure Data Studio.
5) Finally, right click the SafeTodoDB project and select \"Build\". This will create a .dacpac file which we will use in the next step.
"},{"location":"v4-recipes/storage/use-sqlprovider-ssdt/#create-a-todorepository-using-the-new-ssdt-provider-in-sqlprovider","title":"Create a TodoRepository Using the new SSDT provider in SQLProvider","text":""},{"location":"v4-recipes/storage/use-sqlprovider-ssdt/#installing-sqlprovider-from-nuget","title":"Installing SQLProvider from NuGet","text":"SQLProvider NuGet package to the Server projectSystem.Data.SqlClient NuGet package to the Server projectNext, we will wire up our type provider to generate database types based on the compiled .dacpac file.
1) In the Server project, create a new file, Database.fs. (this should be above Server.fs).
module Database\nopen FSharp.Data.Sql\n\n[<Literal>]\nlet SsdtPath = __SOURCE_DIRECTORY__ + @\"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac\"\n\n// TO RELOAD SCHEMA: 1) uncomment the line below; 2) save; 3) recomment; 4) save again and wait.\n//DB.GetDataContext().``Design Time Commands``.ClearDatabaseSchemaCache\n\ntype DB = SqlDataProvider<\nCommon.DatabaseProviderTypes.MSSQLSERVER_SSDT, SsdtPath = SsdtPath,\nUseOptionTypes = true\n>\n\nlet createContext (connectionString: string) =\nDB.GetDataContext(connectionString)\n2) Create TodoRepository.fs below Database.fs.
module TodoRepository\nopen FSharp.Data.Sql\nopen Database\nopen Shared\n\n/// Get all todos that have not been marked as \"done\". \nlet getTodos (db: DB.dataContext) = query {\nfor todo in db.Dbo.Todos do\nwhere (not todo.IsDone)\nselect { Shared.Todo.Id = todo.Id\nShared.Todo.Description = todo.Description }\n}\n|> List.executeQueryAsync\n\nlet addTodo (db: DB.dataContext) (todo: Shared.Todo) =\nasync {\nlet t = db.Dbo.Todos.Create()\nt.Id <- todo.Id\nt.Description <- todo.Description\nt.IsDone <- false\n\ndo! db.SubmitUpdatesAsync()\n}\n3) Create TodoController.fs below TodoRepository.fs.
module TodoController\nopen Database\nopen Shared\n\nlet getTodos (db: DB.dataContext) = TodoRepository.getTodos db\n\nlet addTodo (db: DB.dataContext) (todo: Todo) = async {\nif Todo.isValid todo.Description then\ndo! TodoRepository.addTodo db todo\nreturn todo\nelse return failwith \"Invalid todo\"\n}\n4) Finally, replace the stubbed todosApi implementation in Server.fs with our type provided implementation.
module Server\n\nopen Fable.Remoting.Server\nopen Fable.Remoting.Giraffe\nopen Saturn\nopen System\nopen Shared\nopen Microsoft.AspNetCore.Http\n\nlet todosApi =\nlet db = Database.createContext @\"Data Source=.\\SQLEXPRESS;Initial Catalog=SafeTodo;Integrated Security=SSPI;\"\n{ getTodos = fun () -> TodoController.getTodos db\naddTodo = TodoController.addTodo db }\n\nlet fableRemotingErrorHandler (ex: Exception) (ri: RouteInfo<HttpContext>) = printfn \"ERROR: %s\" ex.Message\nPropagate ex.Message\n\nlet webApp =\nRemoting.createApi()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.fromValue todosApi\n|> Remoting.withErrorHandler fableRemotingErrorHandler\n|> Remoting.buildHttpHandler\n\nlet app =\napplication {\nuse_router webApp\nmemory_cache\nuse_static \"public\"\nuse_gzip\n}\n\nrun app\nFrom the VS Code terminal in the SafeTodo folder, launch the app (server and client):
dotnet run
You should now be able to add todos.
"},{"location":"v4-recipes/storage/use-sqlprovider-ssdt/#deployment","title":"Deployment","text":"When creating a Release build for deployment, it is important to note that SQLProvider SSDT expects that the .dacpac file will be copied to the deployed Server project bin folder.
Here are the steps to accomplish this:
1) Modify your Server.fsproj to include the .dacpac file with \"CopyToOutputDirectory\" to ensure that the .dacpac file will always exist in the Server project bin folder.
<ItemGroup>\n <None Include=\"..\\{relative path to SSDT project}\\ssdt\\SafeTodo\\bin\\$(Configuration)\\SafeTodoDB.dacpac\" Link=\"SafeTodoDB.dacpac\">\n <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>\n </None>\n\n { other files... }\n</ItemGroup>\n2) In your Server.Database.fs file, you should also modify the SsdtPath binding so that it can build the project in either Debug or Release mode:
[<Literal>]\n#if DEBUG\nlet SsdtPath = __SOURCE_DIRECTORY__ + @\"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac\"\n#else\nlet SsdtPath = __SOURCE_DIRECTORY__ + @\"/../../ssdt/SafeTodoDB/bin/Release/SafeTodoDB.dacpac\"\n#endif\nNOTE: This assumes that your SSDT .sqlproj will be built in Release mode. (You can build it manually, or use a FAKE build script to handle this.)
"},{"location":"v4-recipes/ui/add-bulma/","title":"How do I add Bulma to a SAFE project?","text":"Bulma is a free open-source UI framework based on flex-box that helps you create modern and responsive layouts. When it comes to using Bulma as your front-end library on a SAFE Stack web application, you have two options.
By adding either of these to your SAFE project alongside the Bulma stylesheet or the Bulma NPM package, you can take full advantage of Bulma.
"},{"location":"v4-recipes/ui/add-bulma/#using-felizbulma","title":"Using Feliz.Bulma","text":"open Feliz.Bulma\n\nBulma.button.button [\nstr \"Click me!\"\n]\nopen Fulma\n\nButton.button [] [\nstr \"Click me!\"\n]\nDaisyUI is a component library for Tailwind CSS. To use the library from within F# we will use Feliz.DaisyUI (Github).
Follow the instructions for how to add Tailwind CSS to your project
Add daisyUI JS dependencies using NPM: npm i -D daisyui@latest
Add Feliz.DaisyUI .NET dependency...
dotnet paket add Feliz.DaisyUIdotnet add package Feliz.DaisyUIUpdate the tailwind.config.js file's module.exports.plugins array; add require(\"daisyui\")
module.exports = {\ncontent: [\n'./src/Client/**/*.html',\n'./src/Client/**/*.fs',\n],\ntheme: {\nextend: {},\n},\nplugins: [\nrequire(\"daisyui\"),\n],\n}\nOpen the daisyUI namespace wherever you want to use it. YourFileHere.fs
open Feliz.DaisyUI\nCongratulations, now you can use daisyUI components! Documentation can be found at https://dzoukr.github.io/Feliz.DaisyUI/
FontAwesome is the most popular icon set out there and will provide you with a handful of free icons as well as a multitude of premium icons. The standard SAFE template has out-of-the-box support for FontAwesome. You can just start using it in your Client code like so:
open Feliz\n\nHtml.i [ prop.className \"fas fa-star\" ]\nIf you\u2019re using the minimal template, there are a couple of things to do before you can start using FontAwesome. If you don't need the full features of Feliz we suggest using Fable.FontAwesome.Free.
Add Fable.FontAwesome.Free NuGet Package to the Client project.
See How do I add a NuGet package to the Client?.
"},{"location":"v4-recipes/ui/add-fontawesome/#2-the-cdn-link","title":"2. The CDN Link","text":"Open the index.html file and add the following line to the head element:
<link rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css\">\nopen Fable.FontAwesome\n\nIcon.icon [\nFa.i [ Fa.Solid.Star ] [ ]\n]\nNow you can use FontAwesome in your code
"},{"location":"v4-recipes/ui/add-routing-with-separate-models/","title":"How do I add routing to a SAFE app with separate model for every page?","text":"Written for SAFE template version 4.2.0
If your application has multiple separate components, there is no need to have one big, complex model that manages all the state for all components. In this recipe we separate the information of the todo list out of the main Model, and give the todo list application its own route. We also add a \"Page not found\" page.
Install Feliz.Router in the client project
dotnet paket add Feliz.Router -p Client -V 3.8\nFeliz.Router versions
At the time of writing, the current version of the SAFE template (4.2.0) does not work well with the latest version of Feliz.Router (4.0). To work around this, we install Feliz.Router 3.8, the latest version that works with SAFE template version 4.2.0.
If you are working with a newer version of the SAFE template, it might be worth trying to install the newest version of Feliz.Router. To see the installed version of the SAFE template, run in the command line:
dotnet new --list\nTo include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router\nMove the following functions and types to a new TodoList Module in a file TodoList.fs:
also open Shared, Fable.Remoting.Client, Elmish Feliz and Feliz.Bulma
module TodoList\n\nopen Shared\nopen Fable.Remoting.Client\nopen Elmish\nopen Feliz\nopen Feliz.Bulma\n\n\ntype Model = { Todos: Todo list; Input: string }\n\ntype Msg =\n| GotTodos of Todo list\n| SetInput of string\n| AddTodo\n| AddedTodo of Todo\n\nlet todosApi =\nRemoting.createApi ()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.buildProxy<ITodosApi>\n\nlet init () : Model * Cmd<Msg> =\nlet model = { Todos = []; Input = \"\" }\nlet cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos\n\nmodel, cmd\n\nlet update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch msg with\n| GotTodos todos -> { model with Todos = todos }, Cmd.none\n| SetInput value -> { model with Input = value }, Cmd.none\n| AddTodo ->\nlet todo = Todo.create model.Input\n\nlet cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n\n{ model with Input = \"\" }, cmd\n| AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none\n\nlet view (model: Model) (dispatch: Msg -> unit) =\nBulma.box [\nBulma.content [\nHtml.ol [\nfor todo in model.Todos do\nHtml.li [ prop.text todo.Description ]\n]\n]\nBulma.field.div [\nfield.isGrouped\nprop.children [\nBulma.control.p [\ncontrol.isExpanded\nprop.children [\nBulma.input.text [\nprop.value model.Input\nprop.placeholder \"What needs to be done?\"\nprop.onChange (fun x -> SetInput x |> dispatch)\n]\n]\n]\nBulma.control.p [\nBulma.button.a [\ncolor.isPrimary\nprop.disabled (Todo.isValid model.Input |> not)\nprop.onClick (fun _ -> dispatch AddTodo)\nprop.text \"Add\"\n]\n]\n]\n]\n]\nCreate a new Model in the Index module, to keep track of the open page
type Page =\n| TodoList of TodoList.Model\n| NotFound type Model = { CurrentPage: Page }\nAdd a Msg type with a case of TodoList.Msg
type Msg =\n| TodoListMsg of TodoList.Msg\nCreate an update function (we moved the original one to TodoList). Handle the TodoListMsg by updating the TodoList Model. Wrap the command returned by the update of the todo list in a TodoListMsg before returning it. We expand this function later with other cases that deal with navigation.
let update (message: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch model.CurrentPage, message with\n| TodoList todoList, TodoListMsg todoListMessage ->\nlet newTodoListModel, newCommand = TodoList.update todoListMessage todoList\nlet model = { model with CurrentPage = TodoList newTodoListModel }\n\nmodel, newCommand |> Cmd.map TodoListMsg\nCreate a function initFromUrl; initialize the TodoList app when given the URL of the todo list app. Also return the command that TodoList's init may return, wrapped in a TodoListMsg
let initFromUrl url =\nmatch url with\n| [ \"todo\" ] ->\nlet todoListModel, todoListMsg = TodoList.init ()\nlet model = { CurrentPage = TodoList todoListModel }\n\nmodel, todoListMsg |> Cmd.map TodoListMsg\nAdd a wildcard, so any URLs that are not registered display the \"not found\" page
CodeDiff Index.fslet initFromUrl url =\nmatch url with\n...\n| _ -> { CurrentPage = NotFound }, Cmd.none\n let initFromUrl url =\n match url with\n ...\n+ | _ -> { CurrentPage = NotFound }, Cmd.none\nAdd an init function to Index; return the current page based on Router.currentUrl
let init () : Model * Cmd<Msg> =\nRouter.currentUrl ()\n|> initFromUrl\nAdd an UrlChanged case of string list to the Msg type
type Msg =\n...\n| UrlChanged of string list\n type Msg =\n ...\n+ | UrlChanged of string list\nHandle the case in the update function by calling initFromUrl
let update (message: Msg) (model: Model) : Model * Cmd<Msg> =\n...\nmatch model.CurrentPage, message with\n| _, UrlChanged url -> initFromUrl url\n let update (message: Msg) (model: Model) : Model * Cmd<Msg> =\n ...\n+ match model.CurrentPage, message with\n+ | _, UrlChanged url -> initFromUrl url\nComplete the pattern match in the update function, adding a case with a wildcard for both message and model. Return the model, and no command
let update (message: Msg) (model: Model) : Model * Cmd<Msg> =\n...\n| _, _ -> model, Cmd.none\n let update (message: Msg) (model: Model) : Model * Cmd<Msg> =\n ...\n+ | _, _ -> model, Cmd.none\nAdd a function containerBox to the Index module. If the CurrentPage is of TodoList, render the todo list using TodoList.view; in order to dispatch a TodoList.Msg, it needs to be wrapped in a TodoListMsg.
For the NotFound page, return a \"Page not found\" box
let containerBox model dispatch =\nmatch model.CurrentPage with\n| TodoList todoModel -> TodoList.view todoModel (TodoListMsg >> dispatch)\n| NotFound -> Bulma.box \"Page not found\"\nWrap the content of the view function in a router.children property of a React.router. Also add an onUrlChanged property, that dispatches the 'UrlChanged' message.
let view (model: Model) (dispatch: Msg -> unit) =\nReact.router [\nrouter.onUrlChanged (UrlChanged >> dispatch)\nrouter.children [\nBulma.hero [\n...\n]\n]\n]\n let view (model: Model) (dispatch: Msg -> unit) =\n+ React.router [\n+ router.onUrlChanged (UrlChanged >> dispatch)\n+ router.children [\n Bulma.hero [\n ...\n ]\n+ ]\n+ ]\nThe routing should work now. Try navigating to localhost:8080; you should see a page with \"Page not Found\". If you go to localhost:8080/#/todo, you should see the todo app.
# sign
You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
"},{"location":"v4-recipes/ui/add-routing/","title":"How do I add routing to a SAFE app with a shared model for all pages?","text":"Written for SAFE template version 4.2.0
When building larger apps, you probably want different pages to be accessible through different URLs. In this recipe, we show you how to add routes to different pages to an application, including adding a \"page not found\" page that is displayed when an unknown URL is entered.
In this recipe we use the simplest approach to storing states for multiple pages, by creating a single state for the full app. A potential benefit of this approach is that the state of a page is not lost when navigating away from it. You will see how that works at the end of the recipe.
"},{"location":"v4-recipes/ui/add-routing/#1-adding-the-feliz-router","title":"1. Adding the Feliz router","text":"Install Feliz.Router in the client project
dotnet paket add Feliz.Router -p Client -V 3.8\nFeliz.Router versions
At the time of writing, the current version of the SAFE template (4.2.0) does not work well with the latest version of Feliz.Router (4.0). To work around this, we install Feliz.Router 3.8, the latest version that works with SAFE template version 4.2.0.
If you are working with a newer version of the SAFE template, it might be worth trying to install the newest version of Feliz.Router. To see the installed version of the SAFE template, run in the command line:
dotnet new --list\nTo include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router\nAdd the current page to the model of the client, using a new Page type
type Page =\n| TodoList\n| NotFound\n\ntype Model =\n{ CurrentPage: Page\nTodos: Todo list\nInput: string }\n+ type Page =\n+ | TodoList\n+ | NotFound\n+\n- type Model = { Todos: Todo list; Input: string }\n+ type Model =\n+ { CurrentPage: Page\n+ Todos: Todo list\n+ Input: string }\nCreate a function to parse a URL to a page, including a wildcard for unmapped pages
let parseUrl url = match url with\n| [\"todo\"] -> Page.TodoList\n| _ -> Page.NotFound\nOn initialization, set the current page
CodeDifflet init () : Model * Cmd<Msg> =\nlet page = Router.currentUrl () |> parseUrl\n\nlet model =\n{ CurrentPage = page\nTodos = []\nInput = \"\" }\n...\nmodel, cmd\n let init () : Model * Cmd<Msg> =\n+ let page = Router.currentUrl () |> parseUrl\n+\n- let model = { Todos = []; Input = \"\" }\n+ let model =\n+ { CurrentPage = page\n+ Todos = []\n+ Input = \"\" }\n ...\n model, cmd\nAdd an action to handle navigation.
To the Msg type, add a PageChanged case of Page
type Msg =\n...\n| PageChanged of Page\n type Msg =\n ...\n+ | PageChanged of Page\nAdd the PageChanged update action
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch msg with\n...\n| PageChanged page -> { model with CurrentPage = page }, Cmd.none\n let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\n match msg with\n ...\n+ | PageChanged page -> { model with CurrentPage = page }, Cmd.none\nRename the view function to todoView
let todoView (model: Model) (dispatch: Msg -> unit) =\nBulma.hero [\n...\n]\n- let view (model: Model) (dispatch: Msg -> unit) =\n+ let todoView (model: Model) (dispatch: Msg -> unit) =\n Bulma.hero [\n ...\n ]\nAdd a new view function, that returns the appropriate page
let view (model: Model) (dispatch: Msg -> unit) =\nmatch model.CurrentPage with\n| TodoList -> todoView model dispatch\n| NotFound -> Bulma.box \"Page not found\"\nAdding UI elements to every page of the website
In this recipe, we moved all the page content to the todoView, but you don't have to. You can add UI you want to display on every page of the application to the view function.
Add the React.Router element as the outermost element of the view. Dispatch the PageChanged event on onUrlChanged
let view (model: Model) (dispatch: Msg -> unit) =\nReact.router [\nrouter.onUrlChanged (parseUrl >> PageChanged >> dispatch)\nrouter.children [\nmatch model.CurrentPage with\n...\n]\n]\n let view (model: Model) (dispatch: Msg -> unit) =\n+ React.router [\n+ router.onUrlChanged (parseUrl >> PageChanged >> dispatch)\n router.children [\n match model.CurrentPage with\n ...\n ]\n ]\nThe routing should work now. Try navigating to localhost:8080; you should see a page with \"Page not Found\". If you go to localhost:8080/#/todo, you should see the todo app.
To see how the state is maintained even when navigating away from the page, type something in the text box and move away from the page by entering another path in the address bar. Then go back to the todo page. The entered text is still there.
# sign
You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
"},{"location":"v4-recipes/ui/add-routing/#10-adding-more-pages","title":"10. Adding more pages","text":"Now that you have set up the routing, adding more pages is simple: add a new case to the Page type; add a route for this page in the parseUrl function; add a function that takes a model and dispatcher to generate your new page, and add a new case to the pattern match inside the view function to display the new case.
If you wish to use your own CSS or SASS stylesheets with SAFE apps, you can embed either through webpack. The template already includes all required NPM packages you may need, so you will only need to configure webpack to reference your stylesheet and include in the outputs.
"},{"location":"v4-recipes/ui/add-style/#adding-the-stylesheet","title":"Adding the Stylesheet","text":"First, create a CSS file in the src/Client folder of your solution e.g style.css.
The same approach can be taken for .scss files.
Inside the webpack.config.js file, add the following variable to the CONFIG object, which points to the style file you created previously.
cssEntry: './src/Client/style.css',\nFind the entry field in the module.exports object at the bottom of the file, and replace it with the following:
entry: isProduction ? {\napp: [resolve(CONFIG.fsharpEntry), resolve(CONFIG.cssEntry)]\n} : {\napp: resolve(CONFIG.fsharpEntry),\nstyle: resolve(CONFIG.cssEntry)\n},\nThis combines the css and F# outputs into a single bundle for production, and separately for dev.
"},{"location":"v4-recipes/ui/add-style/#im-using-the-minimal-template","title":"I'm using the Minimal Template","text":""},{"location":"v4-recipes/ui/add-style/#1-embed-css-into-outputs","title":"1. Embed CSS into outputs","text":"Find the entry field in the module.exports object at the bottom of the file, and replace it with the following:
entry: {\napp: [\nresolve('./src/Client/Client.fsproj'),\nresolve('./src/Client/style.css')\n]\n},\nYou can now style your app by writing to the style.css file.
Tailwind is a utility-first CSS framework packed that can be composed to build any design, directly in your markup.
Add a stylesheet to the project
Install the required npm packages
npm install -D tailwindcss postcss autoprefixer postcss-loader\ntailwind.config.js npx tailwindcss init\nAmend the content array in the tailwind.config.js as follows
module.exports = {\ncontent: [\n'./src/Client/**/*.html',\n'./src/Client/**/*.fs',\n],\ntheme: {\nextend: {},\n},\nplugins: [],\n}\nCreate a postcss.config.js with the following
module.exports = {\nplugins: {\ntailwindcss: {},\nautoprefixer: {},\n}\n}\nAdd the Tailwind layers to your style.css
@tailwind base;\n@tailwind components;\n@tailwind utilities;\nFind the module.rules field in the webpack.config.js and in the css files rule\u2019s use field add postcss-loader
{\ntest: /\\.(sass|scss|css)$/,\nuse: [\nisProduction\n? MiniCssExtractPlugin.loader\n: 'style-loader',\n'css-loader',\n{\nloader: 'sass-loader',\noptions: { implementation: require('sass') }\n},\n'postcss-loader'\n],\n},\nIn the src/Client folder find the code in Index.fs to show the list of todos and add a Tailwind text colour class(text-red-200)
for todo in model.Todos do\nHtml.li [\nprop.classes [ \"text-red-200\" ]\nprop.text todo.Description\n]\nYou should see some nice red todos proving that Tailwind is now in your project
"},{"location":"v4-recipes/ui/cdn-to-npm/","title":"How do I migrate from a CDN stylesheet to an NPM package?","text":"Though the SAFE template default for referencing a stylesheet is to use a CDN, it\u2019s quite reasonable to want to use an NPM package instead. One common case is that it enables you to further customise Bulma themes by overriding Sass variables.
"},{"location":"v4-recipes/ui/cdn-to-npm/#1-remove-the-cdn-reference","title":"1. Remove the CDN Reference","text":"Find the following line in src/Client/index.html and delete it before moving on:
<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css\">\nGo ahead and add the Bulma NPM package to your project.
See: How do I add an NPM package to the client?
"},{"location":"v4-recipes/ui/cdn-to-npm/#3-load-the-stylesheets","title":"3. Load the Stylesheets","text":"There are two ways for loading the stylesheets:
"},{"location":"v4-recipes/ui/cdn-to-npm/#fable-interop","title":"Fable Interop","text":"A quick and easy way to reference this NPM package in an F# file is to insert the following couple of lines:
open Fable.Core.JsInterop\nimportAll \"bulma/bulma.sass\"\nYou can use this approach for any NPM package.
"},{"location":"v4-recipes/ui/cdn-to-npm/#b-using-sass","title":"b. Using Sass","text":"@import \"~bulma/bulma.sass\"\nRemove / replace all the references to Bulma in fsharp code
Remove any stylesheet links to Bulma which may exist in the index.html page, or in other html pages.
Optional: If using Paket ensure Fable.Core is set to a specified version.
In paket.dependencies, make sure there is a line like so: Fable.Core ~> 3
Warning
SAFE is not yet compatible with newer versions of Fable.Core. In the past, the version was not pinned so it was possible to accidentally upgrade to an incompatible version.
Info
To avoid specifying a version when adding a dependency - if it is not already pinned to a specific version - you can use the --keep-major flag to make the upgrade more conservative.
Remove Fulma and Feliz.Bulma
Paket:
dotnet paket remove Fulma\ndotnet paket remove Feliz.Bulma\nNuGet:
cd src/Client\ndotnet remove package Fulma\ndotnet remove package Feliz.Bulma\nWritten for SAFE template version 4.2.0
UseElmish is a powerful package that allows you to write standalone components using Elmish. A component built around the UseElmish hook has its own view, state and update function.
In this recipe we add routing to a safe app, and implement the todo list page using the UseElmish hook.
Pin Fable.Core to V3
At the time of writing, the published version of the SAFE template does not have the version of Fable.Core pinned; this can create problems when installing dependencies.
If you are using version v.4.2.0 of the template, pin Fable.Core to version 3 in paket.depedencies at the root of the project
...\n-nuget Fable.Core\n+nuget Fable.Core ~> 3\n...\nInstall Feliz.Router in the Client project
dotnet paket add Feliz.Router -p Client -V 3.8\nFeliz.Router versions
At the time of writing, the current version of the SAFE template (4.2.0) does not work well with the latest version of Feliz.Router (4.0). To work around this, we install Feliz.Router 3.8, the latest version that works with SAFE template version 4.2.0.
If you are working with a newer version of the SAFE template, it might be worth trying to install the newest version of Feliz.Router. To see the installed version of the SAFE template, run in the command line:
dotnet new --list\nInstall Feliz.UseElmish in the Client project
dotnet paket add Feliz.UseElmish -p client\nOpen the router in the client project
Index.fsopen Feliz.Router\nCreate a new Module TodoList in the client project. Move the following functions and types to the TodoList Module:
Also open Shared, Fable.Remoting.Client, Elmish, Feliz.Bulma and Feliz.
module TodoList\n\nopen Shared\nopen Fable.Remoting.Client\nopen Elmish\n\nopen Feliz.Bulma\nopen Feliz\n\ntype Model = { Todos: Todo list; Input: string }\n\ntype Msg =\n| GotTodos of Todo list\n| SetInput of string\n| AddTodo\n| AddedTodo of Todo\n\nlet todosApi =\nRemoting.createApi ()\n|> Remoting.withRouteBuilder Route.builder\n|> Remoting.buildProxy<ITodosApi>\n\nlet init () : Model * Cmd<Msg> =\nlet model = { Todos = []; Input = \"\" }\nlet cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos\n\nmodel, cmd\n\nlet update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch msg with\n| GotTodos todos -> { model with Todos = todos }, Cmd.none\n| SetInput value -> { model with Input = value }, Cmd.none\n| AddTodo ->\nlet todo = Todo.create model.Input\n\nlet cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo\n\n{ model with Input = \"\" }, cmd\n| AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none\n\nlet containerBox (model: Model) (dispatch: Msg -> unit) =\nBulma.box [\nBulma.content [\nHtml.ol [\nfor todo in model.Todos do\nHtml.li [ prop.text todo.Description ]\n]\n]\nBulma.field.div [\nfield.isGrouped\nprop.children [\nBulma.control.p [\ncontrol.isExpanded\nprop.children [\nBulma.input.text [\nprop.value model.Input\nprop.placeholder \"What needs to be done?\"\nprop.onChange (fun x -> SetInput x |> dispatch)\n]\n]\n]\nBulma.control.p [\nBulma.button.a [\ncolor.isPrimary\nprop.disabled (Todo.isValid model.Input |> not)\nprop.onClick (fun _ -> dispatch AddTodo)\nprop.text \"Add\"\n]\n]\n]\n]\n]\nopen Feliz.UseElmish in the TodoList Module
TodoList.fsopen Feliz.UseElmish\n...\nIn the todoList module, rename containerBox to view. On the first line, call React.useElmish passing it the init and update functions. Bind the output to model and dispatch
let view (model: Model) (dispatch: Msg -> unit) =\nlet model, dispatch = React.useElmish(init, update, [||])\n...\n-let containerBox (model: Model) (dispatch: Msg -> unit) =\n+let view (model: Model) (dispatch: Msg -> unit) =\n+ let model, dispatch = React.useElmish(init, update, [||])\n ...\nReplace the arguments of the function with unit, and add the ReactComponent attribute to it
[<ReactComponent>]\nlet view () =\n...\n+ [<ReactComponent>]\n- let view (model: Model) (dispatch: Msg -> unit) =\n+ let view () =\n ...\nIn the Index module, create a model that holds the current page
type Page =\n| TodoList\n| NotFound\n\ntype Model =\n{ CurrentPage: Page }\nCreate a function that initializes the app based on an url
Index.fslet initFromUrl url =\nmatch url with\n| [ \"todo\" ] ->\nlet model = { CurrentPage = TodoList }\n\nmodel, Cmd.none\n| _ ->\nlet model = { CurrentPage = NotFound }\n\nmodel, Cmd.none\nCreate a new init function, that fetches the current url, and calls initFromUrl.
let init () =\nRouter.currentUrl ()\n|> initFromUrl\nAdd a Msg type, with an PageChanged case
Index.fs
type Msg = | PageChanged of string list\nupdate function, that reinitializes the app based on an URL Index.fslet update (msg: Msg) (model: Model) : Model * Cmd<Msg> =\nmatch msg with\n| PageChanged url ->\ninitFromUrl url\nAdd a containerBox function to the Index module, that returns the appropriate page content
let containerBox (model: Model) (dispatch: Msg -> unit) =\nmatch model.CurrentPage with\n| NotFound -> Bulma.box \"Page not found\"\n| TodoList -> TodoList.view ()\nWrap the content of the view method in a React.Router element's router.children property, and add a router.onUrlChanged property to dispatch the urlChanged message
let view (model: Model) (dispatch: Msg -> unit) =\nReact.router [\nrouter.onUrlChanged ( PageChanged>>dispatch )\nrouter.children [\nBulma.hero [\n...\n]\n]\n]\nlet view (model: Model) (dispatch: Msg -> unit) =\n+ React.router [\n+ router.onUrlChanged ( PageChanged>>dispatch )\n+ router.children [\n Bulma.hero [\n ...\n ]\n+ ]\n+ ]\nThe routing should work now. Try navigating to localhost:8080; you should see a page with \"Page not Found\". If you go to localhost:8080/#/todo, you should see the todo app.
# sign
You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
"},{"location":"v4-recipes/ui/use-different-bulma-themes/","title":"How Do I Use Different Bulma Themes?","text":""},{"location":"v4-recipes/ui/use-different-bulma-themes/#bulmaswatch","title":"Bulmaswatch","text":"Bulmaswatch is a great website for finding free Bulma themes. However, once you decide on what theme to use, visit this website to get a CDN link to its CSS file. For this recipe, I will use the Nuclear theme.
"},{"location":"v4-recipes/ui/use-different-bulma-themes/#i-am-using-the-standard-template","title":"I am Using the Standard Template","text":"The standard template uses a CDN (Content Delivery Network) link to reference the Bulma theme that it uses. Changing the theme then, is as simple as changing this link. Since the class names Bulma uses to style HTML elements remain the same, we don\u2019t need to change anything else.
"},{"location":"v4-recipes/ui/use-different-bulma-themes/#1-find-the-link","title":"1. Find the Link","text":"In your index.html, find the line that references the Bulma stylesheet that\u2019s used in the template through a CDN link. It will look like the following:
<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css\">\nGo ahead and replace this link with the link to the theme that you want to use, which in my case is Nuclear:
<link rel=\"stylesheet\" href=\"https://cdnjs.cloudflare.com/ajax/libs/bulmaswatch/0.8.1/nuclear/bulmaswatch.min.css\">\nIn your index.html, add the following line anywhere between the opening and closing head tags:
<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css\">\nRead this recipe for the rest of the instructions.
And that\u2019s it. You should now see your app styled in accordance with the Bulma theme you\u2019ve just switched to.
"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 000000000..e6fa04a9c --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,553 @@ + +The following companies provide commercial training, support, consultancy and development services for SAFE Stack applications.
+
Compositional IT are experts in designing functional-first, cloud-ready systems, offering consultancy and support, training and development. Run by an F# MVP and well-known member of the .NET community, they are dedicated to raising awareness of the benefits of both functional programming and harnessing the power of the cloud to deliver high-quality, low-cost solutions.
+
Lambda Factory is a consulting company specializing in designing and building complex systems using Functional Programming languages such as F#, Elm and Elixir. It also offers help with introducing functional programming and open source driven development to the organization, as well as trainings, workshops and mentoring. Founded by open source contributor and well-known member of F# Community, Lambda Factory has been committed to supporting F# Community and helping it grow.
+
Fuzzy Cloud is a fast-growing team of highly skilled and passionate IT professionals who can deliver services that help you speed up innovation and maximize efficiency. Our services are dynamic, scalable, resilient and responsive enabling rapid growth and high value for our clients. We take a highly collaborative approach to align our services with your business goals. We provide consulting in area like Cloud, Cross Platform mobile development, Machine Learning etc using Languages like F#, Python, Dart and few others.
+The SAFE stack was written largely by the community as open source projects, such as Saturn, Giraffe, Fable and Elmish (as well as the alternative elements within the stack). All those teams are always happy to contribute and help out.
+You can also reach out to the SAFE team on @safe_stack or on the regular F# channels on Slack: either the official F# Foundation Slack (an F# Foundation membership is required) or on the Functional Programming Slack. We'll be expanding this over time.
+ + + + + + + + +The SAFE Template is a dotnet CLI template for SAFE Stack projects, designed to get you up and running as quickly as possible, with flexible options to suit your application. The template gets you up and running with the most common elements of the stack with minimal configuration options.
+All template options come with a fully working end-to-end SAFE application with known-good dependencies on client (NPM) and server (NuGet), as well as a preconfigured Vite configuration file.
+Refer to the Quickstart guide to see basic guidance on how to install and use the template.
+The template provides two simple modes: the standard and minimal template.
+The standard template creates an opinionated SAFE Stack app that contains everything you'll need to start developing, testing and deploying applications into Azure.
+dotnet new SAFE
+Use this configuration if..
+The minimal template is a "bare-bones" SAFE Stack app with minimal value-add features.
+dotnet new SAFE -m
+Use this configuration if..
+| Feature | +Standard | +Minimal | +
|---|---|---|
| Styling | +Tailwind | +None | +
| Starter App | +Todo List | +None | +
| Communication | +Fable Remoting | +Raw HTTP | +
| .NET Package Manager | +Paket | +NuGet | +
| Build Tooling | +FAKE | +None | +
| Azure Integration | +Farmer | +None | +
| Testing Support | +Client and Server | +None | +
| Tooling | +VS Code Extensions, Fantomas | +None | +
The SAFE Stack now runs FAKE using a console app rather than a script.
+dotnet run
+Used for development purposes, and provides a great live-reload experience. It pulls down any dependencies required for both the client and server, before running both the client and server in a "watch" mode, so any changes you make on either side will be automatically applied without you needing to restart the application.
+++Navigating to
+http://localhost:8080/will load the application.
dotnet run Bundle
+Used to both build and package up your application in a production fashion, ready for deployment. It will restore all dependencies and build both the client and server in a production and release mode respectively, and correctly copy the outputs into the deploy folder in the root of the application. Once your build has completed, you can launch the entire application locally to test it as follows:
cd deploy
+Server
+++Navigating to
+http://localhost:5000/will load the application.
dotnet run Azure
+This target will deploy your application to Azure with a fully configured Application Insights instance. You do not need to pre-create any resources in Azure - the template will create everything needed, using free SKUs so you can test without any costs.
+++You must already have an Azure account and will be prompted to log into it during the deployment process.
+
This build step uses both the Azure CLI and Farmer projects to create all resources in just a few lines of code.
+++The name of resources will be generated based on the folder in which you created the application. These may be incompatible with Azure naming rules, or may already be in use (Azure web applications must be globally unique) so you may have to modify the name of the webapp to pick one that is acceptable.
+
dotnet run RunTests
+This target behaves similarly to the standard Run target, except that it launches the unit tests for both client and server.
+++Launch the client tests on
+http://localhost:8081/
dotnet run Format
+This target will format all the F# files in the src folder using Fantomas. Out of the box, Fantomas tries to reformat the code according to the F# style guide by Microsoft. For more info, check out the documentation.
Please feel free to submit a PR to add testimonials to this page!
+++SAFE gives us a fast development cycle for our web and mobile platforms
+
We at msu solutions GmbH are big fans of SAFE stack. For the last couple of years we were already using F# open source technologies for web and mobile projects. Tools like the Fable compiler and elmish are rock solid and a pleasure to work with.
+Since the release of SAFE, we see that all these important technologies are now bundled and tested under one big umbrella. +Especially the commercial support for SAFE is very important for us and our customers.
+++It just works!
+
The docs are very detailed and helpful. I got the template up and running on a public URL on Azure within one hour. Without any issues. +Even though I am new to dotnet core and Azure.
+++SAFE was the perfect place to start our biological design and data management platform
+
Demetrix uses F# for DNA design and data management in our research pipeline. Our data systems are built on top of SAFE and it was a great experience for both veteran F# developers and people new to the environment. I would start with SAFE again in a heartbeat for a new project. We shared some of our experiences at Open F# 2018.
+++Spoil your customers with F# and the SAFE stack!
+
Porting a production web app from TypeScript/React to use the SAFE stack turned out to be a huge win. Sharing F# models on the front and back-end allows you to leverage the excellent F# compiler and type system when designing and refactoring your codebase. Using a type provider (in our case, SQLProvider) extends this coverage to your database as well. This means that changes to any part of your application will be picked up by the compiler which will essentially guide you to every relevant place in the source code that needs to be updated. This is so effective that once you experience it, you will never want to be without it.
+On the front end, the Elmish pattern, which may look intimidating at first glance, is actually quite fun and intuitive to write. More importantly, it guides you into the "pit of success" by making you write highly testable "pure functions" that outline your UI state transitions (in your update function). Putting all state transitions in one place becomes a breath of fresh air because it eliminates the spaghetti code that can happen in MVVM view models of even modest complexity. Do you have a complex "sort" that needs to be handled in your update? You can easily write a unit test in F# that passes in the relevant command input for that. No mocking is required because it will be a pure function!
+If you still feel leery of the Elmish pattern, you are free to use React Hooks API or any other pattern you prefer. There are also many excellent external libraries - i.e. Feliz - that allow you to optionally use the Elmish pattern on only certain pages, among other things.
Worried about getting stuck? Don't worry because the F# community will practially crawl all over themselves to be the first to answer you question. There are also options for professional consultation as well. The community support is amazing! +The SAFE stack is designed to be as turn-key as possible, but there are also plenty of opportunities to customize the stack as you see fit.
+Overall, the SAFE stack has allowed me to completely spoil a very demanding customer with timely, bug-free deliverables.
+++I really appreciate the effort that went in to this!
+
The F# SAFE stack documentation is incredibly well done. One of the best features is the learning resources page that includes GitHub repos of example projects.
+++Never did Computer Science
+
The SAFE stack enables me to create full backend to frontend web apps in a matter of weeks!!
+++Recipes are concise solve only one problem and are composable
+
I find SAFE stack recipes have so much value. Thank you! Please keep on doing it.
+++After a year I still feel like F# with the SAFE stack is like high octane rocket fuel for developers.
+
The F# community have created, and made very accessible, a fantastic set of tools that allow you to write F# end to end on the web and in a way that embraces the existing world.
+ + + + + + + + +Fake is a DSL for build tasks that is modular, extensible and easy to start with. Fake allows you to easily build, bundle, deploy your app and more by executing a single command.
+++The standard template comes with a FAKE project by default, so this recipe only applies to the minimal template.
+
Create a new console app called 'Build' at the root of your solution
+dotnet new console -lang f# -n Build -o .
+++We are creating the project directly at the root of the solution in order to allow us to execute the build without needing to navigate into a subfolder.
+
Open the project you just created in your IDE and rename the module it contains from Program.fs to Build.fs.
This renaming isn't explicitly necessary, however it keeps your solution consistent with other SAFE apps and is a better name for the file really.
+++If you just rename the file directly rather than in your IDE, then the Build project won't be able to find it unless you edit the Build.fsproj file as well
+
Open Build.fs and paste in the following code.
open Fake.Core
+open Fake.IO
+open System
+
+let redirect createProcess =
+ createProcess
+ |> CreateProcess.redirectOutputIfNotRedirected
+ |> CreateProcess.withOutputEvents Console.WriteLine Console.WriteLine
+
+let createProcess exe arg dir =
+ CreateProcess.fromRawCommandLine exe arg
+ |> CreateProcess.withWorkingDirectory dir
+ |> CreateProcess.ensureExitCode
+
+let dotnet = createProcess "dotnet"
+
+let npm =
+ let npmPath =
+ match ProcessUtils.tryFindFileOnPath "npm" with
+ | Some path -> path
+ | None -> failwith "npm was not found in path."
+ createProcess npmPath
+
+let run proc arg dir =
+ proc arg dir
+ |> Proc.run
+ |> ignore
+
+let execContext = Context.FakeExecutionContext.Create false "build.fsx" [ ]
+Context.setExecutionContext (Context.RuntimeContext.Fake execContext)
+
+Target.create "Clean" (fun _ -> Shell.cleanDir (Path.getFullName "deploy"))
+
+Target.create "InstallClient" (fun _ -> run npm "install" ".")
+
+Target.create "Run" (fun _ ->
+ run dotnet "build" (Path.getFullName "src/Shared")
+ [ dotnet "watch run" (Path.getFullName "src/Server")
+ dotnet "fable watch --run webpack-dev-server" (Path.getFullName "src/Client") ]
+ |> Seq.toArray
+ |> Array.map redirect
+ |> Array.Parallel.map Proc.run
+ |> ignore
+)
+
+open Fake.Core.TargetOperators
+
+let dependencies = [
+ "Clean"
+ ==> "InstallClient"
+ ==> "Run"
+]
+
+[<EntryPoint>]
+let main args =
+ try
+ match args with
+ | [| target |] -> Target.runOrDefault target
+ | _ -> Target.runOrDefault "Run"
+ 0
+ with e ->
+ printfn "%A" e
+ 1
+Run the following command
+dotnet sln add Build.fsproj
+You will need to install the following dependencies:
+Fake.Core.Target
+Fake.IO.FileSystem
+We recommend migrating to Paket. +It is possible to use FAKE without Paket, however this will not be covered in this recipe.
+At the root of the solution, run dotnet paket install to install all your dependencies.
If you now execute dotnet run, the default target will be run. This will build the app in development mode and launch it locally.
To learn more about targets and FAKE in general, see Getting Started with FAKE.
+ + + + + + + + +When developing your SAFE application, the local runtime experience uses WebPack to run the client and redirect API calls to the server on a different port. However, when you deploy your application, you'll need to run your Saturn server which will serve up statically-built client resources (HTML, JavaScript, CSS etc.).
+If you created your SAFE app using the recommended defaults, your application already has a FAKE script which will do the bundling for you. You can create a bundle using the following command:
+dotnet run Bundle
+This will build and package up both the client and server and place them into the /deploy folder at the root of the repository.
++See here for more details on this build target.
+
If you created your SAFE app using the minimal option, you need to bundle up the client and server separately.
+Execute the following commands:
+npm install
+
+dotnet tool restore
+
+dotnet fable src/Client --run webpack
+This will build the client project and copy all outputs into /deploy/public.
Execute the following commands:
+cd src/Server
+dotnet publish -c release -o ../../deploy
+This will bundle the server project and copy all outputs into the deploy folder.
deploy folder at the root of your repository.Server.exe application.http://localhost:5000.You should now see your SAFE application.
+See this article for more information on architectural concerns regarding the move from dev to production and bundling SAFE Stack applications.
+ + + + + + + + +Using Docker makes it possible to deploy your application as a docker container or release an image on docker hub. This recipe walks you through creating a Dockerfile and automating the build and test process with Docker Hub.
Create a .dockerignore file with the same contents as .gitignore
cp .gitignore .dockerignore
+copy .gitignore .dockerignore
+Now, add the following lines to the .dockerignore file:
.git
+Create a Dockerfile with the following contents:
FROM mcr.microsoft.com/dotnet/sdk:6.0 as build
+
+# Install node
+RUN curl -sL https://deb.nodesource.com/setup_16.x | bash
+RUN apt-get update && apt-get install -y nodejs
+
+WORKDIR /workspace
+COPY . .
+RUN dotnet tool restore
+
+RUN dotnet run Bundle
+
+
+FROM mcr.microsoft.com/dotnet/aspnet:6.0-alpine
+COPY --from=build /workspace/deploy /app
+WORKDIR /app
+EXPOSE 5000
+ENTRYPOINT [ "dotnet", "Server.dll" ]
+This uses multistage builds to keep the final image small.
+Replace the line
+RUN dotnet run Bundle
+with
+RUN npm install
+RUN dotnet fable src/Client --run webpack
+RUN cd src/Server && dotnet publish -c release -o ../../deploy
+docker build -t my-safe-app .docker run -it -p 5000:80 my-safe-app++Because the build is done entirely in docker, Docker Hub automated builds can be setup to automatically build and push the docker image.
+
Create a docker-compose.server.test.yml file with the following contents:
version: '3.4'
+services:
+ sut:
+ build:
+ target: build
+ context: .
+ working_dir: /workspace/tests/Server
+ command: dotnet run
+docker-compose -f docker-compose.server.test.yml up --build
+You can add server tests to the minimal template with the testing the server recipe.
+++The template is not currently setup for automating the client tests in ci.
+Docker Hub can also run automated tests for you.
+Follow the instructions to enable Autotest on docker hub.
+
++Not recommended for most applications
+
If you often build with docker locally, you may wish to make the build faster by optimising the Dockerfile for caching. For example, it is not necessary to download all paket and npm dependencies on every build unless there have been changes to the dependencies.
+Furthermore, the client and server can be built in separate build stages so that they are cached independently. Enable Docker BuildKit to build them concurrently.
+This comes at the expense of making the dockerfile more complex; if any changes are made to the build such as adding new projects or migrating package managers, the dockerfile must be updated accordingly.
+The following should be a good starting point but is not guarenteed to work.
+FROM mcr.microsoft.com/dotnet/sdk:6.0 as build
+
+# Install node
+RUN curl -sL https://deb.nodesource.com/setup_16.x | bash
+RUN apt-get update && apt-get install -y nodejs
+
+WORKDIR /workspace
+COPY .config .config
+RUN dotnet tool restore
+COPY .paket .paket
+COPY paket.dependencies paket.lock ./
+
+FROM build as server-build
+COPY src/Shared src/Shared
+COPY src/Server src/Server
+RUN cd src/Server && dotnet publish -c release -o ../../deploy
+
+
+FROM build as client-build
+COPY package.json package-lock.json ./
+RUN npm install
+COPY webpack.config.js ./
+COPY src/Shared src/Shared
+COPY src/Client src/Client
+RUN dotnet fable src/Client --run webpack
+
+
+FROM mcr.microsoft.com/dotnet/aspnet:6.0-alpine
+COPY --from=server-build /workspace/deploy /app
+COPY --from=client-build /workspace/deploy /app
+WORKDIR /app
+EXPOSE 5000
+ENTRYPOINT [ "dotnet", "Server.dll" ]
+FAKE is a tool for build automation. The standard SAFE template comes with a ready-made build project at the root of the solution that provides support for many common SAFE tasks.
+If you would prefer not to use FAKE, you can of course simply ignore it, but this recipes shows how to completely remove it from your repository. It is important to note that having removed FAKE, you will have to follow a more manual approach to each of these processes. This recipe will only include instructions on how to build and deploy the application after removing FAKE.
+++Note that the minimal template does not use FAKE by default, and this recipe only applies to the standard template.
+
Delete Build.fs, Build.fsproj, Helpers.fs, paket.references at the root of the solution.
Remove the following dependencies +
dotnet paket remove Fake.Core.Target
+dotnet paket remove Fake.IO.FileSystem
+dotnet paket remove Farmer
+Now that you have the FAKE dependencies removed, you will have to separately run the server and the client.
+Navigate to src/Server inside a terminal and execute dotnet run.
Execute the following commands inside a terminal at the root of the solution.
+dotnet tool restore
+npm install
+dotnet fable src/Client --run webpack-dev-server
+The app will now be running at http://0.0.0.0:8080/. Navigate to this address in a browser to see your app running.
See this guide to learn how to package a SAFE application for deployment to e.g. Azure.
+Fable Remoting is a type-safe RPC communication layer for SAFE apps. It uses HTTP behind the scenes, but allows you to program against protocols that exist across the application without needing to think about the HTTP plumbing, and is a great fit for the majority of SAFE applications.
+++Note that the standard template uses Fable Remoting. This recipe only applies to the minimal template.
+
Add Fable.Remoting.Giraffe to the Server and Fable.Remoting.Client to the Client.
+++See How Do I Add a NuGet Package to the Server +and How Do I Add a NuGet Package to the Client.
+
You now need to create the protocol, or contract, of the API we’ll be creating. Insert the following below the Route module in Shared.fs:
+
type IMyApi =
+ { hello : unit -> Async<string> }
+We need to provide a basic routing function in order to ensure client and server communicate on the
+same endpoint. Find the Route module in src/Shared/Shared.fs and replace it with the following:
module Route =
+ let builder typeName methodName =
+ sprintf "/api/%s/%s" typeName methodName
+We now need to provide an implementation of the protocol on the server. Open src/Server/Server.fs and insert the following right after the open statements:
let myApi =
+ { hello = fun () -> async { return "Hello from SAFE!" } }
+We now need to "adapt" Fable Remoting into the ASP.NET pipeline by converting it into a Giraffe HTTP Handler. Don't worry - this is not hard. Find webApp in Server.fs and replace it with the following:
open Fable.Remoting.Server
+open Fable.Remoting.Giraffe
+
+let webApp =
+ Remoting.createApi()
+ |> Remoting.withRouteBuilder Route.builder // use the routing function from step 3
+ |> Remoting.fromValue myApi // use the myApi implementation from step 4
+ |> Remoting.buildHttpHandler // adapt it to Giraffe's HTTP Handler
+We now need a corresponding client proxy in order to be able to connect to the server. Open src/Client/Client.fs and insert the following right after the Msg type:
+
open Fable.Remoting.Client
+
+let myApi =
+ Remoting.createApi()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.buildProxy<IMyApi>
+Replace the following two lines in the init function in Client.fs:
let getHello() = Fetch.get<unit, string> Route.hello
+let cmd = Cmd.OfPromise.perform getHello () GotHello
+with this:
+let cmd = Cmd.OfAsync.perform myApi.hello () GotHello
+At this point, the app should work just as it did before. Now, expanding the API and adding a new endpoint is as easy as adding a new field to the API protocol we defined in Shared.fs, editing the myApi record in Server.fs with the implementation, and finally making calls from the proxy.
First off, you need to create a SAFE app, install the relevant dependencies, and wire them up to be available for use in your F# Fable code.
+Create a new SAFE app and restore local tools: +
dotnet new SAFE
+dotnet tool restore
+Install Fable.Form.Simple.Bulma using Paket: +
dotnet paket add --project src/Client/ Fable.Form.Simple.Bulma --version 3.0.0
+Install bulma and fable-form-simple-bulma npm packages: +
npm add fable-form-simple-bulma
+npm add bulma@0.9.0
+Create ./src/Client/style.scss with the following contents:
@import "~bulma";
+@import "~fable-form-simple-bulma";
++@import "~bulma";
++@import "~fable-form-simple-bulma";
+Update webpack config to include the new stylesheet:
+a. Add a cssEntry property to the CONFIG object:
cssEntry: './src/Client/style.scss',
++cssEntry: './src/Client/style.scss',
+b. Modify the entry property of the object returned from module.exports to include cssEntry:
entry: isProduction ? {
+ app: [resolve(config.fsharpEntry), resolve(config.cssEntry)]
+} : {
+ app: resolve(config.fsharpEntry),
+ style: resolve(config.cssEntry)
+},
+- entry: {
+- app: resolve(config.fsharpEntry)
+- },
++ entry: isProduction ? {
++ app: [resolve(config.fsharpEntry), resolve(config.cssEntry)]
++ } : {
++ app: resolve(config.fsharpEntry),
++ style: resolve(config.cssEntry)
++ },
+Remove the Bulma stylesheet link from ./src/Client/index.html, as it is no longer needed:
<link rel="icon" type="image/png" href="/favicon.png"/>
+- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css">
+ <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css">
+With the above preparation done, you can use Fable.Form.Simple.Bulma in your ./src/Client/Index.fs file.
Open the newly added namespaces:
+open Fable.Form.Simple
+open Fable.Form.Simple.Bulma
++open Fable.Form.Simple
++open Fable.Form.Simple.Bulma
+Create type Values to represent each input field on the form (a single textbox), and create a type Form which is an alias for Form.View.Model<Values>:
type Values = { Todo: string }
+type Form = Form.View.Model<Values>
++type Values = { Todo: string }
++type Form = Form.View.Model<Values>
+In the Model type definition, replace Input: string with Form: Form
type Model = { Todos: Todo list; Form: Form }
+-type Model = { Todos: Todo list; Input: string }
++type Model = { Todos: Todo list; Form: Form }
+Update the init function to reflect the change in Model:
let model = { Todos = []; Form = Form.View.idle { Todo = "" } }
+-let model = { Todos = []; Input = "" }
++let model = { Todos = []; Form = Form.View.idle { Todo = "" } }
+Change Msg discriminated union - replace the SetInput case with FormChanged of Form, and add string data to the AddTodo case:
type Msg =
+ | GotTodos of Todo list
+ | FormChanged of Form
+ | AddTodo of string
+ | AddedTodo of Todo
+type Msg =
+ | GotTodos of Todo list
+- | SetInput of string
+- | AddTodo
++ | FormChanged of Form
++ | AddTodo of string
+ | AddedTodo of Todo
+Modify the update function to handle the changed Msg cases:
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+ | FormChanged form -> { model with Form = form }, Cmd.none
+ | AddTodo todo ->
+ let todo = Todo.create todo
+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+ model, cmd
+ | AddedTodo todo ->
+ let newModel =
+ { model with
+ Todos = model.Todos @ [ todo ]
+ Form =
+ { model.Form with
+ State = Form.View.Success "Todo added"
+ Values = { model.Form.Values with Todo = "" } } }
+ newModel, Cmd.none
+let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+- | SetInput value -> { model with Input = value }, Cmd.none
++ | FormChanged form -> { model with Form = form }, Cmd.none
+- | AddTodo ->
+- let todo = Todo.create model.Input
+- let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+- { model with Input = "" }, cmd
++ | AddTodo todo ->
++ let todo = Todo.create todo
++ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
++ model, cmd
+- | AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none
++ | AddedTodo todo ->
++ let newModel =
++ { model with
++ Todos = model.Todos @ [ todo ]
++ Form =
++ { model.Form with
++ State = Form.View.Success "Todo added"
++ Values = { model.Form.Values with Todo = "" } } }
++ newModel, Cmd.none
+Create form. This defines the logic of the form, and how it responds to interaction:
let form : Form.Form<Values, Msg, _> =
+ let todoField =
+ Form.textField
+ {
+ Parser = Ok
+ Value = fun values -> values.Todo
+ Update = fun newValue values -> { values with Todo = newValue }
+ Error = fun _ -> None
+ Attributes =
+ {
+ Label = "New todo"
+ Placeholder = "What needs to be done?"
+ HtmlAttributes = []
+ }
+ }
+
+ Form.succeed AddTodo
+ |> Form.append todoField
++let form : Form.Form<Values, Msg, _> =
++ let todoField =
++ Form.textField
++ {
++ Parser = Ok
++ Value = fun values -> values.Todo
++ Update = fun newValue values -> { values with Todo = newValue }
++ Error = fun _ -> None
++ Attributes =
++ {
++ Label = "New todo"
++ Placeholder = "What needs to be done?"
++ HtmlAttributes = []
++ }
++ }
++
++ Form.succeed AddTodo
++ |> Form.append todoField
+In the function containerBox, remove the existing form view. Then replace it using Form.View.asHtml to render the view:
let containerBox (model: Model) (dispatch: Msg -> unit) =
+ Bulma.box [
+ Bulma.content [
+ Html.ol [
+ for todo in model.Todos do
+ Html.li [ prop.text todo.Description ]
+ ]
+ ]
+ Form.View.asHtml
+ {
+ Dispatch = dispatch
+ OnChange = FormChanged
+ Action = Form.View.Action.SubmitOnly "Add"
+ Validation = Form.View.Validation.ValidateOnBlur
+ }
+ form
+ model.Form
+ ]
+let containerBox (model: Model) (dispatch: Msg -> unit) =
+ Bulma.box [
+ Bulma.content [
+ Html.ol [
+ for todo in model.Todos do
+ Html.li [ prop.text todo.Description ]
+ ]
+ ]
+- Bulma.field.div [
+- ... removed for brevity ...
+- ]
++ Form.View.asHtml
++ {
++ Dispatch = dispatch
++ OnChange = FormChanged
++ Action = Form.View.Action.SubmitOnly "Add"
++ Validation = Form.View.Validation.ValidateOnBlur
++ }
++ form
++ model.Form
+ ]
+With the basic structure in place, it's easy to add functionality to the form. For example, the changes necessary to add a high priority checkbox are pretty small.
+ + + + + + + + +This recipe shows how to create an endpoint on the server and hook up it up to the client using HTTP POST. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
+A POST endpoint is normally used to send data from the client to the server in the body, for example from a form. This is useful when we need to supply more data than can easily be provided in the URI.
+++You may wish to use POST for "write" operations and use GETs for "reads", however this is a highly opinionated topic that is beyond the scope of this recipe.
+
Fable Remoting takes care of deciding whether to use POST or GET etc. - you don't have to worry about this. Refer to this recipe for more details.
+Create the type that will store the payload sent from the client to the server.
+type SaveCustomerRequest =
+ { Name : string
+ Age : int }
+Create a new function saveCustomer that will call the server. It supplies the customer to save, which
+is serialized and sent to the server in the body of the message.
let saveCustomer customer =
+ let save customer = Fetch.post<SaveCustomerRequest, int> ("/api/customer", customer)
+ Cmd.OfPromise.perform save customer CustomerSaved
+++The generic arguments of
+Fetch.postare the input and output types. The example above shows that +the input is of typeSaveCustomerRequestwith the response will contain an integer value. This may +be the ID generated by the server for the save operation.
This can now be called from within your update function e.g.
| SaveCustomer request ->
+ model, saveCustomer request
+| CustomerSaved generatedId ->
+ { model with GeneratedCustomerId = Some generatedId; Message = "Saved customer!" }, Cmd.none
+Create a function that can extract the payload from the body of the request using Giraffe's built-in model binding support:
+open FSharp.Control.Tasks
+open Giraffe
+open Microsoft.AspNetCore.Http
+open Shared
+
+/// Extracts the request from the body and saves to the database.
+let saveCustomer next (ctx:HttpContext) = task {
+ let! customer = ctx.BindModelAsync<SaveCustomerRequest>()
+ do! Database.saveCustomer customer
+ return! Successful.OK "Saved customer" next ctx
+}
+Tie your function into the router, using the post verb instead of get.
let webApp = router {
+ post "/api/customer" saveCustomer // Add this
+}
+This recipe shows how to create an endpoint on the server and hook up it up to the client. This recipe assumes that you have also followed this recipe and have an understanding of MVU messaging. This recipe only shows how to wire up the client and server.
+Fable Remoting is a library which allows you to create client/server messaging without any need to think about HTTP verbs or serialization etc.
+Add your new endpoint onto an existing API contract e.g. ITodosApi. Because Fable Remoting exposes your API through F# on client and server, you get type safety across both.
type ITodosApi =
+ { getCustomer : int -> Async<Customer option> }
+Create a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required. +
let loadCustomer customerId = async {
+ return Some { Name = "My Customer" }
+}
+++Note the use of
+asynchere. Fable Remoting uses async workflows, and not tasks. You can write functions that use task, but will have to at some point map to async usingAsync.AwaitTask.
Tie the function you've just written into the API implementation. +
let todosApi =
+ { ///...
+ getCustomer = loadCustomer
+ }
+Test out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc. See here for more details on the required format.
+Create a new function loadCustomer that will call the endpoint.
let loadCustomer customerId =
+ Cmd.OfAsync.perform todosApi.getCustomer customerId LoadedCustomer
+++Note the final value supplied,
+CustomerLoaded. This is theMsgcase that will be sent into the +Elmish loop once the call returns, with the returned data. It should take in a value that +matches the type returned by the Server e.g.CustomerLoaded of Customer option. See here +for more information.
This can now be called from within your update function e.g.
| LoadCustomer customerId ->
+ model, loadCustomer customerId
+This recipe shows how to create a GET endpoint on the server and consume it on the client using the Fetch API.
+Create a function that implements the back-end service that you require. Use standard functions to read from databases or other external sources as required. +
open Saturn
+open FSharp.Control.Tasks
+
+/// Loads a customer from the DB and returns as a Customer in json.
+let loadCustomer (customerId:int) next ctx = task {
+ let customer = { Name = "My Customer" }
+ return! json customer next ctx
+}
+++Note how we parameterise this function to take in the
+customerIdas the first argument. Any parameters you need should be supplied in this manner. If you do not need any parameters, just omit them and leave thenextandctxones.This example does not cover dealing with "missing" data e.g. invalid customer ID is found.
+
Tie the function into the router with a route.
+let webApp = router {
+ getf "/api/customer/%i" loadCustomer // Add this
+}
+++Note the use of
+getfrather thanget. If you do not need any parameters, just useget. See here for reference docs on the use of the Saturn router.
Test out your endpoint using e.g. web browser / Postman / REST Client for VS Code etc.
+Create a new function loadCustomer that will call the endpoint.
++This example uses Thoth.Fetch to download and deserialise the response.
+
let loadCustomer customerId =
+ let loadCustomer () = Fetch.get<unit, Customer> (sprintf "/api/customer/%i" customerId)
+ Cmd.OfPromise.perform loadCustomer () CustomerLoaded
+++Note the final value supplied,
+CustomerLoaded. This is theMsgcase that will be sent into the +Elmish loop once the call returns, with the returned data. It should take in a value that +matches the type returned by the Server e.g.CustomerLoaded of Customer. See here +for more information.
An alternative (and slightly more succinct) way of writing this is:
+let loadCustomer customerId =
+ let loadCustomer = sprintf "/api/customer/%i" >> Fetch.get<unit, Customer>
+ Cmd.OfPromise.perform loadCustomer customerId CustomerLoaded
+This can now be called from within your update function e.g.
| LoadCustomer customerId ->
+ model, loadCustomer customerId
+This recipe demonstrates the steps you need to take to store new data on the client using the MVU pattern, which is typically read from the Server. You will learn the steps required to modify the model, update and view functions to handle a button click which requests data from the server and handles the response.
+Create a type in the Shared project which will act as the contract type between client and server. As SAFE compiles F# into JavaScript for you, you only need a single definition which will automatically be shared. +
type Customer = { Name : string }
+Modify the Msg type to have two new messages:
type Msg =
+ // other messages ...
+ | LoadCustomer of customerId:int // Add this
+ | CustomerLoaded of Customer // Add this
+++You will see that this symmetrical pattern is often followed in MVU:
++
+- A command to initiate a call to the server for some data (LoadCustomer)
+- An event with the result of calling the command (CustomerLoaded)
+
Update the Model to store the Customer once it is loaded: +
type Model =
+ { // ...
+ TheCustomer : Customer option }
+++Make
+TheCustomeroptional so that it can be initialised asNone(see next step).
Update the init function to provide default data
+
let model =
+ { // ...
+ TheCustomer = None }
+Update your view to initiate the LoadCustomer event. Here, we create a button that will start loading customer 42 on click:
+
let view model dispatch =
+ Html.div [
+ // ...
+ Html.button [
+ prop.onClick (fun _ -> dispatch (LoadCustomer 42))
+ prop.text "Load Customer"
+ ]
+ ]
+Modify the update function to handle the new messages:
+
let update msg model =
+ match msg with
+ // ....
+ | LoadCustomer customerId ->
+ // Implementation to connect to the server to be defined.
+ | CustomerLoaded c ->
+ { model with TheCustomer = Some c }, Cmd.none
+++ + + + + + + + +The code to fire off the message to the server differs depending on the client / server communication you are using and normally whether you are reading or writing data. See here for more information.
+
Saturn is a functional alternative to MVC and Razor which sits on top of Giraffe. Giraffe itself is a functional wrapper around the ASP.NET Core web framework, making it easier to work with when using F#.
+Since Saturn is built on top of Giraffe, migrating to using "raw" Giraffe is relatively simple to do.
+Navigate to the Server module in the Server project.
+Remove +
open Saturn
+open Giraffe
+open Microsoft.AspNetCore.Builder
+open Microsoft.Extensions.DependencyInjection
+open Microsoft.Extensions.Hosting
+open Microsoft.AspNetCore.Hosting
+In the same module, we need to replace the Server's application computation expression with some functions which set up the default host, configure the application and register services.
Remove this
+let app =
+ application {
+ // ...setup functions
+ }
+
+run app
+and replace it with this
+let configureApp (app : IApplicationBuilder) =
+ app
+ .UseStaticFiles()
+ .UseGiraffe webApp
+
+let configureServices (services : IServiceCollection) =
+ services
+ .AddGiraffe() |> ignore
+
+
+Host.CreateDefaultBuilder()
+ .ConfigureWebHostDefaults(
+ fun webHostBuilder ->
+ webHostBuilder
+ .Configure(configureApp)
+ .ConfigureServices(configureServices)
+ .UseWebRoot("public")
+ |> ignore)
+ .Build()
+ .Run()
+If you are using the standard SAFE template, there is nothing more you need to do, as routing is taken care of by Fable Remoting.
+If however you are using the minimal template, you will need to replace the Saturn router expression with the Giraffe equivalent.
+Replace this +
let webApp =
+ router {
+ get Route.hello (json "Hello from SAFE!")
+ }
+with this +
let webApp = route Route.hello >=> json "Hello from SAFE!"
+The steps shown here are the minimal necessary to get a SAFE app running using Giraffe.
+As with any Server setup however, there are many more optional parameters that you may wish to configure, such as caching, response compression and serialisation options as seen in the default SAFE templates amongst many others.
+See the Giraffe and ASP.NET Core host builder, application builder and service collection docs for more information on this.
+ + + + + + + + +In SAFE apps, you can send a file from the server to the client as well as you can send any other type of data. However, there are a few details that make this case unique that varies on whether you use the standard or the minimal template.
+To begin, find the Route module in Shared.fs and create the following route inside it.
let file = "api/file"
+Find the webApp in Server.fs. Inside its router expression, add the following get expression.
open FSharp.Control.Tasks.V2
+
+let webApp =
+ router {
+ //...other handlers
+ get Route.file (fun next ctx ->
+ task {
+ let byteArray = System.IO.File.ReadAllBytes("~/files/file.xlsx")
+ ctx.SetContentType "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+ ctx.SetHttpHeader "Content-Disposition" "attachment;"
+ return! ctx.WriteBytesAsync (byteArray)
+ })
+ }
+What we're doing here is to read a file from the local drive, but where the file is retrieved from is irrelevant. Then, using ctx, which is of type HttpContext, we let the browser know about the type of data this handler is returning. The last line (again, using ctx) writes a byte array to the body of the HTTP response as well as handling some details that goes alongside this process.
Although not perfect, the best solution for handling the file download is creating an invisible download link, clicking it, and then removing it completely. The following block of code is all we need for this. Add it to the Index.fs file, somewhere above the view function.
open Fable.Core.JsInterop
+open Shared
+
+let downloadFile () =
+ let anchor = Browser.Dom.document.createElement "a"
+ anchor?style <- "display: none"
+ anchor?href <- Route.file
+ anchor?download <- "MyFile.xlsx"
+ anchor.click()
+ anchor.remove()
+++You could also pass in the name of the file or the route to be hit as a parameter.
+
Now, you can call the downloadFile function to initiate the file download.
Since the standard template uses Fable.Remoting, we need to edit our API definition first. Find your API type definition in Shared.fs. It's usually the last block of code. The one you see here is named IFileAPI, but the one you see in Shared.fs will be named differently. Edit this definition to have the download member you see below.
type IFileAPI =
+ { //...other routes
+ download : unit -> Async<byte[]> }
+Open the Server.fs file and find the API that implements the definition we've just edited. It should now have an error since we're not matching the definition at the moment. Add the following route to it
+let download () = async {
+ let byteArray = System.IO.File.ReadAllBytes("/fileFolder/file.xlsx")
+ return byteArray
+}
+++Make sure to replace "/fileFolder/file.xlsx" with the path to your file
+
Paste the following code into Index.fs, somewhere above the view function.
let downloadFile () =
+ async {
+ let! downloadedFile = todosApi.download ()
+ downloadedFile.SaveFileAs("downloaded-file.xlsx")
+ }
+++The
+SaveFileAsfuncion detects the mime-type/content-type automatically based on the file extension of the file input
Since the downloadFile function is asynchronous, we can't just call it anywhere in our view. The way we're going to deal with this is to create a Msg case and handle it in our update funciton.
type Msg =
+ //...other cases
+ | DownloadFile
+ | FileDownloaded of unit
+let update (msg: Msg) (model: Model): Model * Cmd<Msg> =
+ match msg with
+ //...other cases
+ | DownloadFile -> model, Cmd.OfAsync.perform downloadFile () FileDownloaded
+ | FileDownloaded () -> model, Cmd.none // You can do something else here
+Html.button [
+ prop.onClick (fun _ -> dispatch DownloadFile)
+ prop.text "Click to download"
+]
+Having added this last snippet of code into the view function, you will be able to download the file by clicking the button that will now be displayed in your UI. For more information visit the Fable.Remoting documentation
SAFE Stack makes it easy to catch and handle exceptions raised by the server on the client. Though the way we make a call to the server from the client is different between the standard and the minimal template, the way we handle server errors on the client is the same in principle.
+Update the model to store the error details that we receive from the server. Find the Model type in src/Client/Index.fs and add it the following Errors field:
type Model =
+ { ... // the rest of the fields
+ Errors: string list }
+Now, bind an empty list to the field record inside the init function:
let model =
+ { ... // the rest of the fields
+ Errors = [] }
+We now add a new message to handle errors that we get back from the server after making a request. Add the following case to the Msg type:
type Msg =
+ | ... // other message cases
+ | GotError of exn
+In this simple example, we will simply capture the Message of the exception. Add the following line to the end of the pattern match inside the update function:
| GotError ex ->
+ { model with Errors = ex.Message :: model.Errors }, Cmd.none
+The following steps will vary depending on whether you’re using the standard template or the minimal one.
+We now have to connect up the server response to the new message we created. Elmish has support for this through the either Cmd functions (instead of the perform functions). Make the following changes to your server call:
let cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos
+…and replace it with the following:
+let cmd = Cmd.OfAsync.either todosApi.getTodos () GotTodos GotError
+let cmd = Cmd.OfPromise.perform getHello () GotHello
+…and replace it with the following:
+let cmd = Cmd.OfPromise.either getHello () GotHello GotError
+Now, if you get an exception from the Server, its message will be added to the Errors field of the Model type. Instead of throwing the error, you can now display a meaningful text to the user like so:
[ for msg in errorMessages do
+ Html.p msg
+]
+SAFE Stack makes it really simple and easy to share code between the client and the server, since both of them are written in F#. The client side is transpiled into JavaScript via webpack, whilst the server side is compiled down to .NET CIL. Serialization between both happens in the background, so you don't have to worry about it.
+Let’s say the you have the following type in src/Server/Server.fs:
+
type Customer =
+ { Id : Guid
+ Name : string
+ Email : string
+ PhoneNumber : string }
+And you have the following function that is used to validate this Customer type in src/Client/Index.fs:
+
let customerIsValid customer =
+ (Guid.Empty = customer.Id
+ || String.IsNullOrEmpty customer.Name
+ || String.IsNullOrEmpty customer.Email
+ || String.IsNullOrEmpty customer.PhoneNumber)
+ |> not
+If at any point you realise you need to use both the Customer type and the customerIsValid function both in the Client and the Server, all you need to do is to move both of them to Shared project. You can either put them in the Shared.fs file, or create your own file in the Shared project (eg. Customer.fs). After this, you will be able to use both the Customer type and the customerIsValid function in both the Client and the Server.
SAFE comes out of the box with [Fable.Remoting] or [Thoth] for serialization. These will handle transport of data seamlessly for you.
+++ + + + + + + + +Be careful not to place code in
+Shared.fsthat depends on a Client or Server-specific dependency. If your code depends onFablefor example, in most cases it will not be suitable to place it in Shared, since it can only be used in Client. Similarly, if your types rely on .NET specific types in e.g. the framework class library (FCL), beware. Fable has built-in mappings for popular .NET types e.g.System.DateTimeandSystem.Math, but you will have to write your own mappers otherwise.
Fable makes it quick and easy to upload files from the client. Both the standard and the minimal template comes with Fable support by default.
+Create a file in the client project named FileUpload.fs somewhere before the Index.fs file and insert the following:
module FileUpload
+
+open Fable.React
+open Fable.React.Props
+open Fable.FontAwesome
+open Fable.Core
+open Fable.Core.JsInterop
+Then, add the following. The reader.onload block will be executed once we select and confirm a file to be uploaded. Read the FileReader docs to find out more.
let handleFileEvent onLoad (fileEvent:Browser.Types.Event) =
+ let files:Browser.Types.FileList = !!fileEvent.target?files
+ if files.length > 0 then
+ let reader = Browser.Dom.FileReader.Create()
+ reader.onload <- (fun _ -> reader.result |> unbox |> onLoad)
+ reader.readAsArrayBuffer(files.[0])
+++This step varies depending on whether you're using the standard or the minimal template. Apply only the instructions under the appropriate heading.
+
Insert the following block of code at the end of FileUpload.fs. This function will create a UI element to be used to upload files. Click here to find out more about Bulma's file input component.
open Feliz.Bulma
+
+let createFileUpload onLoad =
+ Bulma.file [
+ Bulma.fileLabel.label [
+ Bulma.fileInput [
+ prop.onChange (handleFileEvent onLoad)
+ ]
+ Bulma.fileCta [
+ Bulma.fileLabel.label "Choose a file..."
+ ]
+ ]
+ ]
+Insert the following block of code at the end of FileUpload.fs. This function will create a UI element to be used to upload files.
let createFileUpload onLoad =
+ let input = document.createElement "INPUT"
+ input.onchange <- (handleFileEvent onLoad)
+Having followed all these steps, you can now use the createFileUpload function in Index.fs to create the UI element for uploading files. One thing to note is that HandleFile is a case of the discriminated union type Msg that's in Index.fs. You can use this message case to send the file from the client to the server.
FileUpload.createFileUpload (HandleFile >> dispatch)
+In order to debug Server code from Visual Studio, we need set the correct URLs in the project's debug properties.
+You can do this through the Server project's Properties/Debug editor or by editing the launchSettings.json file which is in the properties folder.
After selecting the debug profile that you wish to edit (IIS Express or Server), you will need to set the App URL field to http://localhost:5000 and Launch browser field to http://localhost:8080. The process is very similar for VS Mac.
Once this is done, you can expect your launchSettings.json file to look something like this:
+
{
+ "iisSettings": {
+ "windowsAuthentication": false,
+ "anonymousAuthentication": true,
+ "iisExpress": {
+ "applicationUrl": "http://localhost:5000/",
+ "sslPort": 44330
+ }
+ },
+ "profiles": {
+ "IIS Express": {
+ "commandName": "IISExpress",
+ "launchBrowser": true,
+ "launchUrl": "http://localhost:8080/",
+ "environmentVariables": {
+ "ASPNETCORE_ENVIRONMENT": "Development"
+ }
+ },
+ "Server": {
+ "commandName": "Project",
+ "launchBrowser": true,
+ "launchUrl": "http://localhost:8080",
+ "environmentVariables": {
+ "ASPNETCORE_ENVIRONMENT": "Development"
+ },
+ "applicationUrl": "http://localhost:5000"
+ }
+ }
+}
+Since you will be running the server directly through Visual Studio, you cannot use a FAKE script to start the application, so launch the client directly using e.g. npm run start.
Set the server as your Startup project, either using the drop-down menu at the top of the IDE or by right clicking on the project itself and selecting Set as Startup Project. Select the profile that you set up earlier and wish to launch from the drop-down at the top of the IDE. Either press the Play button at the top of the IDE or hit F5 on your keyboard to start the Server debugging and launch a browser pointing at the website.
+Although we write our client-side code using F#, it is being converted into JavaScript at runtime by Fable and executed in the browser. +However, we can still debug it via the magic of source mapping. If you are using Visual Studio, you cannot directly connect to the browser debugger. You can, however, debug your client F# code using the browser's development tools.
+The exact instructions will depend on your browser, but essentially it simply involves:
+VS Code allows "full stack" debugging i.e. both the client and server. Prerequisites that you should install:
+Open the Command Palette using Ctrl+Shift+P and run Debug: Add Configuration.... This will ask you to choose a debugger; select Ionide LaunchSettings.
This will create a launch.json file in the root of your solution and also open it in the editor.
The only change required is to point it at the Server application, by replacing the program line with this:
"program": "${workspaceFolder}/src/Server/bin/Debug/net6.0/Server.dll",
+Tasks: Configure Task.Create tasks.json file from template. This will show you a list of pre-configured templates..NET Core."options": {"cwd": "src/Server"}, as shown below:{
+ // See https://go.microsoft.com/fwlink/?LinkId=733558
+ // for the documentation about the tasks.json format
+ "version": "2.0.0",
+ "tasks": [
+ {
+ "label": "build",
+ "command": "dotnet",
+ "type": "shell",
+ "options": {"cwd": "src/Server"},
+ "args": [
+ "build",
+ "debug-pt3.sln",
+ // Ask dotnet build to generate full paths for file names.
+ "/property:GenerateFullPaths=true",
+ // Do not generate summary otherwise it leads to duplicate errors in Problems panel
+ "/consoleloggerparameters:NoSummary"
+ ],
+ "group": "build",
+ "presentation": {
+ "reveal": "silent"
+ },
+ "problemMatcher": "$msCompile"
+ }
+ ]
+}
+Either hit F5 or open the Debugging pane and press the Play button to build and launch the Server with the debugger attached. +Observe that the Debug Console panel will show output from the server. The server is now running and you can set breakpoints and view the callstack etc.
+dotnet fable watch -o output -s --run npm run start from <repo root>/src/Client/.Debug: Open Link.http://localhost:8080/. This will launch a browser which is pointed at the URL and connect the debugger to it..fs.js files within VS Code.++ + + + + + + + +If you find that your breakpoints aren't being hit, try stopping the Client, disconnecting the debugger and re-launching them both.
+To find out more about the VS Code debugger, see here.
+
Testing on the client is a little different than on the server.
+This is because the code which is ultimately being executed in the browser is JavaScript, translated from F# by Fable, and so it must be tested in a JavaScript environment.
+Furthermore, code that is shared between the Client and Server must be tested in both a dotnet environment and a JavaScript environment.
+The SAFE template uses a library called Fable.Mocha which allows us to run the same tests in both environments. It mirrors the Expecto API and works in much the same way.
+If you are using the standard template then there is nothing more you need to do in order to start testing your Client.
+In the tests/Client folder, there is a project named Client.Tests with a single script demonstrating how to use Mocha to test the TODO sample.
+++Note the compiler directive here which makes sure that the Shared tests are only included when executing in a JavaScript (Fable) context. They are covered by Expecto under dotnet as you can see in Server.Tests.fs.
+
In order to run the tests, instead of starting your application using +
dotnet run
+dotnet run Runtests
+Once the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
++This command builds and runs the Server test project too. If you want to run the Client tests alone, you can simply launch the test server using
+npm run test:live, which executes a command stored inpackage.json.
If you are using the minimal template, you will need to first configure a test project as none are included.
+Create a .Net library called Client.Tests in the tests/Client subdirectory using the following commands:
+dotnet new ClassLib -lang F# -n Client.Tests -o tests/Client
+dotnet sln add tests/Client
+Reference the Client project from the Client.Tests project:
+dotnet add tests/Client reference src/Client
+Run the following command:
+dotnet add tests/Client package Fable.Mocha
+Add this function to Client.fs in the Client project
+let sayHello name = $"Hello {name}"
+Replace the contents of tests/Client/Library.fs with the following code:
module Tests
+
+open Fable.Mocha
+
+let client = testList "Client" [
+ testCase "Hello received" <| fun _ ->
+ let hello = Client.sayHello "SAFE V3"
+
+ Expect.equal hello "Hello SAFE V3" "Unexpected greeting"
+]
+
+let all =
+ testList "All"
+ [
+ client
+ ]
+
+[<EntryPoint>]
+let main _ = Mocha.runTests all
+Add a file called index.html to the tests/Client folder with following contents: +
<!DOCTYPE html>
+<html>
+ <head>
+ <title>SAFE Client Tests</title>
+ </head>
+ <body>
+ </body>
+</html>
+Add a file called webpack.tests.config.js to the root directory with the following contents:****
+// Template for webpack.config.js in Fable projects
+// Find latest version in https://github.com/fable-compiler/webpack-config-template
+
+// In most cases, you'll only need to edit the CONFIG object (after dependencies)
+// See below if you need better fine-tuning of Webpack options
+
+// Dependencies. Also required: core-js, @babel/core,
+// @babel/preset-env, babel-loader, sass, sass-loader, css-loader, style-loader, file-loader, resolve-url-loader
+var path = require('path');
+var webpack = require('webpack');
+var HtmlWebpackPlugin = require('html-webpack-plugin');
+var CopyWebpackPlugin = require('copy-webpack-plugin');
+
+var CONFIG = {
+ // The tags to include the generated JS and CSS will be automatically injected in the HTML template
+ // See https://github.com/jantimon/html-webpack-plugin
+ indexHtmlTemplate: 'tests/Client/index.html',
+ fsharpEntry: 'tests/Client/Library.fs.js',
+ outputDir: 'tests/Client',
+ assetsDir: 'tests/Client',
+ devServerPort: 8081,
+ // When using webpack-dev-server, you may need to redirect some calls
+ // to a external API server. See https://webpack.js.org/configuration/dev-server/#devserver-proxy
+ devServerProxy: undefined,
+ babel: undefined
+}
+
+// If we're running the webpack-dev-server, assume we're in development mode
+var isProduction = !process.argv.find(v => v.indexOf('webpack-dev-server') !== -1);
+var environment = isProduction ? 'production' : 'development';
+process.env.NODE_ENV = environment;
+console.log('Bundling for ' + environment + '...');
+
+// The HtmlWebpackPlugin allows us to use a template for the index.html page
+// and automatically injects <script> or <link> tags for generated bundles.
+var commonPlugins = [
+ new HtmlWebpackPlugin({
+ filename: 'index.html',
+ template: resolve(CONFIG.indexHtmlTemplate)
+ })
+];
+
+module.exports = {
+ // In development, split the JavaScript and CSS files in order to
+ // have a faster HMR support. In production bundle styles together
+ // with the code because the MiniCssExtractPlugin will extract the
+ // CSS in a separate files.
+ entry: {
+ app: resolve(CONFIG.fsharpEntry)
+ },
+ // Add a hash to the output file name in production
+ // to prevent browser caching if code changes
+ output: {
+ path: resolve(CONFIG.outputDir),
+ filename: isProduction ? '[name].[hash].js' : '[name].js'
+ },
+ mode: isProduction ? 'production' : 'development',
+ devtool: isProduction ? 'source-map' : 'eval-source-map',
+ optimization: {
+ splitChunks: {
+ chunks: 'all'
+ },
+ },
+ // Besides the HtmlPlugin, we use the following plugins:
+ // PRODUCTION
+ // - MiniCssExtractPlugin: Extracts CSS from bundle to a different file
+ // To minify CSS, see https://github.com/webpack-contrib/mini-css-extract-plugin#minimizing-for-production
+ // - CopyWebpackPlugin: Copies static assets to output directory
+ // DEVELOPMENT
+ // - HotModuleReplacementPlugin: Enables hot reloading when code changes without refreshing
+ plugins: isProduction ?
+ commonPlugins.concat([
+ new CopyWebpackPlugin({ patterns: [{ from: resolve(CONFIG.assetsDir) }] }),
+ ])
+ : commonPlugins.concat([
+ new webpack.HotModuleReplacementPlugin(),
+ ]),
+ resolve: {
+ // See https://github.com/fable-compiler/Fable/issues/1490
+ symlinks: false
+ },
+ // Configuration for webpack-dev-server
+ devServer: {
+ publicPath: '/',
+ contentBase: resolve(CONFIG.assetsDir),
+ host: '0.0.0.0',
+ port: CONFIG.devServerPort,
+ proxy: CONFIG.devServerProxy,
+ hot: true,
+ inline: true
+ },
+ module: {
+ rules: [
+
+ ]
+ }
+};
+
+function resolve(filePath) {
+ return path.isAbsolute(filePath) ? filePath : path.join(__dirname, filePath);
+}
+npm install
+dotnet fable watch src/Client --run webpack-dev-server --config webpack.tests.config
+Once the build is complete and the website is running, navigate to http://localhost:8081/ in a web browser. You should see a test results page that looks like this:
Testing your Server code in a SAFE app is just the same as in any other dotnet app, and you can use the same tools and frameworks that you are familiar with. These include all of the usual suspects such as NUnit, XUnit, FSUnit, Expecto, FSCheck, AutoFixture etc.
+In this guide we will look at using Expecto, as this is included with the standard SAFE template.
+If you are using the standard template, then there is nothing more you need to do in order to start testing your Server code.
+In the tests/Server folder, there is a project named Server.Tests with a single script demonstrating how to use Expecto to test the TODO sample.
+In order to run the tests, instead of starting your application using +
dotnet run
+you should instead use +
dotnet run RunTests
+
++This method builds and runs the Client test project too, which can be slow. If you want to run the Server tests alone, you can simply navigate to the tests/Server directory and run the project using
+dotnet run.
If you would like to use dotnet tests from the command line or the test runner that comes with Visual Studio, there are a couple of extra steps to follow.
+Run the following commands at the root of your solution: +
dotnet paket add Microsoft.NET.Test.Sdk -p Server.Tests
+dotnet paket add YoloDev.Expecto.TestSdk -p Server.Tests
+Open your ServerTests.fsproj file and add the following element:
+<PropertyGroup>
+ <GenerateProgramFile>false</GenerateProgramFile>
+</PropertyGroup>
+To allow your tests to be discovered, you will need to decorate them with a [<Tests>] attribute.
The provided test would look like this: +
[<Tests>]
+let server = testList "Server" [
+ testCase "Adding valid Todo" <| fun _ ->
+ let storage = Storage()
+ let validTodo = Todo.create "TODO"
+ let expectedResult = Ok ()
+
+ let result = storage.AddTodo validTodo
+
+ Expect.equal result expectedResult "Result should be ok"
+ Expect.contains (storage.GetTodos()) validTodo "Storage should contain new todo"
+]
+There are now two ways to run these tests.
+From the command line, you can just run +
dotnet test tests/Server
+Alternatively, if you are using Visual Studio or VS Mac you can make use of the built-in test explorers.
+
If you are using the minimal template, you will need to first configure a test project as none are included.
+Create a .Net 5 console project called Server.Tests in the tests/Server folder.
+dotnet new console -lang F# -n Server.Tests -o tests/Server
+dotnet sln add tests/Server
+Reference the Server project from the Server.Tests project:
+dotnet add tests/Server reference src/Server
+Run the following command:
+dotnet add tests/Server package Expecto
+Update the Server.fs file in the Server project to extract the message logic from the router like so: +
let getMessage () = "Hello from SAFE!"
+
+let webApp =
+ router {
+ get Route.hello (getMessage () |> json )
+ }
+Replace the contents of tests/Server/Program.fs with the following:
open Expecto
+
+let server = testList "Server" [
+ testCase "Message returned correctly" <| fun _ ->
+ let expectedResult = "Hello from SAFE!"
+ let result = Server.getMessage()
+ Expect.equal result expectedResult "Result should be ok"
+]
+
+[<EntryPoint>]
+let main _ = runTests defaultConfig server
+dotnet run -p tests/Server
+This will print out the results in the console window
+
Add the libraries Microsoft.NET.Test.Sdk and YoloDev.Expecto.TestSdk to your Test project, using NuGet.
++The way you do this will depend on whether you are using NuGet directly or via Paket. See this recipe for more details.
+
You can now add [<Test>] attributes to your tests so that they can be discovered, and then run them using the dotnet tooling in the same way as explained earlier for the standard template.
Hot reload is a great time-saving technology and something that every developer will find useful. Whenever changes are made to code, they are immediately reflected in the running application without needing to manually redeploy. The specific way that this is achieved depends on the nature of the application.
+In a SAFE app we have two distinct components, the Client and the Server. Whether you are using the minimal or standard SAFE template, there is nothing more you need to do in order to get started with hot reload.
+If you deploy your application and then make a change in the Client, after a moment it will be reflected in the browser without a full re-deployment. Importantly, the state of your application will be retained across the deployment, so you can continue where you left off. +This is achieved using the hot module replacement functionality provided by webpack.
+If your client project has been hand-rolled, or you simply wish to see how to add it from scratch:
+Add the following to the devServer object of your webpack config:
var devServer = {
+ // other fields elided...
+ hot: true,
+ proxy : {
+ // Redirect websocket requests that start with /socket/ to the server on the port 5000
+ // This is used by Hot Module Replacement
+ '/socket/**': {
+ target: 'http://localhost:5000',
+ ws: true
+ }
+ }
+}
+Import and create an instance HotModuleReplacementPlugin at the top of the webpack configuration file, and ensure that the plugin is added to module.exports:
// Import and create the HMR plugin
+var { HotModuleReplacementPlugin } = require('webpack');
+var hmrPlugin = new HotModuleReplacementPlugin();
+
+// other configuration...
+
+module.exports = {
+ // Add the HMR plugin to the module
+ plugins : [ /* other plugins... */, hmrPlugin ]
+}
+First, add the Fable.Elmish.Hmr package to the client:
+dotnet add package Fable.Elmish.Hmr
+Then, open the Elmish.HMR namespace in your app:
+#if DEBUG
+open Elmish.Debug
+open Elmish.HMR
+#endif
+++Best practice is to include hot module reloading in debug (not production) mode only, since production applications will not benefit from HMR and will only result in an increased bundle size.
+
Server reloading isn't quite as fully automated.
+If you make a change in the Server code and save your work, the project will automatically rebuild and launch itself. Once this is complete however you will need to refresh your browser to see any visual changes.
+++ + + + + + + + +If you are using the minimal template, you need to make sure you launch the Server using
+dotnet watch runrather than justdotnet run. The standard template takes care of this step for you using its FAKE build script. If you have already restored your NuGet dependencies, you can get a little boost in restart speed by usingdotnet watch run --no-restoreas well.
Sometimes you need to use a JS library directly, instead of using it through a wrapper library that makes it easy to use from F# code. In this case you need to import a module from the library. +Here are the most common import patterns used in JS.
+In most cases components use the default export syntax which is when the the component being exported from the module becomes available. For example, if the module being imported below looked something like: +
// module-name
+const foo = () => "hello"
+
+export default foo
+foo.
+import foo from 'module-name' // JS
+let foo = importDefault "module-name" // F#
+To ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element. +
Browser.Dom.console.log("imported value", foo)
+An example of this in use is how React is imported +
import React from "react"
+
+// Although in the newer versions of React this is uneeded
+In some cases components can use the named export syntax. In the below case "module-name" has an object/function/class that is called bar. By referncing it below it is brought into the current scope.
+For example, if the module below contained something like:
+
export const bar (x,y) => x + y
+import { bar } from "module-name" // JS
+let bar = import "bar" "module-name" // F#
+To ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element. +
Browser.Dom.console.log("imported value", bar)
+An example of this is how React hooks are imported +
import { useState } from "react"
+In rare cases you may have to import an entire module's contents and provide an alias in the below case we named it myModule. You can now use dot notation to access anything that is exported from module-name. For example, if the module being imported below includes an export to a function doAllTheAmazingThings() you could access it like:
+
myModule.doAllTheAmazingThings()
+import * as myModule from 'module-name' // JS
+let myModule = importAll "module-name" // F#
+To ensure that the import was successful you can console log the value and you should see the value in the browsers console window which you can get to by right-clicking and selecting the Inspect Element. +
Browser.Dom.console.log("imported value", myModule)
+An example of this is another way to import React +
import * as React from "react"
+
+// Uncommon since importDefault is the standard
+See the Fable docs for more ways to import modules and use JavaScript from Fable.
+ + + + + + + + +To use a third-party React library in a SAFE application, you need to write an F# wrapper around it. There are two ways for doing this - using Fable.React or using Feliz.
+This recipe uses the react-d3-speedometer NPM package for demonstration purposes. Add it to your Client before continuing.
+Create an empty file named ReactSpeedometer.fs in the Client project above Index.fs and insert the following statements at the beginning of the file.
module ReactSpeedometer
+
+open Fable.Core
+open Fable.Core.JsInterop
+open Fable.React
+Prop represents the props of the React component. In this recipe, we're using the props listed here for react-d3-speedometer. We model them in Fable.React using a discriminated union.
type Prop =
+ | Value of int
+ | MinValue of int
+ | MaxValue of int
+ | StartColor of string
+++One difference to note is that we use PascalCase rather than camelCase.
+Note that we can model any props here, both simple values and "event handler"-style ones.
+
Add the following function to the file. Note that the last argument passed into the ofImport function is a list of ReactElements to be used as children of the react component. In this case, we are passing an empty list since the component doesn't have children.
let reactSpeedometer (props : Prop list) : ReactElement =
+ let propsObject = keyValueList CaseRules.LowerFirst props // converts Props to JS object
+ ofImport "default" "react-d3-speedometer" propsObject [] // import the default function/object from react-d3-speedometer
+With all these in place, you can use the React element in your client like so:
+open ReactSpeedometer
+
+reactSpeedometer [
+ Prop.Value 10 // Since Value is already decalred in HTMLAttr you can use Prop.Value to tell the F# compiler its of type Prop and not HTMLAttr
+ MaxValue 100
+ MinValue 0
+ StartColor "red"
+ ]
+If you don't already have Feliz installed, add it to your client.
+In the Client projects Index.fs add the following snippets
open Fable.Core.JsInterop
+Within the view function +
Feliz.Interop.reactApi.createElement (importDefault "react-d3-speedometer", createObj [
+ "minValue" ==> 0
+ "maxValue" ==> 100
+ "value" ==> 10
+])
+createElement from Feliz.ReactApi.IReactApi takes the component you're wrapping react-d3-speedometer, the props that component takes and creates a ReactComponent we can use in F#.importDefault from Fable.Core.JsInterop is giving us access to the component and is equivalent to
+import ReactSpeedometer from "react-d3-speedometer"
+importDefault is the documentation for the component uses a default export "ReactSpeedometer". Please find a list of common import statetments at the end of this recipeAs a quick check to ensure that the library is being imported and we have no typos you can console.log the following at the top within the view function
+
Browser.Dom.console.log("REACT-D3-IMPORT", importDefault "react-d3-speedometer")
+createObj from Fable.Core.JsInterop takes a sequence of string * obj which is a prop name and value for the component, you can find the full prop list for react-d3-speedometer here.==> (short hand for prop.custom) to transform the sequence into a JavaScript object createObj [
+ "minValue" ==> 0
+ "maxValue" ==> 10
+]
+{ minValue: 0, maxValue: 10 }
+That's the bare minimum needed to get going!
+Once your component is working you may want to extract out the logic so that it can be used in multiple pages of your app. +For a full detailed tutorial head over to this blog post!
+ + + + + + + + +When you want to call a JavaScript library from your Client, it is easy to import and reference it using NPM.
+Run the following command: +
npm install name-of-package
+This will download the package into the solution's node_modules folder.
+You will also see a reference to the package in the Client's package.json file: +
"dependencies": {
+ "name-of-package": "^1.0.0"
+}
+Adding packages to the Client project is a very similar process to the Server, with a few key differences:
+Any references to the Server directory should be Client
Client code written in F# is converted into JavaScript using Fable. Because of this, we must be careful to only reference libraries which are Fable compatible.
+If the NuGet package uses any JS libraries you must install them.
+ For simplicity, use Femto to sync - if the NuGet package is compatible - or install via NPM manually, if not.
There are lots of great libraries available to choose from.
+ + + + + + + + +You can add NuGet packages to the server to give it more capabilities. You can download a wide variety of packages from the official NuGet site.
+In this example we will add the FsToolkit ErrorHandling package package.
+Navigate to the root directory of your solution and run:
+dotnet paket add FsToolkit.ErrorHandling -p Server
+This will add an entry to both the solution paket.dependencies file and the Server project's paket.reference file, as well as update the lock file with the updated dependency graph.
+++Find information on how you can convert your project from NuGet to Paket here.
+For a detailed explanation of package management using Paket, visit the official docs.
+
Run the following command:
+dotnet add package FsToolkit.ErrorHandling
+Once you have done this, you will find an element in your fsproj file which looks like this: +
<ItemGroup>
+ <PackageReference Include="FsToolkit.ErrorHandling" Version="1.4.3" />
+</ItemGroup>
+++ + + + + + + + +You can also achieve the same thing using the Visual Studio Package Manager, the VS Mac Package Manager or the Package Manager Console.
+For a detailed explanation of package management using NuGet, visit the official docs.
+
++Note that the minimal template uses NuGet by default. This recipe only applies to the full template.
+
Paket is a fully featured package manager that acts as an alternative to the NuGet package manager commonly used in .NET.
+It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
+For most use cases, we would recommend sticking with Paket. If, however, you are in a position where you wish to remove it and revert back to the NuGet package manager, you can easily do so with the following steps.
+In every project's .fsproj file you will find the following line. Remove it and save.
<Import Project="..\..\.paket\Paket.Restore.targets" />
+You will find this file at the root of your solution. Remove it from your solution if included and then delete it.
+Each project directory will contain a paket.references file. This lists all the NuGet packages that the project requires.
Inside a new ItemGroup in the project's .fsproj file you will need to add an entry for each of these packages.
<ItemGroup>
+ <PackageReference Include="Azure.Core" Version="1.24" />
+ <PackageReference Include="AnotherPackage" Version="2.0.1" />
+ <!--...add entry for each package in the references file...-->
+</ItemGroup>
+++You can find the version of each package in the
+paket.lockfile at the root of the solution. The version number is contained in brackets next to the name of the package at the first level of indentation. For example, in this case Azure.Core is version 1.24:
Azure.Core (1.24)
+ Microsoft.Bcl.AsyncInterfaces (>= 1.1.1)
+ System.Diagnostics.DiagnosticSource (>= 4.6)
+ System.Memory.Data (>= 1.0.2)
+ System.Numerics.Vectors (>= 4.5)
+ System.Text.Encodings.Web (>= 4.7.2)
+ System.Text.Json (>= 4.7.2)
+ System.Threading.Tasks.Extensions (>= 4.5.4)
+Once you have added all of your dependencies to the relevant .fsproj files, you can remove the folowing files and folders from your solution.
Files:
+* paket.lock
+* paket.dependencies
+* all of the paket.references files
Folders:
+* .paket
+* paket-files
If you open .config/dotnet-tools.json you will find an entry for paket. Remove it.
Alternatively, run
+dotnet tool uninstall paket
+Paket is a fully featured package manager that acts as an alternative to the NuGet package manager.
+It can help you reference libraries from NuGet, Git repositories or Http resources. It also provides precise control over your dependencies, separating direct and transitive references and capturing the exact configuration with each commit. You can find out more at the Paket website.
+++Note that the standard template uses Paket by default. This recipe only applies to the minimal template.
+
dotnet tool install paket
+dotnet tool restore
+Run this command to move existing NuGet references to Paket from your packages.config or .fsproj file: +
dotnet paket convert-from-nuget
+This will add three files to your solution, all of which should be committed to source control:
+For a more detailed explanation of this process see the official migration guide.
+++ + + + + + + + +In the case where you have added a NuGet project to a solution which is already using paket, run this command with the option
+--force.If you are working in Visual Studio and wish to see your Paket files in the Solution Explorer, you will need to add both the paket.lock and any paket.references files created in your project directories during the last step to your solution.
+
SAFE Stack uses Fable bindings, which are NuGet packages that provide idiomatic and type-safe wrappers around native JavaScript APIs. These bindings often rely on third-party JavaScript libraries distributed via the NPM registry. This leads to the problem of keeping both the NPM package in sync with its corresponding NuGet F# wrapper. Femto is a dotnet CLI tool that solves this issue.
+++For in-depth information about Femto, see Introducing Femto.
+
Navigate to the root folder of the solution and execute the following command: +
dotnet tool install femto
+In the root directory, run the following: +
dotnet femto ./src/Client
+alternatively, you can call femto directly from ./src/Client:
cd ./src/Client
+dotnet femto
+This will give you a report of discrepancies between the NuGet packages and the NPM packages for the project, as well as steps to take in order to resolve them.
+To sync your NPM dependencies with your NuGet dependencies, you can either manually follow the steps returned by step 2, or resolve them automatically using the following command: +
dotnet femto ./src/Client --resolve
+Keeping your NPM dependencies in sync with your NuGet packages is now as easy as repeating step 3. Of course, you can instead repeat the step 2 and resolve packages manually, too.
+ + + + + + + + +The default template uses in-memory storage. This recipe will show you how to replace the in-memory storage with LiteDB in the form of LiteDB.FSharp.
+++If you're using the minimal template, the first steps will show you how to add a LiteDB database; the remaining section of this recipe are designed to work off the default template's starter app.
+
Add the LiteDB.FSharp NuGet package to the server project.
+Replace the use of the ResizeArray in the Storage type with a database and collection:
open LiteDB.FSharp
+open LiteDB
+
+type Storage () =
+ let database =
+ let mapper = FSharpBsonMapper()
+ let connStr = "Filename=Todo.db;mode=Exclusive"
+ new LiteDatabase (connStr, mapper)
+ let todos = database.GetCollection<Todo> "todos"
+++LiteDb is a file-based database, and will create the file if it does not exist automatically.
+
This will create a database file Todo.db in the Server folder. The option mode=Exclusive is added for MacOS support (see this issue).
++See here for more information on connection string arguments.
+See the official docs for details on constructor arguments.
+
Replace the implementations of GetTodos and AddTodo as follows:
/// Retrieves all todo items.
+ member _.GetTodos () =
+ todos.FindAll () |> List.ofSeq
+
+ /// Tries to add a todo item to the collection.
+ member _.AddTodo (todo:Todo) =
+ if Todo.isValid todo.Description then
+ todos.Insert todo |> ignore
+ Ok ()
+ else
+ Error "Invalid todo"
+Modify the existing "priming" so that it first checks if there are any records in the database before inserting data:
+if storage.GetTodos() |> Seq.isEmpty then
+ storage.AddTodo(Todo.create "Create new SAFE project") |> ignore
+ storage.AddTodo(Todo.create "Write your app") |> ignore
+ storage.AddTodo(Todo.create "Ship it !!!") |> ignore
+Add the CLIMutable attribute to the Todo record in Shared.fs
[<CLIMutable>]
+type Todo =
+ { Id : Guid
+ Description : string }
+++This is required to allow LiteDB to hydrate (read) data into F# records.
+
1) In the "Connections" tab, click the "New Connection" button
+
2) Enter your connection details, leaving the "Database" dropdown set to <Default>.
USE master
+GO
+IF NOT EXISTS (
+ SELECT name
+ FROM sys.databases
+ WHERE name = N'SafeTodo'
+)
+ CREATE DATABASE [SafeTodo];
+GO
+IF SERVERPROPERTY('ProductVersion') > '12'
+ ALTER DATABASE [SafeTodo] SET QUERY_STORE=ON;
+GO
+NOTE: Alternatively, if you don't want to manually create the new database, you can install the "New Database" extension in Azure Data Studio which gives you a "New Database" option when right clicking the "Databases" folder.
+CREATE TABLE [dbo].[Todos]
+(
+ [Id] UNIQUEIDENTIFIER NOT NULL PRIMARY KEY,
+ [Description] NVARCHAR(500) NOT NULL,
+ [IsDone] BIT NOT NULL
+)
+At this point, you should have a SAFE Stack solution and a minimal "SafeTodo" SQL Server database with a "Todos" table. +Next, we will use Azure Data Studio with the "SQL Database Projects" extension to create a new SSDT (SQL Server Data Tools) .sqlproj that will live in our SAFE Stack .sln.
+1) Install the "SQL Database Projects" extension.
+2) Right click the SafeTodo database and choose "Create Project From Database" (this option is added by the "SQL Database Projects" extension)
+
3) Configure a path within your SAFE Stack solution folder and a project name and then click "Create". NOTE: If you choose to create an "ssdt" subfolder as I did, you will need to manually create this subfolder first.
+
4) You should now be able to view your SQL Project by clicking the "Projects" tab in Azure Data Studio.
+
5) Finally, right click the SafeTodoDB project and select "Build". This will create a .dacpac file which we will use in the next step.
+SQLProvider NuGet package to the Server projectSystem.Data.SqlClient NuGet package to the Server projectNext, we will wire up our type provider to generate database types based on the compiled .dacpac file.
+1) In the Server project, create a new file, Database.fs. (this should be above Server.fs).
module Database
+open FSharp.Data.Sql
+
+[<Literal>]
+let SsdtPath = __SOURCE_DIRECTORY__ + @"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac"
+
+// TO RELOAD SCHEMA: 1) uncomment the line below; 2) save; 3) recomment; 4) save again and wait.
+//DB.GetDataContext().``Design Time Commands``.ClearDatabaseSchemaCache
+
+type DB =
+ SqlDataProvider<
+ Common.DatabaseProviderTypes.MSSQLSERVER_SSDT,
+ SsdtPath = SsdtPath,
+ UseOptionTypes = true
+ >
+
+let createContext (connectionString: string) =
+ DB.GetDataContext(connectionString)
+2) Create TodoRepository.fs below Database.fs.
module TodoRepository
+open FSharp.Data.Sql
+open Database
+open Shared
+
+/// Get all todos that have not been marked as "done".
+let getTodos (db: DB.dataContext) =
+ query {
+ for todo in db.Dbo.Todos do
+ where (not todo.IsDone)
+ select
+ { Shared.Todo.Id = todo.Id
+ Shared.Todo.Description = todo.Description }
+ }
+ |> List.executeQueryAsync
+
+let addTodo (db: DB.dataContext) (todo: Shared.Todo) =
+ async {
+ let t = db.Dbo.Todos.Create()
+ t.Id <- todo.Id
+ t.Description <- todo.Description
+ t.IsDone <- false
+
+ do! db.SubmitUpdatesAsync()
+ }
+3) Create TodoController.fs below TodoRepository.fs.
module TodoController
+open Database
+open Shared
+
+let getTodos (db: DB.dataContext) =
+ TodoRepository.getTodos db
+
+let addTodo (db: DB.dataContext) (todo: Todo) =
+ async {
+ if Todo.isValid todo.Description then
+ do! TodoRepository.addTodo db todo
+ return todo
+ else
+ return failwith "Invalid todo"
+ }
+4) Finally, replace the stubbed todosApi implementation in Server.fs with our type provided implementation.
module Server
+
+open Fable.Remoting.Server
+open Fable.Remoting.Giraffe
+open Saturn
+open System
+open Shared
+open Microsoft.AspNetCore.Http
+
+let todosApi =
+ let db = Database.createContext @"Data Source=.\SQLEXPRESS;Initial Catalog=SafeTodo;Integrated Security=SSPI;"
+ { getTodos = fun () -> TodoController.getTodos db
+ addTodo = TodoController.addTodo db }
+
+let fableRemotingErrorHandler (ex: Exception) (ri: RouteInfo<HttpContext>) =
+ printfn "ERROR: %s" ex.Message
+ Propagate ex.Message
+
+let webApp =
+ Remoting.createApi()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.fromValue todosApi
+ |> Remoting.withErrorHandler fableRemotingErrorHandler
+ |> Remoting.buildHttpHandler
+
+let app =
+ application {
+ use_router webApp
+ memory_cache
+ use_static "public"
+ use_gzip
+ }
+
+run app
+From the VS Code terminal in the SafeTodo folder, launch the app (server and client):
+dotnet run
You should now be able to add todos.
+
When creating a Release build for deployment, it is important to note that SQLProvider SSDT expects that the .dacpac file will be copied to the deployed Server project bin folder.
+Here are the steps to accomplish this:
+1) Modify your Server.fsproj to include the .dacpac file with "CopyToOutputDirectory" to ensure that the .dacpac file will always exist in the Server project bin folder.
+<ItemGroup>
+ <None Include="..\{relative path to SSDT project}\ssdt\SafeTodo\bin\$(Configuration)\SafeTodoDB.dacpac" Link="SafeTodoDB.dacpac">
+ <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+ </None>
+
+ { other files... }
+</ItemGroup>
+2) In your Server.Database.fs file, you should also modify the SsdtPath binding so that it can build the project in either Debug or Release mode:
+[<Literal>]
+#if DEBUG
+ let SsdtPath = __SOURCE_DIRECTORY__ + @"/../../ssdt/SafeTodoDB/bin/Debug/SafeTodoDB.dacpac"
+#else
+ let SsdtPath = __SOURCE_DIRECTORY__ + @"/../../ssdt/SafeTodoDB/bin/Release/SafeTodoDB.dacpac"
+#endif
+NOTE: This assumes that your SSDT .sqlproj will be built in Release mode. (You can build it manually, or use a FAKE build script to handle this.)
+ + + + + + + + +Bulma is a free open-source UI framework based on flex-box that helps you create modern and responsive layouts. When it comes to using Bulma as your front-end library on a SAFE Stack web application, you have two options.
+By adding either of these to your SAFE project alongside the Bulma stylesheet or the Bulma NPM package, you can take full advantage of Bulma.
+open Feliz.Bulma
+
+Bulma.button.button [
+ str "Click me!"
+]
+open Fulma
+
+Button.button [] [
+ str "Click me!"
+]
+DaisyUI is a component library for Tailwind CSS.
+To use the library from within F# we will use Feliz.DaisyUI (Github).
Follow the instructions for how to add Tailwind CSS to your project
+Add daisyUI JS dependencies using NPM: npm i -D daisyui@latest
Add Feliz.DaisyUI .NET dependency...
+dotnet paket add Feliz.DaisyUIdotnet add package Feliz.DaisyUIUpdate the tailwind.config.js file's module.exports.plugins array; add require("daisyui")
module.exports = {
+ content: [
+ './src/Client/**/*.html',
+ './src/Client/**/*.fs',
+ ],
+ theme: {
+ extend: {},
+ },
+ plugins: [
+ require("daisyui"),
+ ],
+}
+Open the daisyUI namespace wherever you want to use it. +
open Feliz.DaisyUI
+Congratulations, now you can use daisyUI components!
+ Documentation can be found at https://dzoukr.github.io/Feliz.DaisyUI/
FontAwesome is the most popular icon set out there and will provide you with a handful of free icons as well as a multitude of premium icons. The standard SAFE template has out-of-the-box support for FontAwesome. You can just start using it in your Client code like so:
+open Feliz
+
+Html.i [ prop.className "fas fa-star" ]
+If you’re using the minimal template, there are a couple of things to do before you can start using FontAwesome. If you don't need the full features of Feliz we suggest using Fable.FontAwesome.Free.
Add Fable.FontAwesome.Free NuGet Package to the Client project.
++ ++
Open the index.html file and add the following line to the head element:
+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css">
+open Fable.FontAwesome
+
+Icon.icon [
+ Fa.i [ Fa.Solid.Star ] [ ]
+]
+Now you can use FontAwesome in your code
+ + + + + + + + +Written for SAFE template version 4.2.0
+If your application has multiple separate components, there is no need to have one big, complex model that manages all the state for all components. In this recipe we separate the information of the todo list out of the main Model, and give the todo list application its own route. We also add a "Page not found" page.
Install Feliz.Router in the client project
+dotnet paket add Feliz.Router -p Client -V 3.8
+Feliz.Router versions
+At the time of writing, the current version of the SAFE template (4.2.0) does not work well with the latest version of Feliz.Router (4.0). +To work around this, we install Feliz.Router 3.8, the latest version that works with SAFE template version 4.2.0.
+If you are working with a newer version of the SAFE template, it might be worth trying to install the newest version of Feliz.Router. +To see the installed version of the SAFE template, run in the command line:
+dotnet new --list
+To include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router
+Move the following functions and types to a new TodoList Module in a file TodoList.fs:
also open Shared, Fable.Remoting.Client, Elmish Feliz and Feliz.Bulma
module TodoList
+
+open Shared
+open Fable.Remoting.Client
+open Elmish
+open Feliz
+open Feliz.Bulma
+
+
+type Model = { Todos: Todo list; Input: string }
+
+type Msg =
+ | GotTodos of Todo list
+ | SetInput of string
+ | AddTodo
+ | AddedTodo of Todo
+
+let todosApi =
+ Remoting.createApi ()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.buildProxy<ITodosApi>
+
+let init () : Model * Cmd<Msg> =
+ let model = { Todos = []; Input = "" }
+ let cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos
+
+ model, cmd
+
+let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+ | SetInput value -> { model with Input = value }, Cmd.none
+ | AddTodo ->
+ let todo = Todo.create model.Input
+
+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+
+ { model with Input = "" }, cmd
+ | AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none
+
+let view (model: Model) (dispatch: Msg -> unit) =
+ Bulma.box [
+ Bulma.content [
+ Html.ol [
+ for todo in model.Todos do
+ Html.li [ prop.text todo.Description ]
+ ]
+ ]
+ Bulma.field.div [
+ field.isGrouped
+ prop.children [
+ Bulma.control.p [
+ control.isExpanded
+ prop.children [
+ Bulma.input.text [
+ prop.value model.Input
+ prop.placeholder "What needs to be done?"
+ prop.onChange (fun x -> SetInput x |> dispatch)
+ ]
+ ]
+ ]
+ Bulma.control.p [
+ Bulma.button.a [
+ color.isPrimary
+ prop.disabled (Todo.isValid model.Input |> not)
+ prop.onClick (fun _ -> dispatch AddTodo)
+ prop.text "Add"
+ ]
+ ]
+ ]
+ ]
+ ]
+Create a new Model in the Index module, to keep track of the open page
type Page =
+ | TodoList of TodoList.Model
+ | NotFound
+
+type Model = { CurrentPage: Page }
+Add a Msg type with a case of TodoList.Msg
type Msg =
+ | TodoListMsg of TodoList.Msg
+Create an update function (we moved the original one to TodoList). Handle the TodoListMsg by updating the TodoList Model. Wrap the command returned by the update of the todo list in a TodoListMsg before returning it. We expand this function later with other cases that deal with navigation.
let update (message: Msg) (model: Model) : Model * Cmd<Msg> =
+ match model.CurrentPage, message with
+ | TodoList todoList, TodoListMsg todoListMessage ->
+ let newTodoListModel, newCommand = TodoList.update todoListMessage todoList
+ let model = { model with CurrentPage = TodoList newTodoListModel }
+
+ model, newCommand |> Cmd.map TodoListMsg
+Create a function initFromUrl; initialize the TodoList app when given the URL of the todo list app. Also return the command that TodoList's init may return, wrapped in a TodoListMsg
let initFromUrl url =
+ match url with
+ | [ "todo" ] ->
+ let todoListModel, todoListMsg = TodoList.init ()
+ let model = { CurrentPage = TodoList todoListModel }
+
+ model, todoListMsg |> Cmd.map TodoListMsg
+Add a wildcard, so any URLs that are not registered display the "not found" page
+let initFromUrl url =
+ match url with
+ ...
+ | _ -> { CurrentPage = NotFound }, Cmd.none
+ let initFromUrl url =
+ match url with
+ ...
++ | _ -> { CurrentPage = NotFound }, Cmd.none
+Add an init function to Index; return the current page based on Router.currentUrl
let init () : Model * Cmd<Msg> =
+ Router.currentUrl ()
+ |> initFromUrl
+Add an UrlChanged case of string list to the Msg type
type Msg =
+ ...
+ | UrlChanged of string list
+ type Msg =
+ ...
++ | UrlChanged of string list
+Handle the case in the update function by calling initFromUrl
let update (message: Msg) (model: Model) : Model * Cmd<Msg> =
+ ...
+ match model.CurrentPage, message with
+ | _, UrlChanged url -> initFromUrl url
+ let update (message: Msg) (model: Model) : Model * Cmd<Msg> =
+ ...
++ match model.CurrentPage, message with
++ | _, UrlChanged url -> initFromUrl url
+Complete the pattern match in the update function, adding a case with a wildcard for both message and model. Return the model, and no command
let update (message: Msg) (model: Model) : Model * Cmd<Msg> =
+ ...
+ | _, _ -> model, Cmd.none
+ let update (message: Msg) (model: Model) : Model * Cmd<Msg> =
+ ...
++ | _, _ -> model, Cmd.none
+Add a function containerBox to the Index module. If the CurrentPage is of TodoList, render the todo list using TodoList.view; in order to dispatch a TodoList.Msg, it needs to be wrapped in a TodoListMsg.
For the NotFound page, return a "Page not found" box
let containerBox model dispatch =
+ match model.CurrentPage with
+ | TodoList todoModel -> TodoList.view todoModel (TodoListMsg >> dispatch)
+ | NotFound -> Bulma.box "Page not found"
+Wrap the content of the view function in a router.children property of a React.router. Also add an onUrlChanged property, that dispatches the 'UrlChanged' message.
let view (model: Model) (dispatch: Msg -> unit) =
+ React.router [
+ router.onUrlChanged (UrlChanged >> dispatch)
+ router.children [
+ Bulma.hero [
+ ...
+ ]
+ ]
+ ]
+ let view (model: Model) (dispatch: Msg -> unit) =
++ React.router [
++ router.onUrlChanged (UrlChanged >> dispatch)
++ router.children [
+ Bulma.hero [
+ ...
+ ]
++ ]
++ ]
+The routing should work now. Try navigating to localhost:8080; you should see a page with "Page not Found". If you go to localhost:8080/#/todo, you should see the todo app.
+# sign
+You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. +There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
+Written for SAFE template version 4.2.0
+When building larger apps, you probably want different pages to be accessible through different URLs. In this recipe, we show you how to add routes to different pages to an application, including adding a "page not found" page that is displayed when an unknown URL is entered.
+In this recipe we use the simplest approach to storing states for multiple pages, by creating a single state for the full app. A potential benefit of this approach is that the state of a page is not lost when navigating away from it. You will see how that works at the end of the recipe.
+Install Feliz.Router in the client project
+dotnet paket add Feliz.Router -p Client -V 3.8
+Feliz.Router versions
+At the time of writing, the current version of the SAFE template (4.2.0) does not work well with the latest version of Feliz.Router (4.0). +To work around this, we install Feliz.Router 3.8, the latest version that works with SAFE template version 4.2.0.
+If you are working with a newer version of the SAFE template, it might be worth trying to install the newest version of Feliz.Router. +To see the installed version of the SAFE template, run in the command line:
+dotnet new --list
+To include the router in the Client, open Feliz.Router at the top of Index.fs
open Feliz.Router
+Add the current page to the model of the client, using a new Page type
type Page =
+ | TodoList
+ | NotFound
+
+type Model =
+ { CurrentPage: Page
+ Todos: Todo list
+ Input: string }
++ type Page =
++ | TodoList
++ | NotFound
++
+- type Model = { Todos: Todo list; Input: string }
++ type Model =
++ { CurrentPage: Page
++ Todos: Todo list
++ Input: string }
+Create a function to parse a URL to a page, including a wildcard for unmapped pages
+let parseUrl url =
+ match url with
+ | ["todo"] -> Page.TodoList
+ | _ -> Page.NotFound
+On initialization, set the current page
+let init () : Model * Cmd<Msg> =
+ let page = Router.currentUrl () |> parseUrl
+
+ let model =
+ { CurrentPage = page
+ Todos = []
+ Input = "" }
+ ...
+ model, cmd
+ let init () : Model * Cmd<Msg> =
++ let page = Router.currentUrl () |> parseUrl
++
+- let model = { Todos = []; Input = "" }
++ let model =
++ { CurrentPage = page
++ Todos = []
++ Input = "" }
+ ...
+ model, cmd
+Add an action to handle navigation.
+To the Msg type, add a PageChanged case of Page
type Msg =
+ ...
+ | PageChanged of Page
+ type Msg =
+ ...
++ | PageChanged of Page
+Add the PageChanged update action
let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ ...
+ | PageChanged page -> { model with CurrentPage = page }, Cmd.none
+ let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ ...
++ | PageChanged page -> { model with CurrentPage = page }, Cmd.none
+Rename the view function to todoView
let todoView (model: Model) (dispatch: Msg -> unit) =
+ Bulma.hero [
+ ...
+ ]
+- let view (model: Model) (dispatch: Msg -> unit) =
++ let todoView (model: Model) (dispatch: Msg -> unit) =
+ Bulma.hero [
+ ...
+ ]
+Add a new view function, that returns the appropriate page
+let view (model: Model) (dispatch: Msg -> unit) =
+ match model.CurrentPage with
+ | TodoList -> todoView model dispatch
+ | NotFound -> Bulma.box "Page not found"
+Adding UI elements to every page of the website
+In this recipe, we moved all the page content to the todoView, but you don't have to. You can add UI you want to display on every page of the application to the view function.
Add the React.Router element as the outermost element of the view. Dispatch the PageChanged event on onUrlChanged
let view (model: Model) (dispatch: Msg -> unit) =
+ React.router [
+ router.onUrlChanged (parseUrl >> PageChanged >> dispatch)
+ router.children [
+ match model.CurrentPage with
+ ...
+ ]
+ ]
+ let view (model: Model) (dispatch: Msg -> unit) =
++ React.router [
++ router.onUrlChanged (parseUrl >> PageChanged >> dispatch)
+ router.children [
+ match model.CurrentPage with
+ ...
+ ]
+ ]
+The routing should work now. Try navigating to localhost:8080; you should see a page with "Page not Found". If you go to localhost:8080/#/todo, you should see the todo app.
+To see how the state is maintained even when navigating away from the page, type something in the text box and move away from the page by entering another path in the address bar. Then go back to the todo page. The entered text is still there.
+# sign
+You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. +There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
+Now that you have set up the routing, adding more pages is simple: add a new case to the Page type; add a route for this page in the parseUrl function; add a function that takes a model and dispatcher to generate your new page, and add a new case to the pattern match inside the view function to display the new case.
If you wish to use your own CSS or SASS stylesheets with SAFE apps, you can embed either through webpack. The template already includes all required NPM packages you may need, so you will only need to configure webpack to reference your stylesheet and include in the outputs.
+First, create a CSS file in the src/Client folder of your solution e.g style.css.
++The same approach can be taken for
+.scssfiles.
Inside the webpack.config.js file, add the following variable to the CONFIG object, which points to the style file you created previously.
+
cssEntry: './src/Client/style.css',
+Find the entry field in the module.exports object at the bottom of the file, and replace it with the following:
+
entry: isProduction ? {
+ app: [resolve(CONFIG.fsharpEntry), resolve(CONFIG.cssEntry)]
+} : {
+ app: resolve(CONFIG.fsharpEntry),
+ style: resolve(CONFIG.cssEntry)
+},
+This combines the css and F# outputs into a single bundle for production, and separately for dev.
+Find the entry field in the module.exports object at the bottom of the file, and replace it with the following:
+
entry: {
+ app: [
+ resolve('./src/Client/Client.fsproj'),
+ resolve('./src/Client/style.css')
+ ]
+},
+You can now style your app by writing to the style.css file.
Tailwind is a utility-first CSS framework packed that can be composed to build any design, directly in your markup.
+Add a stylesheet to the project
+Install the required npm packages +
npm install -D tailwindcss postcss autoprefixer postcss-loader
+tailwind.config.js
+ npx tailwindcss init
+Amend the content array in the tailwind.config.js as follows
+
module.exports = {
+ content: [
+ './src/Client/**/*.html',
+ './src/Client/**/*.fs',
+ ],
+ theme: {
+ extend: {},
+ },
+ plugins: [],
+}
+Create a postcss.config.js with the following
+
module.exports = {
+ plugins: {
+ tailwindcss: {},
+ autoprefixer: {},
+ }
+}
+Add the Tailwind layers to your style.css
+
@tailwind base;
+@tailwind components;
+@tailwind utilities;
+Find the module.rules field in the webpack.config.js and in the css files rule’s use field add postcss-loader
+
{
+ test: /\.(sass|scss|css)$/,
+ use: [
+ isProduction
+ ? MiniCssExtractPlugin.loader
+ : 'style-loader',
+ 'css-loader',
+ {
+ loader: 'sass-loader',
+ options: { implementation: require('sass') }
+ },
+ 'postcss-loader'
+ ],
+},
+In the src/Client folder find the code in Index.fs to show the list of todos and add a Tailwind text colour class(text-red-200)
+
for todo in model.Todos do
+ Html.li [
+ prop.classes [ "text-red-200" ]
+ prop.text todo.Description
+ ]
+You should see some nice red todos proving that Tailwind is now in your project
+ + + + + + + + +Though the SAFE template default for referencing a stylesheet is to use a CDN, it’s quite reasonable to want to use an NPM package instead. One common case is that it enables you to further customise Bulma themes by overriding Sass variables.
+Find the following line in src/Client/index.html and delete it before moving on:
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css">
+Go ahead and add the Bulma NPM package to your project.
++ ++
There are two ways for loading the stylesheets:
+A quick and easy way to reference this NPM package in an F# file is to insert the following couple of lines:
+open Fable.Core.JsInterop
+importAll "bulma/bulma.sass"
+++You can use this approach for any NPM package.
+
@import "~bulma/bulma.sass"
+Remove / replace all the references to Bulma in fsharp code
+Remove any stylesheet links to Bulma which may exist in the index.html page, or in other html pages.
Optional: If using Paket ensure Fable.Core is set to a specified version.
In paket.dependencies, make sure there is a line like so: Fable.Core ~> 3
Warning
+SAFE is not yet compatible with newer versions of Fable.Core.
+In the past, the version was not pinned so it was possible to accidentally upgrade to an incompatible version.
Info
+To avoid specifying a version when adding a dependency - if it is not already pinned to a specific version - you can use the --keep-major flag to make the upgrade more conservative.
Remove Fulma and Feliz.Bulma
Paket: +
dotnet paket remove Fulma
+dotnet paket remove Feliz.Bulma
+NuGet: +
cd src/Client
+dotnet remove package Fulma
+dotnet remove package Feliz.Bulma
+Written for SAFE template version 4.2.0
+UseElmish is a powerful package that allows you to write standalone components using Elmish. A component built around the UseElmish hook has its own view, state and update function.
In this recipe we add routing to a safe app, and implement the todo list page using the UseElmish hook.
Pin Fable.Core to V3
+At the time of writing, the published version of the SAFE template does not have the version of Fable.Core pinned; this can create problems when installing dependencies.
If you are using version v.4.2.0 of the template, pin Fable.Core to version 3 in paket.depedencies at the root of the project
...
+-nuget Fable.Core
++nuget Fable.Core ~> 3
+...
+Install Feliz.Router in the Client project
+dotnet paket add Feliz.Router -p Client -V 3.8
+Feliz.Router versions
+At the time of writing, the current version of the SAFE template (4.2.0) does not work well with the latest version of Feliz.Router (4.0). +To work around this, we install Feliz.Router 3.8, the latest version that works with SAFE template version 4.2.0.
+If you are working with a newer version of the SAFE template, it might be worth trying to install the newest version of Feliz.Router. +To see the installed version of the SAFE template, run in the command line:
+dotnet new --list
+Install Feliz.UseElmish in the Client project
+dotnet paket add Feliz.UseElmish -p client
+Open the router in the client project
+open Feliz.Router
+Create a new Module TodoList in the client project. Move the following functions and types to the TodoList Module:
Also open Shared, Fable.Remoting.Client, Elmish, Feliz.Bulma and Feliz.
module TodoList
+
+open Shared
+open Fable.Remoting.Client
+open Elmish
+
+open Feliz.Bulma
+open Feliz
+
+type Model = { Todos: Todo list; Input: string }
+
+type Msg =
+ | GotTodos of Todo list
+ | SetInput of string
+ | AddTodo
+ | AddedTodo of Todo
+
+let todosApi =
+ Remoting.createApi ()
+ |> Remoting.withRouteBuilder Route.builder
+ |> Remoting.buildProxy<ITodosApi>
+
+let init () : Model * Cmd<Msg> =
+ let model = { Todos = []; Input = "" }
+ let cmd = Cmd.OfAsync.perform todosApi.getTodos () GotTodos
+
+ model, cmd
+
+let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ | GotTodos todos -> { model with Todos = todos }, Cmd.none
+ | SetInput value -> { model with Input = value }, Cmd.none
+ | AddTodo ->
+ let todo = Todo.create model.Input
+
+ let cmd = Cmd.OfAsync.perform todosApi.addTodo todo AddedTodo
+
+ { model with Input = "" }, cmd
+ | AddedTodo todo -> { model with Todos = model.Todos @ [ todo ] }, Cmd.none
+
+let containerBox (model: Model) (dispatch: Msg -> unit) =
+ Bulma.box [
+ Bulma.content [
+ Html.ol [
+ for todo in model.Todos do
+ Html.li [ prop.text todo.Description ]
+ ]
+ ]
+ Bulma.field.div [
+ field.isGrouped
+ prop.children [
+ Bulma.control.p [
+ control.isExpanded
+ prop.children [
+ Bulma.input.text [
+ prop.value model.Input
+ prop.placeholder "What needs to be done?"
+ prop.onChange (fun x -> SetInput x |> dispatch)
+ ]
+ ]
+ ]
+ Bulma.control.p [
+ Bulma.button.a [
+ color.isPrimary
+ prop.disabled (Todo.isValid model.Input |> not)
+ prop.onClick (fun _ -> dispatch AddTodo)
+ prop.text "Add"
+ ]
+ ]
+ ]
+ ]
+ ]
+open Feliz.UseElmish in the TodoList Module
+open Feliz.UseElmish
+...
+In the todoList module, rename containerBox to view.
+On the first line, call React.useElmish passing it the init and update functions. Bind the output to model and dispatch
let view (model: Model) (dispatch: Msg -> unit) =
+ let model, dispatch = React.useElmish(init, update, [||])
+ ...
+-let containerBox (model: Model) (dispatch: Msg -> unit) =
++let view (model: Model) (dispatch: Msg -> unit) =
++ let model, dispatch = React.useElmish(init, update, [||])
+ ...
+Replace the arguments of the function with unit, and add the ReactComponent attribute to it
[<ReactComponent>]
+let view () =
+ ...
++ [<ReactComponent>]
+- let view (model: Model) (dispatch: Msg -> unit) =
++ let view () =
+ ...
+In the Index module, create a model that holds the current page
type Page =
+ | TodoList
+ | NotFound
+
+type Model =
+ { CurrentPage: Page }
+Create a function that initializes the app based on an url
+let initFromUrl url =
+ match url with
+ | [ "todo" ] ->
+ let model = { CurrentPage = TodoList }
+
+ model, Cmd.none
+ | _ ->
+ let model = { CurrentPage = NotFound }
+
+ model, Cmd.none
+Create a new init function, that fetches the current url, and calls initFromUrl.
let init () =
+ Router.currentUrl ()
+ |> initFromUrl
+Add a Msg type, with an PageChanged case
type Msg =
+ | PageChanged of string list
+update function, that reinitializes the app based on an URL
+let update (msg: Msg) (model: Model) : Model * Cmd<Msg> =
+ match msg with
+ | PageChanged url ->
+ initFromUrl url
+Add a containerBox function to the Index module, that returns the appropriate page content
let containerBox (model: Model) (dispatch: Msg -> unit) =
+ match model.CurrentPage with
+ | NotFound -> Bulma.box "Page not found"
+ | TodoList -> TodoList.view ()
+Wrap the content of the view method in a React.Router element's router.children property, and add a router.onUrlChanged property to dispatch the urlChanged message
let view (model: Model) (dispatch: Msg -> unit) =
+ React.router [
+ router.onUrlChanged ( PageChanged>>dispatch )
+ router.children [
+ Bulma.hero [
+ ...
+ ]
+ ]
+ ]
+let view (model: Model) (dispatch: Msg -> unit) =
++ React.router [
++ router.onUrlChanged ( PageChanged>>dispatch )
++ router.children [
+ Bulma.hero [
+ ...
+ ]
++ ]
++ ]
+The routing should work now. Try navigating to localhost:8080; you should see a page with "Page not Found". If you go to localhost:8080/#/todo, you should see the todo app.
+# sign
+You might be surprised to see the hash sign as part of the URL. It enables React to react to URL changes without a full page refresh. +There are ways to omit this, but getting this to work properly is outside of the scope of this recipe.
+Bulmaswatch is a great website for finding free Bulma themes. However, once you decide on what theme to use, visit this website to get a CDN link to its CSS file. For this recipe, I will use the Nuclear theme.
+The standard template uses a CDN (Content Delivery Network) link to reference the Bulma theme that it uses. Changing the theme then, is as simple as changing this link. Since the class names Bulma uses to style HTML elements remain the same, we don’t need to change anything else.
+In your index.html, find the line that references the Bulma stylesheet that’s used in the template through a CDN link. It will look like the following:
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css">
+Go ahead and replace this link with the link to the theme that you want to use, which in my case is Nuclear: +
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bulmaswatch/0.8.1/nuclear/bulmaswatch.min.css">
+In your index.html, add the following line anywhere between the opening and closing head tags:
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css">
+Read this recipe for the rest of the instructions.
+And that’s it. You should now see your app styled in accordance with the Bulma theme you’ve just switched to.
+ + + + + + + + +