Additional information

Become a webnative jedi 🧘

Debugging

Version

Check the webnative version.

console.log(wn.VERSION)

Debug Logs

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

wn.setup.debug({ enabled: true })

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

📓 Adding to the CID ledger

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

🌊 Updating your DNSLink

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

🪴 DNSLink updated:

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.

TODO: We'll be documenting and versioning these default folders in the webnative Github repo.

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

More about roots. Learn more about roots in the Fission whitepaper.

Web Worker

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

// UI thread
// `state.fs` will now be `null`
const { permissions } = wn.initialise({ loadFileSystem: false })
worker.postMessage({ tag: "LOAD_FS", permissions })

// Web Worker
let fs

self.onMessage = async event => {
  switch (event.data.tag) {
    case "LOAD_FS":
      fs = await wn.loadFileSystem(event.data.permissions)
      break;
  }
}

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.

// custom api, lobby, and/or user domain
// (no need to specify each one)
wn.setup.endpoints({
  api: "https://my.fission.api",
  lobby: "https://my.fission.lobby",
  user: "my.domain"
})

// js-ipfs options
// (see docs in src for more info)
wn.setup.ipfs({ init: { repo: "my-ipfs-repo" } })

Building Blocks

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

This library is built on top of js-ipfs and keystore-idb. If you have already integrated an ipfs daemon or keystore-idb into your web application, you probably don't want to have two instances floating around.

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

import * as ipfs from 'webnative/ipfs'

// get the ipfs instance that the Fission SDK is using
const ipfsInstance = await ipfs.get()

// OR set the ipfs to an instance that you already have
await ipfs.set(ipfsInstance)

import * as keystore from 'webnative/keystore'

// get the keystore instance that the Fission SDK is using
const keystoreInstance = await keystore.get()

// OR set the keystore to an instance that you already have
await keystore.set(keystoreInstance)