This will eventually be a guide entry that documents how to use a combination of a special backup file as well as email account validation to allow for full account recovery, including private files and data.

Like all Fission apps -- including the ones made by Fission directly -- you need to give permission to the Dashboard app to access your account info.

The first account management feature in the Dashboard is to show the verification status of your account, and to resend your verification email if it ended up in your spam.

Fission Drive is currently a preview release of our upcoming file storage and identity system that lets you take your files anywhere, encrypted end-to-end as well as for public hosting of files, websites, and apps.

The Preview release is an exploration of the interface, and currently supports only public files.

Enter any IPFS Hash

You can browse any IPFS directory, not just those hosted on Fission, by entering in the hash, or Content ID (CID), of a directory.

You can use QmbCLefkFuXbhHBWSW7PWmJzBL7W7e8zm41HK4DGJ1RDwV as an example folder to browse. Visit drive.fission.codes to try it out.

The hash above represents Boris' public files, which you can also see in the default IPFS browser at boris.fission.name.

Features

Dark & Light Mode

Preview supports system wide / browser settings for dark vs. light mode and will switch automatically when you change those settings.

File Previews

Clicking on an image will give you a file preview.

Click on the double arrows in the top right hand corner to embiggen the preview to full screen. Hit the X to close the preview.

The "Open in new tab" link will give you a permanent link for sharing the current file, using the Fission IPFS gateway.

Mobile Support

Yes, this works on mobile!

Keyboard Shortcuts

Use arrow keys to navigate, enter to open preview.

When you create a Fission Account, whether signing up on the web or using the command line as a developer, it creates a username and email address in our service database, and also a private / public key pair representing that account.

We also create a Fission Web Native File System (WNFS) attached to your account, and given you access to Fission Drive, which lets you browse all your files, access them from any browser, and see which apps are attached to your file system.

We verify your email address, and can use that to help manage aspects of your service with us. You hold access to the keys connected to your account, and sign in happens automatically.

We encourage you to "link" your account to multiple devices -- your desktop and your phone, your home and your work computers, and so on. These devices can then be used to login, or link more accounts. You can read more about Account Linking »

Signing out of Fission Apps

There is no "sign out" for a Fission-powered app. You use your key to do a passwordless login, stored in your local desktop browser, mobile web browser, or your local desktop file system with the command line developer tool.

While your device is linked with a key, Fission apps will check that you have a key with the proper permission, and will just let you right in, without having to remember a password or even a username.

This is like your smartphone: only a single user is "logged in" to their personal phone, and they aren't shared.

We don't delete the data that the app stored for you, since it's stored in your own Fission File System -- just like data is stored on your phone.

App Permissions

As part of signing into an app, an app will ask for certain permissions. Right now, these are mostly related to access to your file system.

By default, every app needs access to an App Folder. You'll need to at least grant access to an App Folder for the app to function correctly.

Revoking App Access

Instead of signing out, you may want to revoke -- or delete -- an app's access to your account.

Shared Devices

Browsers and desktop computers aren't smartphones, and they do get shared. You can unlink a device -- remove your key -- by visiting the Fission Auth page.

Multiple Accounts per Device

You may create multiple Fission accounts, but you'll need a unique email address and username for each one. You'll also need to use Browser Profiles to be able to access them at the same time on the same machine, as the keys that grant access are stored in the browser.

All of the apps that you have published with your account are listed on the Apps page.

Create a new app from the Dashboard

As well as using the Fission CLI to register and publish apps, you can drag and drop a folder of HTML, CSS, and JavaScript files to create and publish your app directly from the browser.

Manage apps you've created

When you click on an app in your apps list, you get to a page you can update, rename or delete your apps on.

Setup

With fission installed, we are ready to set it up on your local machine. If this is your first time using fission, you will be prompted for a username and an email to confirm your new account.

$ fission setup
🌱 Setting up environment
🪐 Downloading managed IPFS for Linux
🎛️  Configuring managed IPFS
generating ED25519 keypair...done
peer identity: 12D3KooWHZ3C1tDmzUhgi3A6LYmgBxvv1E1obtG7S2ZkYM1MN83
initializing IPFS node at /home/yourname/.config/fission/ipfs
🔑 Creating keys
🏠 Do you have an existing account? [Y/n] n
Username: YOURNAME
Email: yourname@example.com
✅ Registration successful! Head over to your email to confirm your account.
🎛️  Initializing user config file
✅ Done! Welcome to Fission, YOURNAME ✨.                                                                                             

A private key has been generated for your machine and saved in the ~/.config/fission/key/ directory. This key secures your communication with Fission services and works like using an SSH key to connect to GitHub.

Account Linking

If you already have an account created in a web browser, you can link it on your local machine. See the Fission CLI linking guide to link your account.

Create a simple webpage

Let's publish a simple webpage with Fission! We will write a simple webpage, register it as a Fission app, and publish it to the web.

Create a project directory and an index.html file.

mkdir hello-universe
cd hello-universe
touch index.html

Add some content to index.html:

<html>
  <head>
    <title>Hello Universe!</title>
  </head>
  <body>
    <h1>Hello Universe!</h1>
    <p>This is a Fission powered page.</p>
    <p>Assisted by <a href="https://fission.codes">Fission</a>.</p>
  </body>
</html>

Run fission app register command to initialize the webpage as a Fission app. You will be prompted for a build directory.

$ fission app register
👷 Build directory (.):

Press enter to set hello-universe as your build directory, and fission will initialize your app.

✅ App initialized as big-narrow-fuchsia-elf.fission.app
⏯️  Next run fission app publish or fission app publish --watch to sync data
💁 It may take DNS time to propagate this initial setup globally. 
In this case, you can always view your app at 
https://ipfs.runfission.com/ipns/big-narrow-fuchsia-elf.fission.app

Fission will create a fission.yaml file with your app configuration.

ignore: []
url: big-narrow-fuchsia-elf.fission.app
build: .

The url is where your webpage will be on the web after it has been published, build tells the fission which directory to publish, and ignore is a list of files and directories to ignore. See the Fission YAML guide for more details.

Run fission app publish to publish the webpage.

$ fission app publish
🕚🛫 App publish local preflight
✈️  Pushing to remote
🚀 Now live on the network
📝 DNS updated! Check out your site at:
🔗 big-narrow-fuchsia-elf.fission.app

Copy the URL from the last line and paste it into your web browser to view the webpage live on the web. Nice and simple!

Web Linking

To have access to your account across multiple devices, you need to link them.

When you visit an app on a new device and Sign in with Fission, or if you go directly to the Fission Auth page, you'll be prompted to either create a new account or link an existing one:

