DEV Community: Verge729

Using Fission with Elm - Part 3: Adding authentication and using the Fission Drive

Verge729 — Tue, 09 Nov 2021 01:22:08 +0000

[UPDATE] The Fission team released fission-suite/webnative-elm version 7.0.0 since the original publish date of this article. This update includes a sign out function. The following sections of the article have been changed to reflect this update: `Walkthrough/Authentication/'Prep work'`and `Walkthrough/Authentication/'Signing out'`. This article no longer makes any changes to the `js/index.js` file as defined in `Fission with Elm - Part 2`.

Make sure the npm and elm-module packages for `webnative-elm` are at 6.1.0 and 7.0.0, respectively. To update them, run the following from the root of the project:

npm install --save-dev webnative-elm
npx elm-json install fission-suite/webnative-elm

Prelude

This is a three-part series. In part one, I showed you how to use Vite to manage an Elm application. In part two, I showed you how to integrate the basics of Fission via the Webnative SDK into the project. In part three (this article), I will show how to add authentication and storage via the Webnative SDK to the application. This article is written assuming the developer already has a Fission account and has completed parts 1 and 2.

It should be noted that the last two articles were fairly short. Both have set the stage for this article, the pinnacle of the series. There will be much to add to our growing application, some of these additions are due to Elm being a strongly typed language.

It should also be noted that if you are using a browser that using something similar to Brave Shields in the Brave browser, you will need to disable the feature so Fission can communicate with the application.

This article will also require the use of a Fission account. If you do not yet have one, take a moment to create one now. Check Appendix A at the end of this article for steps on how to do so.

The Github repository associated with this article can be found here:

https://github.com/xeticode/fission-with-elm-demos/tree/Part-3

Intro

Welcome to the final article. Here you will be tested beyond anything you have ever experienced… Nah, this is not some epic set of trials. That being said, it is my hope that by the end of this article, you have been exposed enough to Fission to continue on in your own Fission-based applications.
It is time to add some usefulness to this application. Right now, it is like a wallpaper: good to look at and not much else. The first feature we will add is user authentication. After authentication, we will add code that will interact with the Fission Drive to write a file to storage. There are no introductions to be made this go-around, so we will review important concepts for what I am about to show you.

Things to review

elm ports are the medium by which an Elm application communicates with JavaScript. For more information, see Elm Ports .
IPFS "is a distributed system for storing and accessing files, websites, applications, and data". For more information, see IPFS .
Wnfs stands for Webnative File System and "is a file system built on top of the (IPFS)". For more information, see Webnative File System .
Fission Drive is a military-grade encrypted file system located within a distributed network. For more information, see Fission Drive .
Let us begin!

Walkthrough

Download an updated Main.elm by running this command in the terminal from the src directory:

curl -o Main.elm https://raw.githubusercontent.com/xeticode/fission-with-elm-demos/interim/part-3/Main.elm

This new Main.elm file lays down some new groundwork for our application. It is also divided into sections, the dividers being noticeable comments. Instead of indicating a line in the file to add or find code, I will indicate a region of the code to look. The differences between the new file versus the old one includes additions to our type alias Model, type Msg, and update function (see section: MODEL/UPDATE); a section for helper functions (see section: HELPER FUNCTIONS); and a new UI (see section: VIEW). Let’s quickly go over the new Msg variants and the Model.

`Msg` variants

Here are the new variants and their purposes:

SignIn will be associated with the login button and will initiate the login process with Fission.
SignOut will be associated with the logout button and will initiate the logout process with Fission.
UpdateNote is the variant that will update the note field in the Model. This is the value that will be written to the Wnfs.
SaveNote is associated with the Save Note button and will initiate the process of writing and publishing our note to the Wnfs.

`Model`

Here is a breakdown of the new fields in Model:

username will store the username of the logged-in Fission user of the current session (if you are not familiar with the Maybe type, or simply need a refresher, see Maybe).
logs is a list of strings and will store log entries associated with the different stages of interaction with Fission. These will be displayed on the left side of the screen. Consider these as a log that make it easier to see the processes when they occur.
note this will store the content that will be sent to the Wnfs.

Before we dive in

Run npm run dev from the root of the project to have the application up and running on the dev server. Once you do this, you should see this:

At this point, you can click on the login button, but it will not take you anywhere. Its associated message, SignIn, is currently a dead end. Not to worry, the first thing we will do is implement authentication.

Authentication

Prep work

One of the reasons my meals are so simple and quick is my hungry stomach will usually override my willingness to spend time on quality meal prep. Lucky for us, this is not a food situation. Before we can sign in, we must add a few things, a metaphorical meal prep, if you will, before we can dig into authentication.

The first thing we must do is expand the GotWebnativeResponse branch in our update function. To begin, replace the current GotWebnativeResponse branch (section: MODEL/UPDATE, function: update) with the following code (be aware, the alignment may change when copying and pasting into your developing environment. You will get the red squiggles if the case statement branches are mis-aligned):

