Merge pull request #305 from SAFE-Stack/peter-branch-rescue

Bits of Peter's PR that should be merged in.

Author: martinbryant

docs/recipes/build/bundle-app.md

@@ -0,0 +1,24 @@
+# How do I bundle my SAFE application?
+
+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](../../../faq-build). 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.).
+
+#### 1. Run the FAKE script
+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:
+
+```cmd
+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](../../../template-safe-commands) for more details on this build target.
+
+## Testing the bundle
+1. Navigate to the `deploy` folder at the root of your repository.
+2. Run the `Server.exe` application.
+3. Navigate in your browser to `http://localhost:5000`.
+
+You should now see your SAFE application.
+
+## Further reading
+See [this article](/docs/faq-build) for more information on architectural concerns regarding the move from dev to production and bundling SAFE Stack applications.

docs/recipes/build/remove-fake.md

@@ -0,0 +1,41 @@
+# How do I remove the use of FAKE?
+[FAKE](https://fake.build/) is a tool for build automation. The standard SAFE template comes with a [ready-made build project](../../../template-safe-commands) 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**.
+
+#### 1. Build project
+Delete `Build.fs`, `Build.fsproj`, `Helpers.fs`, `paket.references` at the root of the solution.
+
+#### 2. Dependencies
+Remove the following dependencies
+```fsharp
+dotnet paket remove Fake.Core.Target
+dotnet paket remove Fake.IO.FileSystem
+dotnet paket remove Farmer
+```
+
+## Running the App
+Now that you have removed the FAKE application dependencies, you will have to separately run the server and the client.
+
+#### 1. Start the Server
+Navigate to `src/Server` inside a terminal and execute `dotnet run`.
+
+#### 2. Start the Client
+Navigate to `src/Client` inside a terminal and execute the following:
+
+```bash
+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.
+
+## Bundling the App
+See [this guide](../build/bundle-app.md#2-im-using-the-minimal-template) to learn how to package a SAFE application for deployment to e.g. Azure.
+
+---

docs/recipes/storage/use-litedb.md

@@ -0,0 +1,72 @@
+# How Do I Use LiteDB?
+The default template uses in-memory storage. This recipe will show you how to replace the in-memory storage with [LiteDB](https://github.com/mbdavid/LiteDB) in the form of [LiteDB.FSharp](https://github.com/Zaid-Ajaj/LiteDB.FSharp).
+
+#### 1. Add LiteDB.FSharp
+Add the [LiteDB.FSharp](https://www.nuget.org/packages/LiteDB.FSharp/) NuGet package to the [server project](./../package-management/add-nuget-package-to-server.md).
+
+#### 2. Create the database
+Replace the use of the `ResizeArray` in the `Storage` type with a database and collection:
+
+```fsharp
+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](https://github.com/mbdavid/LiteDB/issues/787)).
+
+> See [here](https://www.litedb.org/docs/connection-string/) for more information on connection string arguments.
+
+> See the [official docs](https://www.litedb.org/docs) for details on constructor arguments.
+
+#### 3. Implement the rest of the repository
+Replace the implementations of `GetTodos` and `AddTodo` as follows:
+
+```fsharp
+    /// 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"
+```
+
+#### 4. Initialise the database
+Modify the existing "priming" so that it first checks if there are any records in the database before inserting data:
+
+```fsharp
+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
+```
+
+#### 5. Make Todo compatible with LiteDb
+Add the [CLIMutable](https://github.com/MicrosoftDocs/visualfsharpdocs/blob/master/docs/conceptual/core.climutableattribute-class-%5Bfsharp%5D.md) attribute to the `Todo` record in `Shared.fs`
+
+```fsharp
+[<CLIMutable>]
+type Todo =
+    { Id : Guid
+      Description : string }
+```
+
+> This is required to allow LiteDB to hydrate (read) data into F# records.
+
+#### All Done!
+* Run the application.
+* You will see that a database has been created in the Server folder and that you are presented with the standard TODO list.
+* Add an item and restart the application; observe that your data is still there.

docs/recipes/ui/add-fontawesome.md

@@ -0,0 +1,35 @@
+# How Do I Use FontAwesome?
+[FontAwesome](https://fontawesome.com/) 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:
+
+```fsharp
+open Feliz
+
+Html.i [ prop.className "fas fa-star" ]
+```
+This will display a solid star icon.
+
+## I'm not using the standard SAFE template!
+If you don't need the full features of Feliz we suggest using `Fable.FontAwesome.Free`.
+
+#### 1. The NuGet Package
+Add [Fable.FontAwesome.Free NuGet Package](https://www.nuget.org/packages/Fable.FontAwesome.Free/) to the Client project.
+> See [How do I add a Nuget package to the Client?](../package-management/add-nuget-package-to-client.md).
+
+#### 2. The CDN Link
+Open the `index.html` file and add the following line to the `head` element:
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css">
+```
+
+#### 3. Code snippet
+
+```fsharp
+open Fable.FontAwesome
+
+Icon.icon [
+    Fa.i [ Fa.Solid.Star ] [ ]
+]
+```
+
+#### All Done!
+Now you can use FontAwesome in your code