If you have an account already, click the sign in button:

The only thing you need to know is your username. Enter it, and hit the link account button:

As you can see, you are now being asked to open the Fission Auth page on your other device. This might be your other computer or perhaps your phone. There is also a short message telling us that this is for the boris0902 username.

Once you open the Fission Auth page on your other device, it will detect the linking request and display a page like this.

The new device you are linking should show the same numbers:

Since we can see the numbers are the same, we can go ahead and hit the "Approve" button, and you'll see this success message.

Switching to the new device you were linking, you'll see this message:

Now you can use either device with full authorization

And yes, this works on mobile too:

Command Line Linking

The Fission CLI is a developer tool for working with apps and managing your account on the Fission platform.

Structure

The Fission CLI uses multipart commands with the structure:

Commands group related subcommands into operations on apps or accounts. Options extend functionality or display help information.

Shortcuts combine a command and subcommand into a shortcut command:

The options that would apply to the multipart command also apply to the shortcut.

Help

The --help option displays a quick reference at any command level.

At the top level, fission --help displays a high-level summary of all commands and shortcuts.

Use fission setup, fission user whoami, and fission login to set up your account, display your username, and link your account in web browser.

Setup a new user

The fission setup command registers your account with Fission or links to your existing Fission account.

When you register a new account, you will be prompted for a username and an email. Fission will send you an email to confirm your account and complete your registration.

The fission setup command will create a global config.yaml file in your ~/.config/fission directory. See the guide for more information about the config.yaml file.

Display user information

Use fission user whoami to display your username.

Linking a web browser

You can link your Fission account in a web browser to interact with Fission-enabled apps. The fission login command sets up the CLI to listen for requests to link your account.

The browser window and command line will display confirmation codes. Verify that the confirmation codes match and grant access at the command line.

The browser window will update to show that you have successfully linked your account.

Linking from a web account

If you are signed into a Fission account in a web browser, you can link your account and use it at the command line.

Use fission setup to create and link a CLI user at your command line.

When prompted, enter Y to confirm you have an account and enter your username from the browser window. The auth lobby and CLI will display a confirmation code.

When you have confirmed that the codes match, approve in the browser, and the CLI will complete the setup process and link your account.

Setup with an existing key

You can set up your machine with an existing account if you have the machine_id.ed25519 key. Use --with-key argument and the path to your key.

Installing the Fission CLI

The Fission command line interface (CLI) is the most common way for developers to interact with Fission services.

macOS with Homebrew

Use the Homebrew recipe to install the CLI on macOS. This taps and installs in one command:

You can also follow the next section for a manual install on macOS.

Linux and Manual Installation

Head over to our page on Github and download the latest release for your operating system.

Grant execute permissions and move the binary onto to your PATH. For example, on Ubuntu 20.04:

That's it! Double check that it's installed correctly.

If you run into any problems, check that you have libssl1.1 (installed with OpenSSL) and libtinfo5 (or libtinfo6). Most recent Linux distributions will already have these libraries installed.

On macOS, you will also need libcrypto1.1 installed and linked on your system, which should be available from OpenSSL.

Upgrading the CLI

Run fission --version to check if you are using an old version of the CLI.

To upgrade the CLI on macOS, brew uninstall and brew untap to reset brew.

Reinstall with brew tap and brew install.

Fission stores global and app configuration options in YAML files. The global configuration is stored in a config.yaml file and app configurations are stored in fission.yaml files.

Global Fission YAML

After you run fission user setup, you will have a global config.yaml in your ~/.config/fission/ folder. You can open config.yaml in a text editor or display it at the command line.

The default global config.yaml will looks something like this:

ignore

Ignore is a list of files you don't want fission app publish to publish. For example, you might add commonly ignored files and secrets.

Ignore follows the same conventions used in a .gitignore file.

username

Username is a name you select for yourself during fission setup.

root_proof

The UCAN that was used to link from another device or browser. null if the account was created on this device.

server_did

Server DID is the identity of the Fission server that authenticates your requests when using the Fission CLI.

peers

We configure your machine to directly connect to our servers. The peers are the IP addresses and fingerprints of our servers.

update_checked

Timestamp of the last check for an updated version of the CLI.

signing_key_path

The path to the key used to sign requests made when using the Fission CLI.

Fission YAML for Apps

When you create a new app with fission app register, a fission.yaml file is created in the directory where you ran the command. The default fission.yaml file looks something like:

ignore

Ignore works the same as the ignore in the global configuration. You can use it to list files that you do not want to publish.

You might use it to ignore a directory like node_modules or all files with an extension like Photoshop .psd files.

url

The URL where your app is viewable after it has been published.

build

The build directory is the directory the Fission CLI will publish. Use this when you have a build step that produces a production-ready version of your application.

The build directory is set as a relative path from the location of the fission.yaml file.

Use the fission app command and its subcommands to work with apps. The main operations are registering an app, publishing an app, and displaying information about an app.

Register an app

The fission app register command initializes a new app and links it to your Fission account.

You will be prompted for a build directory. The Fission CLI will publish your app from the build directory you select.

If you are using a common build directory, the Fission CLI will detect it when you run fission app register and suggest it. You accept the suggestion or enter another build directory as a relative path from the fission.yaml file.

The Fission CLI will create a fission.yaml configuration file with a list of files to ignore, a URL where your app will be viewable after it is published, and a build directory. See the for more information about the fission.yaml file.

The fission app register command has advanced options:

Publish an app

Use the fission app publish command to publish your app to the web. Run this command from the directory that contains your app's fission.yaml configuration file.

The fission app publish command publishes your app and associates it with the URL in the fission.yaml file. After your app is published, the Fission CLI will output a success message and the URL for your app.

The fission app publish command has advanced options:

Continuously Update an App with Watch

You can continuously publish your app by adding the --watch option. The Fission CLI will watch your build directory and publish whenever it detects a change.

This means that as you work in your local development environment, changes are continuously streamed online as you save. Note that some development environments have different code and output options than "production", but this will allow you to quickly and easily share a live online version with other people.

Display information about an app

Use fission app info to display the URL where your app is viewable.

What is Fission?

Fission powers next generation app publishing.

For developers, they can design a user app using only front end and design skills. The web native app can be installed by 10 or 10,000 users, just like mobile or desktop software. Because the app is running on the user's computer, you can focus on finding new users and adding new features, rather than having to learn DevOps or server scaling.

People using apps create a secure identity in their browsers. Every Fission account is linked to a file system, available in any browser. Much like an open source iCloud, users give permissions to apps, and can access their files from anywhere. Users can browse their file system, both public and private, and mix and match which apps they use, just like they're used to with mobile and desktop apps.

