The Webnative SDK empowers developers to build fully distributed web applications without needing a complex back-end. The SDK provides:
Webnative applications work offline and store data encrypted for the user by leveraging the power of the web platform. You can read more about Webnative in Fission's Webnative Guide. There's also an API reference which can be found at webnative.fission.app
// ESM
import * as wn from "webnative"
// Browser/UMD build
const wn = globalThis.webnative
A Webnative program is an assembly of components that make up a distributed web application. Several of the components can be customized. Let's stick with the default components for now, which means we'll be using the Web Crypto API.
const program = await wn.program({
// Can also be a string, used as an identifier for caches.
// If you're developing multiple apps on the same localhost port,
// make sure these differ.
namespace: { creator: "Nullsoft", name: "Winamp" }
}).catch(error => {
switch (error) {
case webnative.ProgramError.InsecureContext:
// Webnative requires HTTPS
break;
case webnative.ProgramError.UnsupportedBrowser:
break;
}
})
wn.program
returns a Program
object, which can create a new user session or reuse an existing session. There are two ways to create a user session, either by using an authentication strategy or by requesting access from another app through the "capabilities" system. Let's start with the default authentication strategy.
let session
// Do we have an existing session?
if (program.session) {
session = program.session
// If not, let's authenticate.
// (a) new user, register a new Fission account
} else if (userChoseToRegister) {
const { success } = await program.auth.register({ username: "llama" })
session = success ? program.auth.session() : null
// (b) existing user, link a new device
} else {
// On device with existing session:
const producer = await program.auth.accountProducer(program.session.username)
producer.on("challenge", challenge => {
// Either show `challenge.pin` or have the user input a PIN and see if they're equal.
if (userInput === challenge.pin) challenge.confirmPin()
else challenge.rejectPin()
})
producer.on("link", ({ approved }) => {
if (approved) console.log("Link device successfully")
})
// On device without session:
// Somehow you'll need to get ahold of the username.
// Few ideas: URL query param, QR code, manual input.
const consumer = await program.auth.accountConsumer(username)
consumer.on("challenge", ({ pin }) => {
showPinOnUI(pin)
})
consumer.on("link", async ({ approved, username }) => {
if (approved) {
console.log(`Successfully authenticated as ${username}`)
session = await program.auth.session()
}
})
}
Alternatively you can use the "capabilities" system when you want partial access to a file system. At the moment of writing, capabilities are only supported through the "Fission auth lobby", which is a Webnative app that uses the auth strategy shown above.
This Fission auth lobby flow works as follows:
// We define a `Permissions` object,
// this represents what permissions to ask the user.
const permissions = {
// Ask permission to write to and read from the directory:
// private/Apps/Nullsoft/Winamp
app: { creator: "Nullsoft", name: "Winamp" }
}
// We need to pass this object to our program
const program = await webnative.program({
namespace: { creator: "Nullsoft", name: "Winamp" },
permissions
})
// (a) Whenever you are ready to redirect to the lobby, call this:
program.capabilities.request()
// (b) When you get redirected back and your program is ready,
// you will have access to your user session.
session = program.session
Once you have your Session
, you have access to your file system 🎉
const fs = session.fs
Notes:
await session.destroy()
configuration.fileSystem.loadImmediately = false
and program.fileSystem.load()
program.fileSystem.recover({ newUsername, oldUsername, readKey })
. The oldUsername
and readKey
can be parsed from the uploaded Recovery Kit and the newUsername
can be generated before calling the function. Please refer to this example from Fission's Webnative App Template. Additionally, if you would like to see how to generate a Recovery Kit, you can reference this exampleThe Web Native File System (WNFS) is a file system built on top of IPLD. It supports operations similar to your macOS, Windows, or Linux desktop file system. It consists of a public and private branch: The public branch is "live" and publicly accessible on the Internet. The private branch is encrypted so that only the owner can see the contents. Read more about it here.
const { Branch } = wn.path
// List the user's private files
await fs.ls(
wn.path.directory(Branch.Private)
)
// Create a sub directory and add some content
const contentPath = wn.file(
Branch.Private, "Sub Directory", "hello.txt"
)
await fs.write(
contentPath,
new TextEncoder().encode("👋") // Uint8Array
)
// Persist changes and announce them to your other devices
await fs.publish()
// Read the file
const content = new TextDecoder().decode(
await fs.read(contentPath)
)
That's it, you have successfully created a Webnative app! 🚀
WNFS exposes a familiar POSIX-style interface:
exists
: check if a file or directory existsls
: list a directorymkdir
: create a directorymv
: move a file or directoryread
: read from a filerm
: remove a file or directorywrite
: write to a fileEach 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.
const file = await fs.get(wn.path.file("private", "Blog Posts", "article.md"))
file.history.list()
// { delta: -1, timestamp: 1606236743 }
// { delta: -2, timestamp: 1606236532 }
// Get the previous version
file.history.back()
// Go back two versions
const delta = -2
file.history.back(delta)
// Get the first version (ie. delta -2)
// by providing a timestamp
file.history.prior(1606236743)
https://guide.fission.codes/developers/webnative/sharing-private-data
Some versions of Webnative require apps to migrate their codebase to address breaking changes. Please see our migration guide for help migrating your apps to the latest Webnative version.
Debugging mode can be enable by setting debug
to true
in your configuration object that you pass to your Program
. By default this will add your programs to the global context object (eg. window
) under globalThis.__webnative.programs
(can be disabled, see API docs).
const appInfo = { creator: "Nullsoft", name: "Winamp" }
await wn.program({
namespace: appInfo,
debug: true
})
// Automatically exposed Program in debug mode
const program = globalThis.__webnative[ wn.namespace(appInfo) ] // namespace: "Nullsoft/Winamp"
Generated using TypeDoc