GotWebnativeResponse response ->
    case Webnative.decodeResponse tagFromString response of
        Webnative (Initialisation state) ->
            case state of 
                NotAuthorised ->
                    ( { model
                        | username = Nothing
                        , logs = "Auth: NotAuthorised" :: model.logs
                    }
                    , Cmd.none
                    )
                AuthSucceeded { username } ->
                    ( { model
                        | username = Just username
                        , logs =  "Auth: AuthSucceeded" :: model.logs
                    }
                    , Cmd.none
                    )
                AuthCancelled _ ->
                    ( { model
                        | username = Nothing
                        , logs = "Auth: AuthCancelled" :: model.logs
                    }
                    , Cmd.none
                    )
                Continuation { username } ->
                    ( { model
                        | username = Just username
                        , logs = "Auth: Continuation" :: model.logs
                    }
                    , Cmd.none
                    )

        Wnfs _ _ ->
            ( model, Cmd.none )


        Webnative (Webnative.NoArtifact SignedOut) ->
            ( { model
                | logs = "Signed out!" :: model.logs
                , username = Nothing
            }
            , Cmd.none
            )

        Webnative (Webnative.NoArtifact _) ->
            ( model
            , Cmd.none
            )

        WebnativeError err ->              
            ( { model
                | logs = Webnative.error err :: model.logs
            }
            , Cmd.none
            )

        WnfsError err ->
            ( { model
                | logs = Wnfs.error err :: model.logs
            }
            , Cmd.none
            )

That is a lot of new code, and some of it is accompanied by our friendly neighborhood red squiggles. This is due to missing proper imports and a definition for tagFromString, which is a helper function. Let's resolve the problem starting with the imports.

Go to the import block at the top of Main.elm. Near the bottom of the import block at the top of the file, we have our Webnative import and it is currently exposing Artifact(..) and all its variants (represented by the (..)). Replace this import with:

import Webnative exposing (Artifact(..), NoArtifact(..), DecodedResponse(..), State(..))

Adding these to the exposing list will allow us access to the DecodedResponse and State types from the Webnative-elm module (see DecodedResponse and State).

Now we will define tagFromString. In the HELPER FUNCTION section, add the following code:

tagFromString : String -> Result String Tag
tagFromString str =
    case str of
         _ ->
            Err <| "Invalid tag: " ++ str

Webnative-elm utilizes tags to differentiate between different requests and connect the appropriate response. For example, if I sent a webnativeRequest tagged with “StudioGhibli”, the associated webnativeResponse will have the same tag. We can then create a branch within our GotWebnativeResponse branch’s case statement and dictate how to handle the response.

Now, both webnativeRequest and webnativeResponse require the tag to be a string not an Elm type. That is why we need such helper functions as tagFromString and its companion tagToString. Extra code on our part, yes. This is a byproduct of Elm, not the webnative-elm wrapper. In fact, this is great design by the people behind the wrapper because it couples the Webnative SDK with the strengths of Elm.

Speaking of an Elm type for our tags, we now have another red squiggle to take care of, this time on Tag. Add the following code between the type Msg and update function:

type Tag
    = ChangeMeLater

This is where we define our different webnativeRequest tags. To reiterate, we will return to this later when it is time to utilize our Tag type. We need to define Tag now so we can proceed with the rest of what the GotWebnativeResponse has to offer.
We are now ready to officially sign in!

Signing in

This is where having a Fission account is crucial. If you have yet to do so, stop and take a moment to create a Fission account (see Appendix A at the end of this article for details).

The application is growing up so fast. To implement sign in, go to the SignIn branch of the update function (section: MODEL/UPDATE) and replace Cmd.none with the following code:

permissions
    |> Webnative.redirectToLobby Webnative.CurrentUrl
    |> webnativeRequest

This will take our permissions (defined in part 2 of this series) and pass it to the Webnative function redirectToLobby.

Time to see it in action! Refresh the app in the browser and click "Login"! This will take us to a Fission authorization lobby. You will see something like this:

This lobby utilizes the appPermissions and fsPermissions we defined at the beginning of the Main.elm file. If there are no defined fsPermissions (like with this application), the only permission request will be for the file path generated for the application. Once you grant permission, authentication will finish.

Rather than using traditional username and password authentication (such as OAuth), Fission uses cryptographic keys and stores them in a browser you authorize with your Fission account (you can authorize multiple browsers on multiple machines). See Webnative Authentication for more information.

Once you have logged in and granted permission for the app to access Trillian/fission-with-elm (aka creator/name as specified in appPermissions located in the beginning of section: FISSION SETUP) in your Fission Drive, you will see this simple web page:

Before we implement signing out, I want to give a quick walkthrough of this application.

The UI

Under the “Fission with Elm” title, there are two oval-esque elements. The one on the left should display the Fission logo and your Fission username, and the one on the right is a logout button.

On the far-left side of the screen, you will see “Auth: AuthSucceeded”. When you save a note, more logs will appear here, allowing you to see the process of writing to a Fission Drive.

