Initialization

Creating a Webnative program

You can use the Webnative SDK by creating a Webnative program. Here is a minimal example:

const program = await wn.program({
  // `namespace` can also be just a string; it's 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:
      // Browsers must support IndexedDB
      break;
  }

})

Program

A Webnative program is a set of components and utilities for building a distributed web application.

export type Program = ShortHands & {
  auth: AuthenticationStrategy
  capabilities: {
    collect: () => Promise<Maybe<string>> // returns username
    request: (options?: CapabilitiesImpl.RequestOptions) => Promise<void>
    session: (username: string) => Promise<Maybe<Session>>
  }
  configuration: Configuration
  components: Components
  fileSystem: FileSystemShortHands & Events.ListenTo<Events.FileSystem>
  session: Maybe<Session>
}

We'll cover each part of a program in upcoming sections. As a quick summary:

• Session. A session including a username and a filesystem instance. A session will be created from an authentication strategy or requested capabilities depending on which approach your application takes.

• Authentication Strategy. A set of functions for registering users and linking devices.

• Capabilities. A set of functions for requesting authorization from another app.

• File System. A set of functions and event listeners for working with the file system.

• Configuration. The configuration used to instantiate the program.

• Components. Component implementations for authentication strategy, capabilities, crypto, storage, depot, manners, and references.

• Shorthands. Helper functions provided for easy access.

Configuration

You can configure a program with a namespace parameter and a few optional parameters:

export type Configuration = {
  namespace: string | AppInfo
  debug?: boolean
  fileSystem?: {
    loadImmediately?: boolean
    version?: string
  }
  permissions?: Permissions
  userMessages?: UserMessages
}

Namespace

We saw a namespace earlier in our minimal example:

namespace: { creator: "Nullsoft", name: "Winamp" }

A namespace isolates an application in browser storage. This isolation means you can work on multiple apps on localhost at the same port and not worry about them interacting or conflicting. Provide each app a namespace, and they will exist independently.

You can also set the namespace as a string:

namespace: "nullsoft-winamp"

Debug

The debug flag determines whether Webnative should log detailed debugging information to the console. The default value is false.

Filesystem options

The loadImmediately flag determines if Webnative should load the filesystem at initialization. The default value is true.

The filesystem can be loaded after initialization using the program.loadFileSystem shorthand function. In most cases, you will want to load the filesystem immediately, but deferring can sometimes be useful. For example, you can load the filesystem in a Worker after initialization.

The version sets the filesystem version. The version defaults to the latest stable version of WNFS.

Permissions

Permissions are the capabilities to be requested from another application. We'll cover permissions in more detail in the Requesting Capabilities section.

User messages

User messages are alerts that report to the user when the current version of Webnative does not support their filesystem. You can update these messages to provide users with your support information.

Custom Components

You can deeply customize a Webnative program by providing component implementations. We'll discuss custom components in the Components section.