zaid-ajaj/safe.simplified

A lightweight alternative template of SAFE for happy cross-IDE full-stack F# development

Simplified SAFE Stack

A lightweight alternative template to the full-fledged official SAFE Template. Lowers the entry barrier by choosing the simplest possible opinionated defaults:

• Nuget for package management
• FAKE build script as a console project (see ./build)
• Saturn as server web framework
• Fable.Remoting for client-server communications
• Feliz as the React DSL on the front-end
• Expecto for server unit-tests project
• Fable.Mocha for client unit-tests project (runs in Node.js when on CI servers or live during development)
• Serilog for logging server-side stuff
• Scalable architecture by modelling logical server-side components following Fable.Remoting protocols
• F# Analyzers support
• Simple application variable configuration (see below sections)

Getting Started

To start using this template, simply clone this repository or use it as template via Github UI and you are good to go.

You need to have installed:

• .NET Core SDK 3.1+
• Node.js 12.0+

You can use the editor of your choice to work with the repository. VS Code is recommended with the Ionide extension for F# development but the template will also work just fine with Visual Studio, Rider or Visual Studio for Mac if you prefer to work with any of those.

Running The Application

To work with and develop the application, you need to both the server and the client project running at the same time. The server application is in the server directory and the client is in client directory. To run them both, simply open two shell tabs, each for either applications then:

  Shell tab c:\project\simplified-safe   Shell tab c:\project\simplified-safe
 -------------------------------------- --------------------------------------
  > cd server                            > cd client
  > dotnet restore                       > npm install
  > dotnet run                           > npm start

As shown here below

The server web application starts listening for requests at http://localhost:5000 where as the client application will be hosted at http://localhost:8080 during developments. All web requests made from the front-end are automatically proxied to the backend at http://localhost:5000. In production, there will no proxy because the front-end application will be served from the backend itself.

That is unless you are hosting the backend serverless and would like to host the front-end project separately.

Available Build Targets

You can easily run the build targets as follows:

• ./build.sh {Target} on Linux, Mac or simulated bash on Windows
• build {Target} on Windows
• Hitting F5 where Build.fsproj is the startup project in Visual Studio or Rider

There are a bunch of built-in targets that you can run:

• Server builds the server in Release mode
• Client builds the client in production mode
• Clean cleans up cached assets from all the projects
• ServerTests runs the server unit-tests project
• ClientTests runs the client unit-tests project by compiling the project first and running via Mocha in node.js
• LiveClientTests runs a standalone web application at http://localhost:8085 that shows test results from the unit tests and recompiles whenever the tests change.
• HeadlessBrowserTests builds the test project as web application and spins up a headless browser to run the tests and report results
• Pack builds and packs both server and client into the {solutionRoot}/dist directory after running unit tests of both projects. You can run the result application using dotnet Server.dll in the dist directory.
• PackNoTests builds and packs both server and client projects into {solutionRoot}/dist without running tests.
• InstallAnalyzers installs F# code analyzers. You can configure which analyzers to install from the build target itself.

Configuring application variables: Server

The server web application picks up the environment variables by default from the host machine and makes them available from an injected IConfiguration interface. However, it adds a nice feature on top which allows to add more application-specific local variables by adding a JSON file called config.json inside your server directory:

{
  "DATABASE_CONNECTIONSTRING": "ConnectionString",
  "APP_NAME": "SimplifiedSafe",
  "VERSION": "0.1.0-alpha"
}

Just including the file will allow the variables to be picked up automatically and will also be made available through the IConfiguration interface.

Configuring application variables: Client

Even the client can use build variables. Using the Config.variable : string -> string function, you can have access to the environment variables that were used when the application was compiled. Webpack will pick them up automatically by default. To use local variables other than the environment variables, you add a file called .env into the client directory. This file is a dotenv variables file and has the following format:

KEY1=VALUE1
KEY2=VALUE2
WELCOME_MESSAGE=Welcome to full-stack F#

Then from your Fable application, you can use the variables like this:

Config.variable "WELCOME_MESSAGE" // returns "Welcome to full-stack F#"

Since this file can contain variables that might contain sensitive data. It is git-ignored by default.

Injecting ASP.NET Core Services

Since we are using Fable.Remoting in the template, make sure to check out the Functional Dependency Injection article from the documentation of Fable.Remoting that goes through the required steps of injecting services into the functions of Fable.Remoting APIs

F# Analyzers support

When developing the application using Ionide and VS Code, you can make use of F# analyzers that are built to detect certain types of specific pieces of code. By default the template doesn't include any analyzers but it is easy to add and install them using the InstallAnalyzers build target defined in build/Program.fs as follows:

Target.create "InstallAnalyzers" <| fun _ ->
    let analyzersPath = path [ solutionRoot; "analyzers" ]
    Analyzers.install analyzersPath [
        // Add analyzer entries to download
        // example { Name = "NpgsqlFSharpAnalyzer"; Version = "3.2.0" }
    ]

To install for example the NpgsqlFSharpAnalyzer package, simply uncomment the entry to make the code look like this:

Target.create "InstallAnalyzers" <| fun _ ->
    let analyzersPath = path [ solutionRoot; "analyzers" ]
    Analyzers.install analyzersPath [
        // Add analyzer entries to download
        { Name = "NpgsqlFSharpAnalyzer"; Version = "3.2.0" }
    ]

Then run the build target InstallAnalyzers again where it will delete the contents of analyzers directory and re-install all configured analyzers from scratch. Restart VS Code to allow Ionide to reload the installed analyzers. If you already have analyzers installed and adding new ones, you might need to do that from the terminal outside of VS Code because Ionide will lock the files in the analyzers path preventing the target from deleting the old analyzers.