The center of the screen has a textbox where you can write a note and a “Save Note” button below it that will write the note to your Fission Drive. This functionality will be implemented after sign out.

In the bottom right corner, there should be a little blue rectangle which displays the Elm logo and a number. This is a button that will open the Elm debugging window.

Anyways, on to the implementation of signing out!

Signing out

The webnativeRequest port supports two types methods of signing out: Webnative.leave and Webnative.signOut (see Webnative, in the section named "Authentication").

Webnative.leave will redirect the user to a Fission logout lobby, which looks like this:

Webnative.signOut will not redirect the user to a Fission logout lobby.

To add sign out functionality, go to the SignOut branch in the update function and replace the current version of it with:

SignOut ->
    ( { model
        | username = Nothing
        , logs = "SignOut" :: model.logs
    }
    , Webnative.signOut
        |> webnativeRequest
    )

Bah-duh bing, bah-duh boom! We can now sign in and sign out! Time to see it in action. Go ahead and test the app by logging in and logging out! Pretty cool!

Next up on the docket is writing to a Fission Drive, let us dive in!

Data Storage

Writing to the Wnfs is a two-step process:

Write the data to a file and save it in the Wnfs in the local browser storage
Once saved locally, replicate and encrypt the data and store it in the Wnfs on the IPFS network

The following diagram depicts the write process within the context of our application:

The three circles in the elm app section represent Msg and Tag variants and are milestones in the writing process. We begin by calling the SaveNote Msg variant and end in handling a tagged webnativeResponse with our PublishNote Tag variant.
We need to do the following to replicate this process in our application:

type Tag
- Finish defining the variants for the Tag type. Once this is done, we can tag requests and appropriately handle the associated responses.
Helper functions
- Write several helper functions to help with encoding the data and using tags.
update function
- Update various case statement branches to accommodate saving a note.

Once we get through that, our application will be complete. Let’s get started!

type Tag

This is our current state of our Tag type:

type Tag
    = ChangeMeLater

We need to swap the current variant from ChangeMeLater with two new variants: WriteNote and PublishNote. This will allow us to handle responses to the write and publish requests.

Change the type Tag to look like this:

type Tag
    = WriteNote
    | PublishNote

Helper functions

Two of these helper functions (tagFromString and tagToString) are needed simply because Elm is a strongly typed language and does not have a native way to convert type variants to strings. This gives us extra work to do before we can accomplish our goal. Fortunately for this application, our application is small and will not require much of this kind of code.

The other two helper functions (encode and save) are for encoding our note and preparing it as a Webnative.Request.

tagFromString

We can now properly finish the implementation of this function! This will allow us to convert our Type variants to strings. Replace the half-baked tagFromString with the following full-baked code:

tagFromString : String -> Result String Tag
tagFromString str =
    case str of
        "WriteNote" ->
            Ok WriteNote

        "PublishNote" ->
            Ok PublishNote
        _ ->
            Err <| "Invalid tag: " ++ str

tagToString

As promised, here is the second helper function for the tags. This will convert a Tag into a String so we may add it to the webnativeRequest. Make sure to get the spelling right AND that it matches the spellings used in tagFromString function. Add this code to the HELPERS section of the file:

tagToString : Tag -> String
tagToString tag =
    case tag of 
        WriteNote ->
            "WriteNote"
        PublishNote ->
            "PublishNote"

encode

This application will write our note to a JSON file. This next helper function will JSON encode our note. Add the following code to the HELPERS section of the file:

encode : String -> Json.Encode.Value
encode note =
    Json.Encode.object
        [ ("note", Json.Encode.string note)            
        ]

save

This function will take the pieces we have made in this portion of the walkthrough and use them to initiate the writing process. It will first take our note and encode it to a JSON value, prettify it, and then write it to a specified file with an associated Tag. Add the following code to the HELPERS section of the file:

save : String -> Webnative.Request
save note =
    note    
        |> encode
        |> Json.Encode.encode 0
        |> Wnfs.writeUtf8
            Wnfs.Private
            { path = Path.file [ "Apps", "Trillian", "fission-with-elm", "notes", "note.json"]
            , tag = tagToString WriteNote
            }

update Function

The prep work has been laid, now we need to establish some milestones. The writing process will begin when we click the “Save Note” button, which will send a webnativeRequest tagged with WriteNote. We will then handle the associated response and then send one more webnativeRequest tagged with PublishNote. The final step will be handling the associated response.

SaveNote msg

To begin, we need to change the Cmd.none in our SaveNote update branch to a Cmd that calls our webnativeRequest port. Replace Cmd.none with the following:

webnativeRequest <| save model.note

This will begin our interaction with Webnative by writing our note to a file and then writing it to our Wnfs. The next step is to handle the response.

WriteNote handler

Our WriteNote response will be caught by our subscription to the webnativeResponse port and be redirected to the GotWebnativeResponse Msg variant. Add the following branch to GotWebnativeResponse, just before the Wnfs _ _ branch:

Wnfs WriteNote _ ->
    ( { model
        | logs = "Note Written..." :: model.logs
    }
    , ({ tag = tagToString PublishNote }
        |> Wnfs.publish
        |> webnativeRequest)
    )

