Migration

Migration guides for new versions of the webnative SDK

Webnative

Some versions of Webnative require apps to migrate their codebase to address breaking changes. Versions with changes are listed below.

Version 0.35.0

This version of Webnative is a major rewrite. Most apps will only need to update their initialization, permission request, and registration code to use the new APIs.

In previous versions, Webnative was initialized using the initialise or app functions that returned a state object:

// Requires permission from the Fission Auth Lobby
const state = await wn.initialise({
  permissions: {
    app: {
      name: "Winamp",
      creator: "Nullsoft"
    },
  }
})

// Redirect to Auth Lobby to request permission
wn.redirectToLobby(state.permissions)

// Initializes an app with root authority
const state = await webnative.app({ useWnfs: true })

// Register the user after checking the username is valid and available
const { success } = await wn.account.register({ username })

In Webnative 0.35, Webnative is initialized by creating namespaced programs and creating sessions.

Initialize a program with permissions when your app requests capability from the Fission Auth Lobby.

const permissions = {
  app: { creator: "Nullsoft", name: "Winamp" }
}

// Permissions are configured at initialization
const program = await webnative.program({
  namespace: { creator: "Nullsoft", name: "Winamp" },
  permissions
})

// (a) Whenever you are ready to redirect to the lobby to request capabilities 
// call the request function:
program.capabilities.request()

// (b) When you have been redirected back from the lobby and
// your program re-initializes, you will have access to the user session.
session = program.session

Apps with root authority initialize without permissions and use authentication strategies to register users and create sessions:

// Initialize the program
const program = await wn.program({
  namespace: { creator: "Nullsoft", name: "Winamp" }
})

// Register the user after checking the username is valid and available
const { success } = await program.auth.register({ username })
  
// Create a session on success
const session = success ? program.auth.session() : null

In both cases, the program will have an authenticated session at initialization when a user returns for another visit.

See the Initialization, Session, Requesting Capabilities, and Authentication Strategies sections for more details on the new APIs.

Webnative 0.35 also updates the file system interface so that only Uint8Array can be written to and read from WNFS. If you are storing strings or other types of data, you will need to convert them Uint8Array before writes and convert them from Uint8Array on reads.

For example, writing a string to a file and later reading it looks like this:

// 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)
)

Please review the CHANGELOG for an overview of the other changes in this version.

Version 0.28.0

The publicReadKey function in keystore-idb was renamed topublicExchangeKey.

Most users will not need to change anything for webnative 0.28.0, unless they are interacting directly with keystore-idb.

Version 0.27.0

The type of App returned app.index has changed. Previously, the return type was

export type App = {
  domain: string
}

In Webnative 0.27.0, the the return type is

export type App = {
  domains: string[]
  insertedAt: string
  modifiedAt: string
}

The domain for the app is now in the domains array.

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.

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

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.

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

Version 0.26.0

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

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

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

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

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.

const bool = await fs.exists("private/some/file")
const updatedCID = await fs.mkdir("public/some/directory")

In Webnative 0.24, paths are created by path helper functions for files and directories.

const bool = await fs.exists(wn.path.file("private", "some", "file"))
const updatedCID = await fs.mkdir(wn.path.directory("public", "some", "directory"))

The docs for the previous API remain available for reference.