Developers

Get started by installing the Fission CLI »

Users

Learn more about Fission Accounts, and try one out by installing the Drive app »

You can add the webnative SDK to a project by loading it from a CDN or installing it with a package manager.

CDN

For prototyping or experimentation, you can use the latest version of the SDK.

<script src="https://unpkg.com/webnative@0.26.1/dist/index.umd.min.js"></script>

We recommend linking to a specific version in production to avoid unexpected changes.

Package Manager

We recommend installing with a package manager for larger projects that use build tools or bundlers.

Install the SDK with npm or your preferred package manager.

npm install webnative

Import the SDK in your application.

// ES6
import * as wn from 'webnative'

// Browser/UMD build
const wn = self.webnative

Webnative uses directory and file paths built from path segments by path functions.

// creates a directory path equivalent to "public/some/directory/"
const publicDirectoryPath = wn.path.directory("public", "some", "directory")

// creates a directory path equivalent to "private/some/directory/"
const privateDirectoryPath = wn.path.directory("private", "some", "directory")

// creates a file path equivalent to "public/some/file"
const publicFilePath = wn.path.file("public", "some", "file")

// creates a file path equivalent to "private/some/file"
const privateFilePath = wn.path.file("private", "some", "file")

// wn.path.Branch.Private is an alias for "private"
const privateHelperPath = wn.path.file(wn.path.Branch.Private, "some", "file")

// wn.path.Branch.Public is an alias for "public"
const publicHelperPath = wn.path.file(wn.path.Branch.Public, "some", "file")

All webnative SDK methods expect paths created by path functions. See the path API documentation for more path utility functions.

A native arm64 version of the Fission CLI is not yet available. When support is ready in the Haskell compiler, we will ship native binaries. In the meantime, the Fission CLI runs under "Rosetta 2" emulation. To get this working:

Ensure Rosetta 2 is installed:

softwareupdate --install-rosetta

Install the x86_64 version of homebrew:

arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

This will install a separate version of homebrew in /usr/local for x86_64 tools. Finally, Install the Fission CLI via:

arch -x86_64 /usr/local/bin/brew install fission-suite/fission/fission-cli

The Fission CLI will now be available at /usr/local/bin/fission

Every Fission App gets a free subdomain.

Currently, these look like YOURUSERNAME.fission.name, but we're migrating to user accounts and attached apps, where every app has YOURAPPNAME.fission.app.

To use a custom domain of your own, like YOURAPPDOMAIN.com, you need to make some changes to DNS. There are two methods detailed in the following pages:

1. - move your nameservers to Fission, we automate everything

2. - create a CNAME and TXT record and point them at Fission services

The Web Native File System (WNFS) is a file system built on top of the InterPlanetary File System (IPFS). Each Fission user has their own WNFS, and apps store user files and data in it when granted permission.

Each file system has a public tree and a private tree, much like your macOS, Windows, or Linux desktop file system. The public tree is "live" and publicly accessible on the Internet. The private tree is encrypted so that only the owner can see the contents.

All information (links, data, metadata, etc.) in the private tree is encrypted. Decryption keys are stored so that access to a given directory grants access to all of its subdirectories.

WNFS is structured and functions similarly to a Unix-style file system, with one notable exception: it's a Directed Acyclic Graph (DAG), meaning that a given child can have more than one parent (think symlinks but without the "sym").

Permissions

Every file system action checks if an app has received sufficient permissions from the user. Apps request permissions when they initialize webnative. The .

Apps request permission for app storage, additional private and public directories, and user apps published with the Platform APIs. For example, a notes app might request these permissions.

The app would have access to its dedicated app storage and public and private Notes directories.

Apps request permissions.app to store user data in a default app storage directory and other public and private directories. Webnative creates these directories for your app if they do not already exist.

The initialize function will return a NotAuthorised scenario if one of the UCAN will expire in one day to minimize the likelihood of receiving an expired permissions error. But to be safe, apps should also account for this error.

WNFS

WNFS exposes a POSIX-style interface:

• add: add a file

• cat: retrieve a file

• exists: check if a file or directory exists

• ls: list a directory

• mkdir: create a directory

• mv: move a file or directory

• read: alias for cat

• rm: remove a file or directory

• write: alias for add

Publish

The publish function synchronizes your file system with the Fission API and IPFS. WNFS does not publish changes automatically because it is more practical to batch changes in some cases. For example, a large data set is better published once than over multiple calls to publish.

Returns: CID the updated root CID for the file system.

API Summary

Methods

Methods for interacting with the filesystem all use absolute paths.

The FileContentthat WNFS can store includes FileContentRaw, Blob, string, number, and boolean. FileContentRaw is Uint8Array. In addition, the private file system can store Objects.

add

Adds file content at a given path.

Params:

• path: FilePath required

• content: FileContentrequired

Returns: CID the updated root CID for the file system

Example:

cat

Retrieves some file content at a given path.

Params:

• path: FilePath required

Returns: FileContent

Example:

exists

Checks if there is anything located at a given path.

Params:

• path: DistinctivePath required

Returns: boolean

Example:

get

Retrieves the node at the given path, either a File or Tree object

Params:

• path: DistinctivePath required

Returns: Tree | File | null

Example:

ls

Returns a list of links at a given directory path

Params:

• path: DirectoryPath required

Returns: { [name: string]: Link } Object with the file name as the key and its Link as the value.

Example:

mkdir

Creates a directory at the given path

Params:

• path: DirectoryPath required

Returns: CID the updated root CID for the file system

Example:

mv

Move a directory or file from one path to another.

Params:

• from: DistinctivePath required

• to: DistinctivePath required

Returns: CID the updated root CID for the file system

Example:

rm

Removes a file or directory at a given path.

Params:

• path: DistinctivePath required

Returns: CID the updated root CID for the file system

Example:

write

Alias for add.

Params:

• path: FilePath required

• content: FileContent required

Returns: CID the updated root CID for the file system

Example:

Versioning

Each file and directory has a history property, which you can use to get an earlier version of that item. We use the delta variable as the order index, primarily because the timestamps can be slightly out of sequence due to device inconsistencies.

The webnative platform API provides methods to work with the apps associated with users.

The platform API makes it possible to manage user apps and, combined with the webnative filesystem methods, create and manage apps entirely from the browser.

The API methods are prefixed with apps.

• apps.index: A list of all of your apps and their associated domain names

• apps.create: Creates a new app, assigns an initial subdomain, and sets an asset placeholder

• apps.publish: Publish a new app version

• apps.deleteByDomain: Destroy an app identified by domain