This code block will add an entry to our model’s list of logs and then chain a new request to publish our updated Wnfs.

PublishNote handler

Our PublishNote response will again be caught by our subscription to the webnativeResponse port and be redirected to the GotWebnativeResponse Msg variant. In GotWebnativeResponse, replace the Wnfs _ _ branch with the following:

Wnfs PublishNote _ ->
    ( {model
        | logs = "Note Published to Fission Drive!" :: model.logs
        }
    , Cmd.none
    )

This code block will add an entry to our model’s list of logs and then do nothing because the process of writing our note to the Wnfs has reached its end. Your file will then be accessible from your Fission Drive! It may take a few seconds to propagate the data to the Drive, so be aware of that.

The Finished Project

Let’s do a quick walk through of writing to your Fission Drive. Begin by opening a new window or tab, and navigate to your Fission Drive. Once there, navigate to the fission-with-elm directory (Apps > Trillian > fission-with-elm). This directory should be empty (unless you saved a note between finishing the app and now).

Refresh the app page in the browser to make sure your browser has loaded the latest compiled version of the app from the server. Now, navigate to the “Fission with Elm” application and add some text to the input field in the app. It can be as quick as “asdf” or as creative as “test”, it is up to you. Once you have done so, click the “Save Note” button and then navigate back to your Fission Drive. As a reminder, it can take a few seconds for the new note to propagate to your Drive. Once a note has been written, there should appear a new directory within the fission-with-elm directory called notes. Enter that directory and you will see a JSON file entitled note. If you click on it, you will see the contents of the file in a preview window located on the right side of the screen. Like so:

Voilà!

The End of a Trilogy

There is not much reading left now. And I can guarantee this ending is not as satisfying as the end of watching the Lord of the Rings trilogy for the umpteenth time… But hey, we made it. The “Fission with Elm” demonstration app is now fully functioning, and you now have a better grip on the basics of integrating Fission into your code.

In the first part of this series, I showed you how to set up Vite to manage Elm applications. This was the foundation of the application. In the second part, I showed you how to integrate Fission into an Elm project via the webnative-elm module. This highlighted the structure of Fission integration. This third part took what was established in the previous two parts and demonstrated some of the processes of Fission.

I hope you have found this series of articles helpful as you begin to build Fission-based applications in Elm!

Feel free to email any questions you may have to info@xeticode.com and my team and I will answer as promptly as we can :)

Appendix A

Creating a Fission account

Go to https://fission.codes/
Click on the "Sign up" button (located in the top portion of the screen)
Click "Create account"
Enter an email and desired username into the fields
Click "Get started"
Follow the instructions on your screen to link your account to another device!

Using Fission with Elm - Part 2: Integrating Fission into the Elm project

Verge729 — Mon, 18 Oct 2021 22:47:24 +0000

Prelude

This is part of a three-part series. In part one, I demonstrated how to use Vite to manage an Elm application. In part two (this article), I will show you how to integrate Fission into the project from part one. Part three will walk you through how to refactor the project for Fission authentication and Fission Drive.

The Github repository associated with this article can be found here:
https://github.com/xeticode/fission-with-elm-demos/tree/Part-2

Intro

Welcome to round two! The time has come to upgrade our project from part one! The upgrade will connect the application to Fission, which I will introduce to you in a short moment. Before the introduction, I want to point out why Fission is a tool of the future. Fission uses a distributed system to store data. To one up that, Fission built a file system in the distributed system and protects it with military grade encryption. That means you can have a whole file system saved and protected across a whole network (in this case, the internet) rather than just on a remote machine or your own. And for app development, it means no need to worry about server maintenance or scaling. Anyways, I am getting ahead of myself. Without further ado, I present to you the InterPlanetary File System (IPFS) and, of course, Fission.

Enter IPFS…

In short, the “IPFS is a distributed system for storing and accessing files, websites, applications, and data” (for more information, see IPFS). No more need for centralized servers! Have you ever heard of blockchain? It uses a similar technical approach: peer-to-peer networking using content addressing. Say goodbye to centralized servers!

Enter Fission…

To add to my pre-introduction, Fission is built on top of the IPFS, and implements a layer of military grade encryption. I know I mentioned this before, but it deserves more attention. Fission created a file system called Webnative File System (Wnfs). It has a huge advantage over cloud storage in that it resides in a distributed system rather than centralized servers, meaning it is backed up on a vast network of machines and not at the data centers of some tech company.

Fission developed the Webnative SDK to interact with Fission services. Since we are working with an Elm application, we will use the Webnative-elm module for Elm (see Webnative-Elm). Using this wrapper allows us to maximize our Elm code and minimize the JavaScript for the project.

The Walkthrough

NOTE: This article assumes you have completed the project as described in part 1. If you have not completed that project, please go back and follow the steps in part 1 to complete it or download the part 1 reference project. See Fission with Elm, Part 1: Using Vite to manage Elm applications for both options.

