How to upgrade to rs.js 1.0 (from 0.14 or earlier)

remoteStorage.js 1.0.0 marks a big step for the library and project and considerably improves the developer experience across the board. However, this means that the ways to include and use it in your app changed in some significant ways.

This guide will show you what changed exactly and how to upgrade your app. Instead of duplicating information, it will mostly link to the shiny new documentation, which we’re certain you will appreciate.

1. Including the library in your project

  • Instead of choosing between a bunch of different builds, you can now use our single new UMD build, which you can find in release/remotestorage.js. (There’s a source map file in the same directory, which you can optionally link.)
  • We’re now recommending npm as the preferred means of getting the library and managing its version. (But Bower is still available, too.)
  • We moved from global variables to proper JavaScript modules (any system you like). However, if you just link the release build from your HTML, you can still use globals.

:point_right: Docs: Adding rs.js to an app

2. Creating and configuring a remoteStorage instance

  • The remoteStorage instance is not created automatically anymore. Instead, you must create one via new RemoteStorage() with an optional configuration object.

:point_right: Docs: Initialization & configuration

3. Using the new connect widget add-on

  • We removed the connect widget from the core library entirely, and made all functions needed to build your own UI available as public API with documentation.
  • If you’re using the widget in your app, you should upgrade to our shiny new widget library, which is much prettier, and also nicely integrates Dropbox and Google Drive options (optionally).

:point_right: Docs: Using the Connect Widget add-on

4. Offering Dropbox and Google Drive as storage options

  • Dropbox and Google Drive are now officially supported as storage options! However, there are a bunch of known issues and caveats. Mainly, you can’t use them for publicly sharing files yet, so make sure to disable sharing functions by looking at remoteStorage.backend, in case this applies to your app.

:point_right: Docs: Offering Dropbox and Google Drive storage options

5. Data module changes

  • The API for defining data modules has changed in some ways: mainly, they are now just plain JavaScript objects instead of calling RemoteStorage.defineModule(), and you can load them into your remoteStorage instance either as config argument when creating it, or later via addModule().
  • The recommended way of sharing/publishing modules is now as one npm package per module (also as UMD builds)! This vastly improves the whole situation for both module contributors and consumers.

:point_right: Docs: Data modules

Other changes

  • There are some other breaking changes, e.g. some events being emitted elsewhere. Please refer to the Breaking Changes section of the changelog for these. (They won’t be relevant for most apps).

:point_right: Changelog


This should be it. If you have any questions, feel free to reply here of course, or ping someone in #remotestorage on Freenode IRC. We’ll gladly help you with updating any apps using the library!

2 Likes

Any example applications that have been ported already? Would love to have a look!

Of course: you can check out https://github.com/remotestorage/myfavoritedrinks or https://github.com/skddc/webmarks/ or https://github.com/skddc/sharesome/ for example. But there’s really not much to it, if you just follow this guide. Should take less than 15 minutes for most apps.

1 Like

Litewrite is now also using the latest RemoteStorage.
The documents module moved to https://www.npmjs.com/package/remotestorage-module-documents.
Checkout https://litewrite.net and try out the new Dropbox and Google Drive integrations!

1 Like