Permissions

Apps that use the platform API must request permission to work with a user's apps. Permissions are requested when a user signs in through the Fission Auth Lobby. See the for more on the webnative authentication flow.

Platform API permissions are requested at permissions.platform.apps in the initialization object.

The value at permissions.platform.apps can be

• "*": Grant complete app management access for all of the user's apps

• An array of domain names, e.g. [ "an-app.fission.app", "another-app.fission.app" ]: Grant permission to manage specific apps. Those apps can be published or deleted.

API

apps.index

Lists all user apps and their associated domain names.

Required permissions: { platform: { apps: "*" } } full app management permissions

Params: No parameters

Returns: { domain: string }[] an array of app domains

Example:

apps.create

Creates a new app, assigns an initial subdomain, and publishes a placeholder site.

Required permissions: { platform: { apps: "*" } } full app management permissions

Params:

• subdomain: string optional

Returns: { domain: string } the subdomain of the newly created app

Example:

apps.publish

Publishes a new app version by IPFS CID. If the app does not exist yet, create the app first with apps.create.

Params:

• domain: string required

• cid: string required

Returns: Nothing returned

Example:

Retrieving the CID depends on where you have staged the app code. One convenient way to do this is to publish the app's HTML, CSS, JavaScript, and assets to a public directory in WNFS and retrieve the CID of that directory.

apps.deleteByDomain

Delete an app by domain.

Params:

• url: string required

Returns: Nothing returned

Example:

Debugging

Version

Check the webnative version.

Debug Logs

Add the following to your code to enable webnative debug logging.

When webnative makes a change to the user's filesystem, it logs:

Next, webnative links the change to make it available across the web.

When linking completes, the change is published and available to other browsers.

Forcing a Logout

While you are testing an app, you may want to force a logout to check the NotAuthorised authentication state. The wn.leave() method will log out and completely remove a user from your app. The user will still be authenticated with Fission, and they can sign back into your app to re-authorize.

WNFS File System Roots

WNFS comes with three separate top-level file systems "roots": public, pretty, and private.

Public

Not encrypted. Full metadata support. Starts with /public.

Pretty

Not encrypted. No metadata. Represented simply as /p to be nice and short when creating public URLs like /p/path/to/file.img. It does not support versioning, use the Public or Private trees for that.

Private

Encrypted. Structured so that file metadata as well as contents are obscured. Starts with /private.

Default folders

We initialize WNFS with a set of default private folders, which should be familiar to people from working with desktop operating systems.

Additionally, in apps like Drive or in file pickers, the user sees a top level Public folder, which maps to the Public system root

Web Worker

Can I use my file system in a web worker? Yes, this only requires a slightly different setup.

Versions

Since the file system may evolve over time, a "version" is associated with each node in the file system (tracked with semver).

Currently two versions exist:

• 1.0.0: file tree with metadata. Nodes in the file tree are structured as 2 layers where one layer contains "header" information (metadata, cache, etc), and the second layer contains data or links. This is the default version, use this unless you have a good reason not to.

• 0.0.0: legacy bare file tree of an early version.

Customization

Customization can be done using the setup module. Run these before anything else you do with the SDK.

Building Blocks

Warning: Here be 🐉! Only use lower level utilities if you know what you're doing.

You can use one instance for your whole application by doing the following:

By using Cloudflare as your DNS provider and their , you can deploy on Fission but have your content be served by Cloudflare. This will let you use custom domains with your Fission apps while we work to automate the process fully on the platform.

Add a CNAME pointing to Cloudflare's IPFS gateway

For your domain, YOURAPPDOMAIN.com, go into your DNS provider control panel and add a CNAME pointing to cloudflare-ipfs.com.

Since your domain is already hosted with Cloudflare, there's no step two: they'll add SSL support to it automatically, and turn off proxying.

Add a TXT record with dnslink

Now, add a TXT record pointing to your app subdomain. Your APPNAME is created when you run fission app register, and will look something like junior-angular-tulip . We're creating a link to say that the content from that app should be served up at your domain with a special dnslink record:

That's it, you're done!

Whenever you publish a new version of your Fission app, we update the hash that this special record points to. When you go to YOURAPPDOMAIN.com, Cloudflare's gateway looks up this _dnslink record, checks the ipns record, gets the hash, and fetches the content from the global IPFS network. This might even be from your computer directly.

Authentication

Users authenticate once per browser in the . If the user is new to Fission, they are prompted to sign up. They may also link an existing account from another browser.

Apps redirect users to the Auth Lobby to sign up and request authorization to use resources. Sign-up only happens once, and each subsequent visit from any app is for authorization only.

Authorization

The Auth Lobby grants apps authorization to access WNFS. Apps request permission to use app-specific storage and additional public and private directories. The Auth Lobby creates a User Controlled Authorization Networks (UCAN) token that reflects the requested permissions.

Webnative checks the UCAN at initialization and returns an auth scenario.

• AuthSucceded. The user has just returned from the Auth Lobby, and they granted the requested permissions.

• Continuation. The user has already granted permission, and the UCAN has not expired.

• AuthCancelled. The user denied the requested permissions.

• NotAuthorised. The user has not granted permission yet or the UCAN has expired.

UCANs expire and users must periodically re-authorize apps through the Auth Lobby. All user data is preserved in WNFS across authorizations, including the data stored in App Storage.

Initialization

Shared Devices

One case where logging out is desirable is on a shared device. Logging out on a shared device can be accomplished in two steps:

• Remove the UCAN token from apps that were granted permissions with the webnativewn.leave function

Fission makes it easy to build and host web apps using only frontend and local development tools with no effort put into servers or deployment workflows.

In this guide, we will use the Fission CLI to publish the elm-pages-starter to the web.

Publish the elm-pages-starter

Clone the elm-pages-starter to your local development environment.

Install and build the app.

Once the elm-pages-starter is built, we are ready to publish it with Fission.

Initialize the project as a Fission app with fission app register. You will be prompted for a build directory.

Accept dist as your build directory, and fission will initialize your app.

Fission has created a fission.yaml file with your app configuration.

Run fission app publish to publish the webpage.

Copy the URL into your browser and you will see the elm-pages-starter live on the web!

You can continuously update the hosted version of the app by running fission app publish --watch. Fission will watch the files in dist and publish when changes occur.

Learn more

We have put the elm-pages-starter out on the web without setting up a DevOps environment or going through a complex deployment workflow!

At this point your mind might be swimming with a thousand questions. Here are a couple of resources that explain how this all works:

In the next section, we will add Fission auth to the elm-pages-starter.