IIS Support

The bundled application you get by running the Pack build target can be used directly as an application inside of IIS. Publishing on IIS requires that you make a separate Application Pool per .NET Core application with selected .NET CLR Version = No Managed Code. Then creating a new IIS Application which into the newly created Application Pool and setting the Physical Path of that Application to be the dist directory.

safe.simplified's Issues

How to generate-load-scripts

When using paket, you can use the generate-load-scripts option to generate script files that will load all dependencies. As the current framework relies on nuget directly, how can this be achieved without paket?

Invalid Hook Call. Hooks can only be called inside of the body of a function component.

I have upgraded React to 17.0.2 and Feliz to 1.40.1
When using React hooks, I get this error in my console and the app does not render. This is my code:

[<ReactComponent>]
let Component () =
  let state, setState = React.useState ""

  Html.h1 state


ReactDOM.render (Component(), document.getElementById "feliz-app")

It works with a project started with dotnet new feliz -n AwesomeApp. I'm guessing the difference is with the fable compiler version used. This template uses v2, while the Feliz-specific template uses v3.

This is the js output for the above f# code in the template:

function Component() {
  var patternInput = Object(_fable_Feliz_1_40_1_React_fs__WEBPACK_IMPORTED_MODULE_0__["Feliz$002EReact$$React$002EuseState$002EStatic$$1505"])("");
  var state = patternInput[0];
  var setState = patternInput[1];
  return Object(_fable_Feliz_1_40_1_Interop_fs__WEBPACK_IMPORTED_MODULE_1__["Interop$$$reactElement"])("h1", {
    children: [state]
  });
}

Object(react_dom__WEBPACK_IMPORTED_MODULE_1__["render"])(Object(_App_fs__WEBPACK_IMPORTED_MODULE_0__["Component"])(), document.getElementById("feliz-app"));//# sourceURL=[module]

While the js output using the Feliz template is:

function Component() {
  _s();

  var patternInput = Object(_fable_Feliz_1_40_1_React_fs_js__WEBPACK_IMPORTED_MODULE_0__["useFeliz_React__React_useState_Static_1505"])("");
  var state = patternInput[0];
  var setState = patternInput[1];
  return /*#__PURE__*/Object(react__WEBPACK_IMPORTED_MODULE_1__["createElement"])("h1", {
    children: [state]
  });
}

Object(react_dom__WEBPACK_IMPORTED_MODULE_2__["render"])( /*#__PURE__*/Object(react__WEBPACK_IMPORTED_MODULE_1__["createElement"])(Component, null), document.getElementById("feliz-app"));

My guess is that the problem is with the createElement call not being invoked in the first code sample.

Old version of Debugger may break build

SAFE.Simplified/client/src/Client.fsproj

Line 15 in 714f061

<PackageReference Include="Fable.Elmish.Debugger" Version="3.0.3" />

Use 3.2.0, see thoth-org/Thoth.Json#45 for details.

Server side recompiles not working

When changing server side code and saving recompile is not working with a running development server because the Server.exe is locked. I think with the original SAFE STACK you can do this?

Just need you to contact me.

Hello Zaid, great work. Again!

But could you call me by cellphone, I would like to discuss some things would you.

Sorry for this intrusion, but I haven't got an alternative way to reach you. P.S. My phone is in my mail signature from work.

How to run it with .NET 5?

Thank you for this awesome template!

Have you tried it with .NET 5 yet? If so, how do I upgrade it to .NET 5? I tried changing the target framework, but some build error because of missing sdk:

/home/tomas/git/mastoj/simpleshopper/server/Server.fsproj : error MSB4236: The SDK 'Microsoft.NET.Sdk.Web' specified could not be found.

Anything more that I need to change? I did try to create an empty webapi to compare the fsproj file, but couldn't spot any major differences.

Issue when loading localConfig in Env.fs

Hi,

When I was trying to load a localConfig file I encountered an issue whereby it wasn't adding any key/value pairs. I've got a fix in my local branch so happy to do a PR (#2), I just wanted to make sure the way it is now isn't the intended behaviour?

SAFE.Simplified/server/Env.fs

Line 64 in 098ce4b

if (variables.ContainsKey(property.Name)) then

SAFE.Simplified/server/Env.fs

Line 77 in 098ce4b

if (variables.ContainsKey(property.Name)) then

package-lock.json is out of date but can be refreshed to correct issue

package-lock.json references node-forge:0.9.0 which has a severe security vulnerability.

The problem is resolved by invoking npm install --package-lock

NuGet Template

Hi Zaid!

I just dusted off the templatized version of SAFE.Simplified that I started on a few years ago and got it back up and running with a few updates according to my preferences.

I remember that you were not a fan of templates, but it would be useful for me (and possibly others) to have this template available on NuGet for convenience. Would you mind if I uploaded it from my fork? Obviously I would alter the name to make it clear that it's a forked version.

Build project misconfigured

I think the build project is misconfigured here. It is referring to clientTests as one of the directories and I think it means client\tests. Next, if you were to use the default ./build.sh you will find it errors out looking for Default, which does not exist in the targets. Not sure which one is recommended as default.

dotnet new template

I have mostly finished creating a dotnet new template for this.
The default should leave it pretty much exactly the way you have it now, but it also allows for renaming the shared, server and client projects, project refs, build script strings, etc. And it also allows adding an optional root namespace.
That may go against the idea of keeping it simple, so let me know if you are interested in this.