Add lots of recipes

[isaacabraham]

This is a tentative list of "recipes" or "how-to" guides that the docs should offer. Hopefully each should be relatively small and quick to author!

Upgrading from SAFE v1

• [x] How do I upgrade a SAFE v1 project to SAFE v2?

Hosting

• [x] How do I host inside Docker?
• [x] How do I host inside Azure App Service?
• [ ] How do I host inside Amazon Web Service?
• [ ] How do I host inside IIS?
• [ ] How do I host inside Google Cloud Platform App Engine?

Build

• [x] How should I combine the build outputs from client and server?
• [x] How do I add a build script to the project e.g. FAKE?
• [x] How do I remove the use of FAKE?

Package Management

• [x] How do I add a nuget package to the server?
• [x] How do I add a nuget package to the client?
• [x] How do I add an NPM package to the client?
• [x] How do I ensure NPM and Nuget packages stay in sync?
• [x] How do I migrate to Paket?
• [x] How do I migrate to Nuget?
• [x] How do I migrate to Yarn instead of NPM?

Client / server communication

• [x] How do I add support for Fable Remoting?
• [ ] How do I add support for SignalR (https://shmew.github.io/Fable.SignalR)?
• [ ] How do I add support for GraphQL?
• [x] How do I add a POST endpoint?
• [x] How do I add a GET endpoint?
• [x] How do I handle server errors on the client?
• [x] How do I share types between client and server?
• [x] How do I share code between client and server?
• [ ] How do I add Server to Client communication with WebSockets?
• [ ] What are my serialization options for HTTP communication?
• [ ] How do I enable Server Side Rendering?
• [ ] How do I configure Thoth to work with Decimals and other types?
• [ ] How do I serve a file from the back-end?
• [x] How do I upload a file from the client?
• [ ] How do I show server errors on the client?

Developing and Testing

• [x] How do I test my client application?
• [x] How do I test my server application?
• [x] How do I use hot reloading?
• [x] How do I debug my SAFE apps?
• [ ] How do I add support for the remote container extension in VS Code?
• [ ] How do I do logging in SAFE apps?

Fable

• [x] How do I reference an NPM module?
• [x] How do I use a third-party React package?

UI

• [ ] What is the difference between Fable React and Feliz?
• [x] How do I add Bulma support?
• [x] How do I use different Bulma styles?
• [x] How do I add use raw CSS styles?
• [x] How do I add support for Feliz?
• [x] How do I add support for font awesome?
• [x] How do I use SASS with SAFE apps?
• [x] How do I migrate from a CDN stylesheet to an NPM package?

Server

• [x] How do I use Giraffe instead of Saturn?

Other Platforms

• [ ] How do I share code between Web and Console applications?

WebPack

• [x] How do I add support for older browsers?

Other

• [x] How do I add application configuration?
• [x] How do I add environment specific configuration?

Security

• [ ] How do I add oauth authentication to the Server?
• [ ] How do I perform a standard login flow across my application?
• [ ] How do I do authentication and role-based authorization using Azure AD?

[theimowski]

Here's a list of items I'd add / change. Most of these are due to us removing features in v2 compared to v1.

building and hosting

• How do I handle application versioning - As we remove support for RELEASE_NOTES and Version.fs with FAKE support for parsing, we need to explain how this can be done • How do I add / remove FAKE support? - similar to Paket, one might want this small change when starting with full / minimal template • How do I host inside Heroku? • Google cloud platform - separate section for App Engine and Kubernetes as @mastoj did those two awesome contributions

package management

• How do I use Yarn instead of NPM? • How do I add / remove paket support? - we should document both ways

client / server communication

• "How do I add support for Fable" - what do you mean?

dev & test

• How do I add support for remote container extension in VS Code?

fable

• How do I add support for fable reaction ?

ui

• How do I start with a Bulma template? - here we can create sample repos with all v1 layout options

---

Two more sections I'd add:

server

• How do I use Giraffe instead of Saturn? - we have users that want bare Giraffe

other platforms

• How do I share code between Web and Console application? - I can add that section given it's my actual commercial use case. In future we could expand it to Mobile (Xamarin) / Electron / etc.

[isaacabraham]

All added :-)