By adding a TXT record for your app and a CNAME pointing at our gateway, you can run your DNS elsewhere but still have a custom domain for your Fission app.

Add a CNAME pointing to ipfs.runfission.com

For your domain, YOURAPPDOMAIN.com, go into your DNS provider control panel and add a CNAME pointing to ipfs.runfission.com.

The process for a subdomain is the same SUB.YOURAPPDOMAIN.com, but looks a little different. Go into your DNS provider control panel and add a CNAME pointing to ipfs.runfission.com.

Add a TXT record with dnslink

Now, add a TXT record pointing to your app subdomain. Your APPNAME is created when you run fission app-init, and will look something like junior-angular-tulip . We're creating a link to say that the content from that app should be served up at your domain with a special dnslink record:

Again, subdomains function the same way, with the _dnslink subdomain, where you're adding the TXT record being "above" the SUB.YOURDOMAIN.com record, which looks like this:

Get in touch to complete the process

Webnative

Version 0.24

The way paths are used throughout the webnative and filesystem APIs has changed.

In earlier versions of webnative, API calls expected UNIX style paths.

In webnative 0.24, paths are created by for files and directories.

The docs for the remain available for reference.

Version 0.26.0

The URL for loading webnative from UNPKG has changed. In previous versions, webnative was available as index.umd.js.

In webnative 0.26, webnative is available as index.min.js.

Version 0.26.1

The URL for loading webnative from UNPKG has changed. In webnative 0.26.0, webnative was available as index.min.js.

We found that some projects needed the UMD build and brought it back in webnative 0.26.1. We have replaced index.min.js with index.umd.min.js.

We can take care of this for you by hosting your DNS for you. This means changing your name servers to the Fission ones. Below are guides for some DNS providers.

Fission Nameservers

• ns1.fission.systems

• ns2.fission.systems

• ns3.fission.systems

• ns4.fission.systems

Once this is completed, we'll confirm it and handle any other updates needed automatically.

Changing Nameservers in Namecheap

Go to the domain you want to host on Fission in your Namecheap admin:

Where it says "Namecheap BasicDNS", select "Custom DNS" from the drop down:

Enter in ns1.fission.systems and ns2.fission.systems and click the green check mark to save.

We're developing a series of example apps, base templates, and code examples to help you get up to speed in building Fission-powered apps. The is also a great place to look for inspiration.

Elm

that goes from basic publishing through to adding auth and storage.

The Quotes app is a simple app written in Elm. It features Fission login, and stores quotes data in your personal storage.

• Try it live at

• Browse the source on Github

Fission Drive is maintained by the Fission team and included with every Fission account. It lets you work with all of the files in your account's file system.

• Read more about

• Login at

• Browse the source on Github

WebAssembly

, and also teaches you about using WebAssembly.

React

Photo Gallery

Notes

The foundation of powerful digital applications roughly include three primary building blocks: compute, storage, and identity. Fission's approach is to make use of these building blocks, make them easier to use for developers, and to develop strong default capabilities in each of these areas.

The Fission White Paper can be read for a more technical, specification-style version of our vision and roadmap, including direct links to various sections:

• WinFS File System

• DID-based identity, UCAN + JWTs

Additional reading and presentations are also available:

• User Controlled Authorization Network (UCAN), Auth without a Backend blog post

• Presentation to the Berlin Functional Programming Meetup June 2020, A Universal Hostless Substrate: Full Stack Web Apps Without a Backend, and More!

• Web Native File System Technical Design Overview, Aug 2020 slide deck and recorded video presentation

Compute

Web browsers run on your local desktop, laptop, or mobile device, and use local computer processing unit (CPU) to do work -- to compute things. Your machine provides the work to run apps in your browser. Simple web pages use the browser's built in HTML and CSS capabilities. But many web pages are full blown "apps" that are highly interactive, with a rich user interface (UI). These are typically powered by JavaScript, a programming language that runs in your browser, and uses your local compute.

Web Assembly is a fourth compute environment has been standardized for browsers. It can compute apps that are originally written in many different programming languages, not just JavaScript. We are just starting to see powerful Web Assembly apps being built, like Figma, which provides a PhotoShop-like experience in your web browser.

Fission intends to support Web Assembly, and make it easier to build, host, and scale web native apps that include Web Assembly.

Storage

When people think about owning their data, this often reveals that they feel comfortable when they can see and browse the files that an app uses or creates, rather than having to request an export, or not even have access to their data at all.

At Fission, we started by designing a file system that is available to both developers who want to build and host apps, and the people who use these apps.

We have designed what we call Web Native File System, pronounced and written as WinFS. It is built on top of other open protocols, including the InterPlanetary File System (IPFS).

We intend to design and share the WinFS specification in the open, and contribute it as an open standard, with open source implementations that anyone can use.

WinFS is designed to provide an experience like an open source iCloud: available and synchronized across all devices and provide both public and private, encrypted files.

Identity

Implementing a login, authentication, and authorization system is challenging to do securely, especially while respecting user privacy, providing end to end encryption, and otherwise balancing ease of use for both developers and customers.

For developers, we wanted to provide a built in way to include logins and authentication without having to struggle to implement it.

For everyone, we wanted it to be easy to login securely, without having to remember passwords, and make that login available on all of their devices.

We built on top of the emerging Decentralized Identifiers (DIDs), which is a working draft of the W3C standards body.

We then designed the User Controlled Authorization Network (UCAN): a way of doing authorization where users are fully in control.

With UCAN, we based it on top of the developer friendly JSON Web Tokens (JWTs) standard, plus Google's Macaroons research paper for more distributed systems.

We combine all of this in the webnative SDK for developers and the Fission platform for app users. In browsers, we use the Web Cryptography API, a W3C standard. The MDN Web Docs include further reading »

We intend to work with existing and emerging authorization and identity standards bodies to contribute our work as open standards.

Further Reading

The Introduction to Web Native Apps post on our blog covers a lot of the same material from a conceptual point of view.

We are inspired by the work of the Ink & Switch research lab, especially their April 2019 publication on Local First Software, which includes their Seven Ideals for local-first Software:

1. No spinners: your work at your fingertips

2. Your work is not trapped on one device

3. The network is optional

4. Seamless collaboration with your colleagues

5. The Long Now

6. Security and privacy by default

7. You retain ultimate ownership and control

Basic example of how to make a UCAN. Note that the issuer always has to be your DID, because the UCAN will be signed with your private key.

import * as wn from "webnative"

// DIDs
const ourDID = await wn.did.ucan()
const otherDID = "did:key:EXAMPLE"

/**
 * This can be another UCAN which has a bigger, or equal,
 * set of permissions than the UCAN we're building later.
 */