Installing Webnative dependencies

To start things off, we will need to install Webnative to our node modules and elm.json file. To do this, run the following commands in the terminal from the root directory of the project:

npm install --save-dev webnative webnative-elm
npx elm-json install fission-suite/webnative-elm

These commands do the following:

npm install webnative webnative-elm will install both webnative and webnative-elm libraries to the project (check package.json for the new additions).
npx elm-json install fission-suite/webnative-elm will install the Elm dependency of the fission-suite/webnative-elm module (check elm.json for the new addition). This module is a wrapper, written in Elm, for Webnative.

Modifying js/index.js

This is pretty simple.

At the top of the file, add these two lines:

import * as webnative from “webnative”
import * as webnativeElm from “webnative-elm”

And after the const app = Elm.Main.init({}); line, add these two lines:

webnative.setup.debug({enabled:true});
webnativeElm.setup({app, webnative});

Here is a quick breakdown of the new lines:

webnative.setup.debug({enabled:true}); toggles on the debug mode. If enabled, the debug mode will output Webnative-related messages to the Console tab in the Developer Tools window. Toggle debug mode with this window open and you will easily see the difference.
webnativeElm.setup({app, webnative}); initiates the webnative-elm wrapper, taking the initialized Elm application and the Webnative SDK connection as parameters.

Modifying src/Main.elm

Ports

Elm ports are how an Elm application can communicate with JavaScript, or the “outside world” as I like to call it (for an in-depth explanation of Elm ports, see Elm Ports). The current state of the Main.elm file does not permit the use of ports. To change this, we need to change the file from a standard module to a port module. On line 1 of Main.elm, add port before module. We can now use ports in this Elm file! Let’s add some!
Normally, Elm ports require two ends: one Elm, and one in JavaScript. What makes this situation “abby”-normal (if you know, you know) is that this application is only concerned with interacting with Fission. The webnative-elm wrapper handles the JavaScript end of the Webnative-related ports. The wrapper has also consolidated all of the ports we may need into two ports: one for all Webnative requests, and one for all Webnative responses.
The Webnative SDK requires two ports: one for requests, and one for responses. Add these two lines just after the import block at the top of the file in Main.elm to satisfy the requirement:

port webnativeRequest : Webnative.Request -> Cmd msg
port webnativeResponse : (Webnative.Response -> msg) -> Sub msg

Once you have them added, you will notice the red squiggles under Webnative.Request and Webnative.Response. This is because we have yet to import Webnative to the file. Add:

import Webnative

to the import block at the top of the file.

Adding Permissions

Every Fission-based application requires a set of defined permissions to initialize the application.
There are three functions we will add to our project to define these permissions: appPermissions, fsPermissions, and permissions.

appPermissions will return a record with fields indicating the name of the application and the creator of the application. Add the following just after the Webnative ports in Main.elm:

appPermissions : Webnative.AppPermissions
appPermissions =
    { creator = "Trillian"
    , name = "fission-with-elm"
    }

This is what Fission will use to create a file path within the Wnfs to the files produced by this application (i.e. Apps/Trillian/fission-with-elm/). Feel free to change the creator field to your own username if you so desire.

fsPermissions will return a record with fields indicating what public and private parts of the Wnfs for which the application will request access (“fs” stands for File System here). Add the following a couple of lines after appPermissions, but before type alias Flags:

fsPermissions : Webnative.FileSystemPermissions
fsPermissions = 
    { public =
            { directories = []
        , files = []
            }
    , private = 
            { directories = []
            , files = []
            }
    }

This application is not asking to access any parts of the Wnfs external to this application, so the lists will remain empty.

permissions the icing on the cake. This will return a record with two fields: app and fs. These correspond to the two previous code blocks we talked about. Add the following a couple of lines after fsPermissions, but before type alias Flags:

permissions : Webnative.Permissions
permissions =
    { app = Just appPermissions
    , fs = Just fsPermissions
    }

We will pass this, our newly defined permissions, through the webnativeRequest port in the next step.

The `init` and `subscriptions` functions

`init`

The only difference here is changing the Cmd msg from Cmd.none to a command that will initialize the application as a Webnative application. The new init function should look like this:

init : Flags -> Url.Url -> Navigation.Key -> (Model, Cmd Msg)
init {} url key =
    ( Model
    , permissions
        |> Webnative.init
        |> webnativeRequest
    )

Here is a quick explanation of the new command:

permissions was previously defined in the walkthrough. It indicates both the name and creator of the application and contains a list of Wnfs access requests.
Webnative.init is a function of webnative-elm that will load a user's Wenative File System, if said user is authenticated.
webnativeRequest is our port for our Webnative related requests. subscriptions We now need to subscribe to webnativeResponse so the response will be properly handled and not left by the wayside. In the subscriptions function, change Sub.none to:

webnativeResponse GotWebnativeResponse

This will set the application to watch our webnativeResponse port for any changes. GotWebnativeResponse is a Msg variant we will add in a few moments and will be where we handle the response.

Adding a variant to the `Msg` and updating the `update` function