[theimowski]

I've moved a couple items in the list under proper group

[Ulriksen]

I'd very much love to see one on how to authenticate with Azure AD, preferably that the user is member of a specific group.

[rastreus]

I'd like to see a recipe on WebSockets and a recipe on integrating Akka.NET / Akkling.

• [ ] How do I add Server to Client communication with WebSockets?

This could possibly re-use the WebSockets with SAFE Stack blog post and the corresponding example code (safe-sockets).

• [ ] How do I add Akka.NET / Akkling to the Server?

SAFE-Chat is a nice demo app that leverages Akka and WebSockets, but it is older and uses Suave for the Server. It's not the same as a "How To Start" recipe.

[Jmaharman]

I recently added Tailwind to a SAFE template to try them both out. I'd be happy to create a recipe for that once the new minimal template is out and I have a recipe format to follow.

[Jmaharman]

One misconception I had coming into SAFE was thinking that it was a purpose built stack, I knew it was made out of a number of frameworks / libraries, but I didn't quite realise how much you could just play around with it from there. It's a starting point more than anything.

I think the way it is moving forward makes total sense, having a minimal template and a full template. It reminds me a little bit of hedycode, if you start using the full template there's too much going on to remember the important bits. Where as if you start with the minimal template and create recipes to help others add more content to their repo, they are then learning as they progress and realise why the full template does the things that it does.

You probably have these thoughts as well, but it won't hurt to hear them repeated. I think it should be very obvious to anyone reading the recipes that they are community driven, that they survive and grow based on community input. A very useful one is to make sure there is an edit link on the page for the reader to make changes, especially as recipes age and packages are updated with breaking changes.

It would be amazing to be able to see the history of the recipe based on the version of package being used, but I feel that is a whole other beast. A problem to solve if recipes are a success, rather than something to do upfront.

[isaacabraham]

We're working on a recipe template and are doing a few sample recipes to get it going. I'm hoping to start rolling them out next week :-)

[markpattison]

Recipe suggestion: How to serve up a file (created on the server) to a user.

Example workflow from the user's point of view:

1. User presses button
2. Front-end sends request with parameters to the server
3. Server creates a file based on request
4. User gets the usual "Download/open./save as..." dialogue in browser

[kaashyapan]

How do I add application configuration ? How do I add environment specific configuration ?

Following Don Syme's recent talk about memetic independence, I think it is an important area to cover for people who come from non .Net background.

A non-C# version of an application configuration walk through without use of Visual Studio and without assuming any prior .Net familiarity and in a location that is readily accessible as the Safe stack docs will be useful.

[RicoSaupe]

Question to that recipe "How do I share code between Web and Console applications?". What is the use case for that? You have some types or even Thoth decoders and use it in server project and a simple console app?

[theimowski]

Question to that recipe "How do I share code between Web and Console applications?". What is the use case for that? You have some types or even Thoth decoders and use it in server project and a simple console app?

I believe this might have been my idea. We do something like that at work - there's an agent running on a device that acts as 'backend' for the Fable app, so the same concepts of sharing code apply. Probably an edge case though, so might not be interesting for wider audience.

[RicoSaupe]

This could also be a use case for my work. Doing similar things, still using c# though but undergoing a transformation to F# now. Thanks to @isaacabraham

[olivercoad]

Sharing code with web and console applications is also something I've done at work with Elmish Bridge DotnetClient (as well as Remoting) for managing CAD projects. There's a background service (BGService) that runs on users' computers and sends/receives messages from the server, which broadcasts/receives messages from the Feliz Client and other BGService instances.

What would you think of naming it "How do I share code between Web and Dotnet client applications" (Or "... Console/Desktop applications")? A different project that never got off the ground had an Avalonia.FuncUI.Elmish component, but any dotnet desktop app that needs to share code with the server could probably benefit from the same recipe.

[kaashyapan]

I realized the difficulty was the unsafetiness of JSON. I ended up going with Bare serialization for client-server messages. It has a fable compatible nuget package with code generator. https://www.nuget.org/packages/bare-cli

[kurt-mueller-osumc]

I would love to see a recipe for adding jwt authentication to a safe stack app :)