const possibleProof = null // or, other UCAN.

/**
 * The UCAN, encoded as a string.
 */
const ucan = await wn.ucan.build({
  audience: otherDID,
  issuer: ourDID,
  lifetimeInSeconds: 60 * 60 * 24, // UCAN expires in 24 hours
  proof: possibleProof
})

We are committed to making Web Native and the Fission platform work on desktop and mobile browsers without plugins. This is the list of browsers we aim to support.

Alternative browsers (e.g. Brave, Microsoft Edge) are supported on a best effort basis.

Desktop

Windows

• Chrome

• Firefox

MacOS

• Safari

• Chrome

• Firefox

Linux

• Chrome

• Firefox

Mobile

Safari on iPhone iOS / iPad iPadOS

Embedded Webviews in apps may or may not work, as it does differ from Safari.

Chrome on Android

Firefox on Android

Browser APIs

Fission relies on modern browser API features

• Web Cryptography API https://www.w3.org/TR/WebCryptoAPI/

The webnative software development kit offers tools for:

• Auth. Users make an account and link their account across devices in the Fission Auth Lobby.

• Storage. The webnative file system (WNFS) stores user data for apps.

• UCAN and DID tools for working with UCANs and distributed identities

• Platform APIs for interacting with user apps

Storing WebAssembly Modules

In this guide, we will show how to store WebAssembly modules in Fission web native storage. Our goal will be to store a WASM module and execute it at a later time.

The code in this guide is available in the fission-stored-wasm-example repository and the example is published at quick-enormous-silicon-dinosaur.fission.app.

We have compiled an add function from C to a WASM module.

  int add(int x, int y)
  {
    return x + y;
  }

Our example app will make a GET request for add.wasm and store it in web native storage. We will list the contents of the directory where the module is stored to confirm it is there. Finally, we will load the module from storage and add some numbers!

Authenticate the user

Before we can store a WASM module, we need to initialize webnative and ask the user for permission to use their web native file system. This example asks for permission to use app storage and uses fs as an alias for the file system after we initialize.

let fs;

const fissionInit = {
  permissions: {
    app: {
      name: 'fission-wasm-example',
      creator: 'bgins'
    }
  }
};

We pass fissionInit to webnative and get back a state that tells us if the user has authenticated or not.