`Msg`

At this point, we have only two Msg variants: UrlChanged Url.Url and LinkClicked Browser.UrlRequest. To handle the webnativeResponse, we need to add the GotWebnativeResponse variant. Add the new variant to the Msg so that it looks like this:

type Msg 
    = UrlChanged Url.Url
    | LinkClicked Browser.UrlRequest
    | GotWebnativeResponse Webnative.Response

This new variant will allow us to dictate how to handle each response the application receives from webnativeResponse. Our friendly red squiggles should now be present on our update function. This is because our new Msg variant is a new branch the case statement in our update function needs to handle. The only problem? We have yet to add the branch to the case statement. This exemplifies one of the beauties of Elm, it forces us to handle each defined potential outcome or branch of whatever it is that is the subject of a case statement. Super helpful if you are, at times, forgetful 😉 Let us now add the new branch to update.

`update`

That being said, as much as we may enjoy the red squiggles, they need to go. Add the following branch to the update function's case statement:

GotWebnativeResponse response ->
    (model, Cmd.none)

This will satisfy the Elm compiler, but it needs to be noted that this state of the GotWebnativeResponse branch does not handle anything. It is currently a dead end for the Webnative response, and for the time being, it will stay that way. The reason for this decision is that adding the proper logic to this branch fits beautifully with what is covered in part three of this series: authentication and interacting with the Wnfs. So be sure to check out part three!

The Ending

Before its over: See that it works

So far we have done all this work, but have yet to visually see any of that work in our app. If you have not done so already, get your dev server running. Once you have the app running, open the Developer Tools window in your browser, and go to the Console tab. You should see the following message in the list of messages:

[vite-plugin-elm] ports. webnativeRequest.subscribe called

This indicates that our application is listening to the webnativeRequest port! Visually, it is not much, but internally this is very important.

Adieu

And there you have it! The application has been upgraded with Fission integration. In this article, I showed you how to build upon what we made in the first article. In the third article, we will see the culmination as functionality is added to the project. If you wish to learn more about Fission or the Webntive-Elm module, check out these links:

Fission
Webnative-elm
- https://package.elm-lang.org/packages/fission-suite/webnative-elm/6.0.0/

Using Fission with Elm - Part 1: Using Vite to manage Elm applications

Verge729 — Tue, 12 Oct 2021 22:34:16 +0000

Prelude

This is a three-part series. In part one (this article), I will show you how to use Vite to manage an Elm application. The second article will show you how to integrate the basics of Fission via the Webnative SDK into the project and the third will walk you through how to refactor the project for Fission authentication and using a Fission Drive.

The Github repository associated with this article can be found here: https://github.com/xeticode/fission-with-elm-demos/tree/Part-1 .

Intro

Hello, hello! In this article, I will walkthrough how to initialize a Vite project and then set up an Elm application within that project. Before I do that, I will quickly introduce you to both Vite and Elm because a lack of character development is almost always an insufficient foundation for any good story. So, without further ado…

Enter Elm…

Elm is not only a typed, pure functional language that transpiles to JavaScript, it is also an architecture for web applications (known as The Elm Architecture or TEA, for short). As a language, Elm offers excellent error messages and is able to avoid runtime errors at compile time because of its strong typing and pure functions. This combination can make refactoring a project a breeze as Elm directs the developer to the exact spot or a specified area where the error is occurring. As an architecture, Elm employs a reactive Model-View-Controller design, or more common within the code: a Model, a view, and an update function. As the user interacts with the UI, messages are sent to the update function which then can alter the data within the Model, which will then update the UI, and the cycle continues on.

To learn more about Elm, check out https://elm-lang.org/ .

Enter Vite…

Vite is a bundling tool that uses browser-native ES modules and tools such as Rollup to build a project. Vite makes it easy to build JS modules along side your Elm code for seamless project deployment. This will not be apparent in this article because we will not be using JS modules. That being said, we will use them in subsequent articles, so setting up Elm with Vite is necessary moving forward. For now, we will have the benefit of using the dev server, build, and build preview functionality offered by this tool.

To learn more about Vite, check out https://vitejs.dev/ .

The Walkthrough

Alright, now that introductions have been made, we can proceed!

Initialize the Vite project

First things first: open an IDE of your choice and open the directory in which you want to store the fission-with-elm application. Once that is done, run the following commands in the terminal from the directory holding the project:

npm init vite

This command will initialize a Vite project.

We will be prompted to enter a name for the Vite project. Normally, this would be your chance to come up with something creative, but since this is a walkthrough, that will have to wait. Name the project fission-with-elm. Anyway, next you will then be prompted to select a web framework. Vite initializes a project differently based on the chosen web framework. As Elm is not one of the core frameworks we will select vanilla for the framework and vanilla as the variant.

Once the Vite project has successfully been initialized, these will be the next commands to run, some of which are displayed at the end of the output from the npm init vite command:

cd fission-with-elm
npm install --save-dev vite-plugin-elm
npm run dev

These commands do the following:

