Migration

Migration guides for new versions of the ODD SDK

Migration from Webnative SDK to ODD SDK

With version 0.37.0 the Webnative SDK has been re-named to the 'ODD SDK', and it is published to npm as @oddjs/odd.

If you install the SDK with a package manager, update your dependencies in package.json.

{
  "dependencies": {
    "@oddjs/odd": "^0.37.0",
    ...
  }
}

Update imports in your code base from webnative to @oddjs/odd.

import * as odd from '@oddjs/odd'

If you load the SDK from a CDN, update the source in the script tag.

<script src="https://unpkg.com/@oddjs/odd@latest/dist/index.esm.min.js/"></script>

ODD SDK

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

Version 0.37.0

File system event listeners have been moved onto the top-level program and renamed.

For example, the local-change listener was previously accessible on program.fileSystem.

program.fileSystem.on("local-change", ({ path, root }) => { ... })

In version 0.37, the local-change event listener is accessible directly on the program.

program.on("fileSystem:local-change", ({ path, root }) => { ... })

Older Webnative versions

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

Version 0.36.0

This version of Webnative includes a few minor breaking changes.

In previous versions, you could call program.loadFileSystem() to load the file system. In Webnative 0.36.0, call program.fileSystem.load() instead.

The fs.cat file system operation has been replaced by fs.read, and the fs.add operation has been replaced with fs.write.

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 odd.initialise({
  permissions: {
    app: {
      name: "Winamp",
      creator: "Nullsoft"
    },
  }
})

// Redirect to Auth Lobby to request permission
odd.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 odd.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 odd.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 = odd.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(odd.path.file("private", "some", "file"))
const updatedCID = await fs.mkdir(odd.path.directory("public", "some", "directory"))

The docs for the previous API remain available for reference.