webnative.initialize(fissionInit).then(async state => {
  switch (state.scenario) {
    case webnative.Scenario.AuthSucceeded:
    case webnative.Scenario.Continuation:
      fs = state.fs;

      // Show the previous result if we have one
      const resultPath = fs.appPath(webnative.path.file('results', 'add'));
      if (await fs.exists(resultPath)) {
        const stored = JSON.parse(await fs.read(resultPath));
        revealStoredResult(stored);
      }

      dom.hide('loading-animation');
      dom.reveal('store');
      break;

    case webnative.Scenario.NotAuthorised:
    case webnative.Scenario.AuthCancelled:
      dom.hide('loading-animation');
      dom.reveal('auth');
      break;
  }

In the AuthSucceeded and Continuation cases, the user gave our app permission to use their file system. Otherwise, they have not been asked or they declined.

The user may have already stored add.wasm and used it to add numbers on a previous visit, so we check and display a stored result if we have one.

If the user has not authenticated, we show them a Sign In button that will redirect them to the Fission auth lobby.

    webnative.redirectToLobby(state.permissions);

Request and store the module

After authentication, we are ready to request add.wasm and store it in web native storage.

  const store = async () => {
    dom.reveal('loading-animation');

    fetch('add.wasm').then(response =>
      response.arrayBuffer().then(async buffer => {
        if (fs) {
          const path = fs.appPath(webnative.path.file('wasm', 'math', 'add.wasm'));
          const blob = new Blob([buffer], { type: 'application/wasm' });
          await fs.write(path, blob);
          await fs.publish();

          dom.hide('store-button-row', 'loading-animation');
          dom.reveal('list');
        }
      })
    );
  };

We fetch add.wasm and stream the Response into an ArrayBuffer. It will be stored as a Blob in app storage at the path wasm/math/add.wasm.

We prepare a path and blob, write the blob to the local file system, and publish it to the user's wider file system across the web. After we publish, the module is available on any device where the user has set up web native storage.

List directory contents

Next, we can check to make sure the module has been saved in storage.

    if (fs) {
      const directoryPath = fs.appPath(webnative.path.directory('wasm', 'math'));
      const directoryListing = await fs.ls(directoryPath);
      Object.keys(directoryListing).forEach(function (key) {
        appendRow(directoryListing[key]);
      });

      dom.hide('list-button-row');
      dom.reveal('contents');
    }

This time we prepare a wasm/math path for the directory and call fs.ls to list its contents. We take each entry in the directory listing and append its metadata to a table.

Each entry has a name, size (in bytes), last modified time, and a flag indicating whether it is a file or directory.

Load and use the module

The module is in storage and we are ready to use it! Each time a user submits lhs and rhs numbers, we load add.wasm and add their numbers.

    if (fs) {
      if (!Number.isNaN(lhs) && !Number.isNaN(rhs)) {
        const path = fs.appPath(webnative.path.file('wasm', 'math', 'add.wasm'));
        if (await fs.exists(path)) {
          const buffer = await fs.read(path);
          WebAssembly.instantiate(buffer).then(async wasmObject => {
            const result = wasmObject.instance.exports.add(lhs, rhs);
            dom.updateFirstChild('result', result);

            const resultPath = fs.appPath(webnative.path.file('results', 'add'));
            const computation = { lhs, rhs, result };
            await fs.write(resultPath, JSON.stringify(computation));
            await fs.publish();

            dom.reveal('everywhere');
          });
        }
      } else {
        dom.updateFirstChild('result', '🤖🤖💥');
      }

After some input validation, we prepare the wasm/math/add.wasm path, make sure a module exists at that path, and read it into a buffer. We instantiate the WASM module and call the add function off it.

Earlier we mentioned that storing the module makes it available across the web. Why not do the same for our result? We store the result at the path results/add, and now both the module and the last result are available on any device!

Deleting the module and result

We can delete the module and result from storage to reset our example.

    if (fs) {
      const funcPath = fs.appPath(webnative.path.file('wasm', 'math', 'add.wasm'));
      const resultPath = fs.appPath(webnative.path.file('results', 'add'));
      await fs.rm(funcPath);
      await fs.rm(resultPath);
      await fs.publish();

      dom.hide('loading-animation')
      dom.reveal(
        'store',
        'store-button-row',
        'list-button-row',
        'show-run-button-row'
      );
    }

We prepare paths for the module and result and use fs.rm to delete them. Lastly, we publish the deletion to remove them from the wider file system.

Store once, compute once

Storing WASM modules and results means you only need to request a module or perform a computation once. The web native file system will sync modules and results across user devices automatically. This opens up many opportunities to simplify your applications and sync app data across user devices.

Reading this guide gives you a taste of how this all works, but extending this example will take you much further! Here are a couple of suggested exercises that will help you to get started with web native.

• Add a subtraction operation. We have done addition, adding subtraction would be an easy first step. See Compiling C to WebAssembly without Emscripten for help with compiling WASM modules.

• Distributed addition. How about instead of overwriting the result of an addition, we keep a running total across devices?

• Build a calculator. A bit more ambitious, but a calculator app that stores state across devices would be so cool!

In this guide, we will add Fission auth to the elm-pages-starter. We will add a login button to the navbar that redirects users to the Fission auth lobby. After a user authenticates in the lobby, we will log them in and display their Fission username.

All of the code in this guide is available in the fission-elm-pages-starter repository on the auth branch.

Before authentication, our header has a Fission login button.

After authentication, we show a username next to the button.

We will use the Fission webnative package to authenticate users. Our Elm app will request a login over an outgoing port and subscribe to authentication changes over an incoming port.

Users own their data. All Fission services are designed on the principle that users should own their data. When users own their identity, developers no longer need to maintain user accounts and authentication becomes simple to implement. See Compute, Storage, and Identity Foundations in our guide for more information on identity.

Add username and login

Our login button will be added to Layout.elm, but we will start by adding our authentication logic and state in Main.elm.

Let's start by adding a username to our model.

type alias Model =
    { username : Maybe String }


init : ( Model, Cmd Msg )
init =
    ( { username = Nothing }
    , Cmd.none
    )

Note that we always start without a username. We will check for an authenticated user after initialization.

Add a SubmittedLogin message for when a user clicks the login button and a GotAuth message to respond to authentication changes.

type Msg
    = SubmittedLogin
    | GotAuth (Maybe String)


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        SubmittedLogin ->
            ( model
            , login ()
            )

        GotAuth maybeUsername ->
            ( { model | username = maybeUsername }
            , Cmd.none
            )

Add an outgoing login port and an incoming onFissionAuth port.

port login : () -> Cmd msg


port onFissionAuth : (Json.Decode.Value -> msg) -> Sub msg

Add a subscription to onFissionAuth.

subscriptions : Model -> Sub Msg
subscriptions _ =
    onFissionAuth
        (\val ->
            Json.Decode.decodeValue authDecoder val
                |> Result.toMaybe
                |> GotAuth
        )


authDecoder : Json.Decode.Decoder String
authDecoder =
    Json.Decode.field "username" Json.Decode.string

We expect JSON that should look something like { username: "fission-username" }. After decoding the value, we call GotAuth with a Just username on success or Nothing on failure.

⚠️ Nothing on failure? In a real application, we would want to add error reporting and handling. We silently fail here to keep our example simple.

Add the login button

Our model, update, and subscriptions are ready to go! Now let's add the login button to the navbar.

In Main.elm, pass the SubmittedLogin message and model.username to Layout.view

Layout.view
    (pageView model siteMetadata page viewForPage)
    page
    { loginMsg = SubmittedLogin, username = model.username }

In Layout.elm, modify view to accept the new parameter and call it fissionAuth.

view :
    { title : String, body : List (Element msg) }
    ->
        { path : PagePath Pages.PathKey
        , frontmatter : Metadata
        }
    ->
        { loginMsg : msg
        , username : Maybe String
        }
    -> { title : String, body : Html msg }
view document page fissionAuth =
    { title = document.title
    , body =
        Element.column
            [ Element.width Element.fill ]
            [ header page.path fissionAuth
            ...
    }

Pass fissionAuth through header to a new fissionAuthButton displayed alongside the Elm docs and GitHub links.

, Element.row [ Element.spacing 15 ]
    [ fissionAuthButton fissionAuth
    , elmDocsLink
    , githubRepoLink
    , highlightableLink currentPath Pages.pages.blog.directory "Blog"
    ]

fissionAuthButton : { loginMsg : msg, username : Maybe String } -> Element msg
fissionAuthButton fissionAuth =
    Element.Input.button
        []
        { onPress = Just fissionAuth.loginMsg
        , label =
            Element.row
                [ Element.spacing 2
                , Font.size 18
                ]
                [ Element.image
                    [ Element.width (Element.px 26)
                    ]
                    { src = ImagePath.toString Pages.images.fission
                    , description = "Login with Fission"
                    }
                , case fissionAuth.username of
                    Just username ->
                        Element.text username

                    Nothing ->
                        Element.none
                ]
        }

We call SubmittedLogin when a user clicks the fissionAuthButton and display their username if they are logged in.

Add webnative auth

All of our Elm code is written and we only need a small bit of JavaScript to authenticate users with Fission.

Our desired authentication flow looks like this:

1. A user clicks on the Fission button

2. They authenticate in the Fission auth lobby

3. They are redirected back to our page in an authenticated state

4. The next time they visit our site, they should already be authenticated

Let's start by installing the webantive package from npm.

npm install webnative

Import it in index.js.

import * as webnative from 'webnative';

After our Elm app is initialized, we can bring webnative together with our login and onFissionAuth ports to authenticate users.

const fissionInit = {
  permissions: {
    app: {
      name: 'fission-elm-pages-starter',
      creator: 'bgins'
    }
  }
};

pagesInit({
  mainElmModule: Elm.Main
}).then(app => {
  webnative.initialize(fissionInit).then(async state => {
    switch (state.scenario) {
      case webnative.Scenario.AuthSucceeded:
      case webnative.Scenario.Continuation:
        app.ports.onFissionAuth.send({ username: state.username });
        break;

      case webnative.Scenario.NotAuthorised:
      case webnative.Scenario.AuthCancelled:
        break;
    }

    app.ports.login.subscribe(() => {
      webnative.redirectToLobby(state.permissions);
    });
  });
});

Initializing webnative gives us access to state which has a state.username and a state.scenario. The state.scenario tells us if the user is authenticated or not.

If a user just returned from the Fission auth lobby, state.scenario will be webnative.Scenario.AuthSucceeded. If they authenticated on a previous visit, state.scenario will be webnative.Scenario.Continuation. In both cases, we have a state.username to pass through the onFissionAuth port.

The login port calls on webnative to redirect the user to the Fission auth lobby. When the user returns from the lobby, we will initialize and check authentication status all over again.

Authentication complete 🤖

That's it! User identity is held by your users in browser storage and you won't need a backend to manage it. A user that has authenticated with Fission also has a webnative file system where your app can store their data. In the next section, we will show how to use it.

Here are a couple of resources on Fission auth for a deeper dive into how this all works:

• UCAN: Authorizing Users Without a Back End

• Accounts section in Fission whitepaper

Adding storage to an elm-pages app

In this guide, we will show how to use Fission webnative storage to save user data. Our goal will be to add annotations to blog posts in the elm-pages-starter.

All of the code in this guide is available in the fission-elm-pages-starter repository on the storage branch.

When a user has signed in with Fission, an annotation button is displayed at the bottom right corner of the page.

Clicking the button opens a text input box where the user can write their notes.

If a user has not signed in, they do not see the annotation button or text input box.

Annotations are saved to the user's webnative filesystem and will be there when they return or use the app on another device.

Write an annotation module

We will start off by writing an annotation module. Annotation.elm is built around an Annotation type and has a way to create, encode, and view annotations.

An Annotation can be editable or not. If an annotation is editable, it has a title and notes.

type Annotation
    = Editable Internals
    | NotEditing


type alias Internals =
    { title : String
    , notes : String
    }

We have two ways of creating an annotation. A NotEditing annotation can be created directly. An Editable annotation must be created from a Value that will come over a port.

notEditing : Annotation
notEditing =
    NotEditing


fromValue : Value -> Annotation
fromValue val =
    case Json.Decode.decodeValue internalsDecoder val of
        Ok internals ->
            Editable internals

        Err _ ->
            NotEditing

internalsDecoder : Decoder Internals
internalsDecoder =
    Json.Decode.map2 Internals
        (Json.Decode.field "title" Json.Decode.string)
        (Json.Decode.field "notes" Json.Decode.string)

Our code that interacts with the webnative filesystem will use blog post titles as keys to lookup and save annotations.

Add encode for storing annotations and encodeTitle for loading them.

encode : Annotation -> Json.Encode.Value
encode annotation =
    case annotation of
        Editable internals ->
            Json.Encode.object
                [ ( "title", Json.Encode.string internals.title )
                , ( "notes", Json.Encode.string internals.notes )
                ]

        NotEditing ->
            Json.Encode.null


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

Lastly, we need a way to view annotations. When a user is editing an annotation, we show their notes or the blog post title as a placeholder. When an annotation is not being edited, we show a button with a pencil icon.

Add a view function with a case for Editable and NotEditing annotations.

view :
    { annotation : Annotation
    , title : String
    , onLoadAnnotation : String -> msg
    , onUpdateAnnotation : Annotation -> msg
    }
    -> Element msg
view options =
    case options.annotation of
        Editable annotation ->
            Element.row
                [ Element.alignBottom
                , Element.alignRight
                , Element.padding 30
                ]
                [ Element.Input.multiline
                    [ Element.height (Element.px 150)
                    , Element.width (Element.px 200)
                    , Border.width 2
                    , Border.roundEach { topLeft = 15, topRight = 15, bottomLeft = 15, bottomRight = 0 }
                    , Border.color (Element.rgb 0.5 0.5 0.5)
                    , Element.focused
                        [ Border.color (Element.rgb 0.3 0.3 0.3)
                        , Border.shadow
                            { offset = ( 1, 1 )
                            , blur = 1
                            , color = Element.rgb 0.85 0.85 0.85
                            , size = 1
                            }
                        ]
                    , Font.size 16
                    ]
                    { onChange =
                        \newText ->
                            options.onUpdateAnnotation
                                (Editable
                                    { title = options.title, notes = newText }
                                )
                    , text = annotation.notes
                    , placeholder =
                        Just
                            (Element.Input.placeholder []
                                (Element.text ("Write some notes on " ++ options.title))
                            )
                    , label = Element.Input.labelHidden ("Notes on " ++ options.title)
                    , spellcheck = False
                    }
                ]

        NotEditing ->
            Element.row
                [ Element.alignBottom
                , Element.alignRight
                , Element.padding 30
                ]
                [ Element.Input.button []
                    { onPress = Just (options.onLoadAnnotation options.title)
                    , label =
                        Element.row
                            [ Element.padding 8
                            , Border.width 2
                            , Border.rounded 50
                            , Border.color (Element.rgb 0.3 0.3 0.3)
                            ]
                            [ Element.image
                                [ Element.width (Element.px 30)
                                ]
                                { src = ImagePath.toString Pages.images.annotation
                                , description = "Annotate with Fission"
                                }
                            ]
                    }
                ]

Add annotations

Now that our annotation module is ready, we can add annotations to the elm-pages-starter.

We want the user to see the annotation button when they navigate to a page with a blog post. When they click on the annotation button, we load the annotation from their webnative filesystem or an empty annotation if they are starting a new annotation. We replace the button with the notes in a text input box.

We save the annotation to webnative with each keystroke the user makes in the text input box.

Import the annotation module in Main.elm.

import Annotation exposing (Annotation)

Add an annotation to the Model.

type alias Model =
    { username : Maybe String
    , annotation : Annotation
    }

We only display one annotation at a time, which means we can replace annotation when we navigate to a new page or load an annotation.

The annotation starts off as NotEditing in init.

init : ( Model, Cmd Msg )
init =
    ( { username = Nothing
      , annotation = Annotation.notEditing
      }
    , Cmd.none
    )

Our update will handle four messages that initialize, load, or store annotations. OnPageChange sets the annotation to NotEditing when a user navigates to a new page. LoadAnnotation calls over a port to load an annotation. UpdateAnnotation updates the displayed annotation in the input box and stores the annotation. GotAnnotatation subscribes to annotations that come in over a port after a load.

type Msg
    = SubmittedLogin
    | GotAuth (Maybe String)
    | OnPageChange
        { path : PagePath Pages.PathKey
        , query : Maybe String
        , fragment : Maybe String
        }
    | LoadAnnotation String
    | UpdateAnnotation Annotation
    | GotAnnotation Annotation


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        SubmittedLogin ->
            ( model
            , login ()
            )

        GotAuth maybeUsername ->
            ( { model | username = maybeUsername }
            , Cmd.none
            )

        OnPageChange _ ->
            ( { model | annotation = Annotation.notEditing }
            , Cmd.none
            )

        LoadAnnotation title ->
            ( model
            , loadAnnotation (Annotation.encodeTitle title)
            )

        UpdateAnnotation annotation ->
            ( { model | annotation = annotation }
            , storeAnnotation (Annotation.encode annotation)
            )

        GotAnnotation annotation ->
            ( { model | annotation = annotation }
            , Cmd.none
            )