cd fission-with-elm : will move the terminal's working directory into the project directory.
npm install --save-dev vite-plugin-elm : will install a Vite plugin that bridges the gap between Vite and Elm. Vite supports a handful of web frameworks from the get-go and Elm is not one of them. Thus we install a plugin to make up for that. The --save-dev tag will make this a development dependency, which is a dependency kept for development and building of the project, but is not kept for deployment.
npm run dev : will begin the dev server. dev is a script defined in the package.json file.

Before running these commands in the terminal, take a look at the file explorer and browse the files added by npm init vite. You should see:

.gitignore
favicon.svg
index.html
main.js
package.json
style.css

As we change some of the project structure, some of these files will become redundant and can be removed. I will indicate which files those are at the appropriate times. Now run the three commands indicated by the terminal.

After running npm run dev you will see the dev server is running at http://localhost:3000. If you go there you should see this:

The only thing that remains to finish initializing this Vite project is making it so the project can properly use the Elm plugin. To do this, we will create a file named vite.config.js. This file will be placed within the current directory (which is named after the name you chose for the Vite project). The file needs to contain the following:

import elmPlugin from "vite-plugin-elm"

export default {
  // identify what plugins we want to use
  plugins: [elmPlugin()],
  // configure our build
  build: {
    // file path for the build output directory
    outDir: "build",
    // esbuild target
    target: "es2020"
  }
}

Set up the Elm Application: Installation

elm-tooling

Life and setting up an Elm application have at least one thing in common: there are many ways to do it. As this is a dev article, I will not indicate which way of life you should live, but I will tell you which method to use to set up an Elm application. For this project, we use elm-tooling. It is a command line program for managing Elm tools, namely: elm, elm-format, elm-json, and elm-test-rs (see elm-tooling-cli for more information). First step for setting up an Elm application is to install elm-tooling. Run the following commands in the terminal (double check to make sure you are still in the fission-with-elm directory):

npm install --save-dev elm-tooling
npx elm-tooling init
npx elm-tooling install

These commands do the following:

npm install --save-dev elm-tooling : installs the elm-tooling tool to the project.
npm elm-tooling init : will initialize elm-tooling within the project. You will notice a new file named elm-tooling.json : appear in the file explorer.
npx elm-tooling install : will install the selected tools to ~/.elm/elm-tooling/ and create soft links to these tools in ./node_modules/.bin/ .

You can see what tools elm-tooling has to offer by running the

npx elm-tooling tools

command. This will also let you select the tools you want for the project. Running the command will present you with output like this one:

As you can see, elm, elm-format, and elm-json are selected by default. We will not be using the last tool, elm-test-rs, which is a tool used for testing the application, as writing tests is beyound the scope of these articles.

elm-json

Next, run:

npx elm-json new

This will create a file named elm.json. This file holds information concerning the Elm application such as: dependencies, location of source directories, and which version of Elm is being used for the project. There will be a question about what type of Elm project you want, select “application”.

At this point we have four JSON files: elm.json, elm-tooling.json, package-lock.json, package.json. Here is what is significant about each file:

elm.json : this contains Elm specific information such as Elm module dependencies, the version of Elm being used, and the file path(s) to any source directories within the project.
elm-tooling.json : this contains a limited selection of Elm tools
package-lock.json : the npm package version lock.
package.json : this contains information of the project such as the name of the project, command line scripts (i.e., the dev command previously executed in this walkthrough).

Set up the Elm Application: Modifying to the file structure

Ok, now that installation has been complete, let’s add some structure to the project! We will be adding a few directories and files with those directories. As a reminder, everything that will be added will be with the fission-with-elm directory (now referred to as root directory for the remainder of this article).

Add a directory named src. This will be for your Elm source files. Within that directory, add a file named Main.elm. Leave the file empty for now.
Add another directory in the root directory called js. In this new directory, create a file called index.js. Leave the file empty for now.
Create another directory in the root directory called public
1. Within public, create a directory called assets
2. Within assets, create a directory called images
3. The end product here should look like: ./public/assets/images/. For this project, we will be using the Fission logo. You can download this image from the repo associated with this article. To do so, Run the following command in the terminal from the images directory:
```
  curl -o fission.svg https://raw.githubusercontent.com/xeticode/fission-with-elm-demos/Part-1/public/assets/images/fission.svg
```

Set up the Elm Application: Adding content to the files

We are near the end! We have a few files to change: ./js/index.js, ./src/Main.elm, and ./index.html. First, we will take a look at ./index.html.

index.html

We need to connect the index.js file to the index.html file via a script tag that will be placed within the head tag.

This is the new content of the index.html file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
    <!-- Here is the new script tag -->
    <script type="module" src="./js/index.js"></script>
  </head>
  <body>
    <!-- This is the old content -->
    <!-- <div id="app"></div> -->
    <!-- <script type="module" src="/main.js"></script> -->
  </body>
</html>

These changes make the main.js and styles.css files redundant as we no longer reference them. Both files are used to present the Hello Vite! webpage from the beginning of the walkthrough. Delete these files now.

index.js

Here is all that is needed in the ./js/index.js file:

import { Elm } from "/src/Main.elm"

const app = Elm.Main.init({});

This is the connection point between index.html and our Elm application. Line 1 indicates where to find the application, and line 3 initializes the application.

Main.elm

This article does not focus on the components of Main.elm. Because of this, and the length of the file, we will download the file directly from the Github repository. We will dive into the file in Part 2, but for now, use this command to download the Main.elm file from the repository asociated with this article. We will dive into this file in part 2:

curl -o Main.elm https://raw.githubusercontent.com/xeticode/fission-with-elm-demos/Part-1/src/Main.elm

Set up the Elm Application: Importing Elm modules

Alrighty! Go ahead and run

npm run dev

The compilation should fail. Reason being? There are dependencies we refer to from within Main.elm that have not been installed. Run the following command in the root directory to install the missing dependencies:

npx elm-json install elm/browser elm/url mdgriffith/elm-ui

Here is some information on the packages being installed (for more info on each package, see https://package.elm-lang.org/ and enter the package name in the search bar):

elm/browser enables the Elm application to run in the browser.
elm/url handles creation and parsing of Urls (required when using Browser.application).
mdgriffith/elm-ui handles layout and styling (there are a few options for for layout and styling, and I chose elm-ui for its simplicity, capability, and ease of use).

After running the command, a confirmation prompt will appear regarding the addition of these modules to the elm.json file. There will be some dependencies to be installed to the indirect dependcies because the direct dependencies depend on them. The word "dependency" was used too much in that last sentence... I recommend having the elm.json file open so the changes can be visibly seen.

You can also run the npx elm-json install command once per dependency if desired. Once those dependencies have been installed, the error messages should disappear and you should see this:

The Ending

Before its over: Witness the live reload of Vite

For this part, make sure you have the dev server running and a browser open to the localhost domain. Vite has live reload functionality. In other words, if you change something in the Main.elm file, it will take note of the changes made and automatically serve the new files. To demonstrate this, go to line 68 in Main.elm. You should see this:

, EBA.color <| E.rgb255 176 192 222

This line dictates the background color of the application. Change any number of the intgers following E.rgb255 to a value between 0 and 255 inclusive and see the background automatically change!

Before its over: Build and Serve the project

Before we can officially wrap this up, I will show you how to build the project and serve the build directory. Run these commands:

npm run build
npm run serve

Both build and serve are scripts defined in package.json. These commands do the following:

npm run build will use Vite to build the project. As it builds, a new directory named build will appear in the file structure. The first children of this directory will be the static files from the location indicated by the publicDir tag from the vite.config.js file. The other children will take a moment to appear and will be the files generated from the build process.
npm run serve will start a localhost server and serve the files from the build directory. This will be running at http://localhost:5000 .

The result should be the same as what is produced by the npm run dev command.

Adieu

And there you have it! A simple Elm project that is managed by Vite. As a reminder, this only covers the basics of setting up Vite and Elm, if you wish to learn more about what they both have to offer, follow these links:

Elm
- https://package.elm-lang.org/
- https://elm-lang.org/
Vite
- https://vitejs.dev/

In the next article, we will alter this project to integrate Webnative, an SDK built and provided by Fission.

DEV Community: Verge729

Using Fission with Elm - Part 3: Adding authentication and using the Fission Drive

Make sure the npm and elm-module packages for webnative-elm are at 6.1.0 and 7.0.0, respectively. To update them, run the following from the root of the project:

Prelude

Intro

Things to review

Walkthrough

Msg variants

Model

Before we dive in

Authentication

Prep work

Signing in

The UI

Signing out

Data Storage

type Tag

Helper functions

update Function

The Finished Project

The End of a Trilogy

Appendix A

Creating a Fission account

Using Fission with Elm - Part 2: Integrating Fission into the Elm project

Prelude

Intro

Enter IPFS…

Enter Fission…

The Walkthrough

Installing Webnative dependencies

Modifying js/index.js

Modifying src/Main.elm

Ports

Adding Permissions

The init and subscriptions functions

init

Adding a variant to the Msg and updating the update function

Msg

update

The Ending

Before its over: See that it works

Adieu

Using Fission with Elm - Part 1: Using Vite to manage Elm applications

Prelude

Intro

Enter Elm…

Enter Vite…

The Walkthrough

Initialize the Vite project

Set up the Elm Application: Installation

elm-tooling

elm-json

Set up the Elm Application: Modifying to the file structure

Set up the Elm Application: Adding content to the files

index.html

index.js

Main.elm

Set up the Elm Application: Importing Elm modules

The Ending

Before its over: Witness the live reload of Vite

Before its over: Build and Serve the project

Adieu

Make sure the npm and elm-module packages for `webnative-elm` are at 6.1.0 and 7.0.0, respectively. To update them, run the following from the root of the project:

`Msg` variants

`Model`

The `init` and `subscriptions` functions

`init`

Adding a variant to the `Msg` and updating the `update` function

`Msg`

`update`