remote-storage

The User ID is set when you create a new instance of remoteStorage:

const remoteStorage = new RemoteStorage({
  userId: '123e4567-e89b-12d3-a456-426614174000'
})

If you don't provide a user ID, remoteStorage will generate a random UUID which will change every time the user visits your site. This is useful for testing, but defeats the purpose of remoteStorage since the data will not persist across devices or browsers.

Instance IDs

remoteStorage uses instance IDs to identify the application instance that is making the request. An instance ID is a string that uniquely identifies an application instance. Typically you would use the same instance ID for all requests from the same application instance.

The instance ID is set when you create a new instance of remoteStorage:

const remoteStorage = new RemoteStorage({
  userId: '123e4567-e89b-12d3-a456-426614174000',
  instanceId: 'my-cool-app'
})

Server

We offer a free hosted community server at https://api.remote.storage (the default behavior if no serverAddress is provided). This hosted server should not be used for production apps, but it's great for testing and prototyping.

To use a different server, simply pass the serverAddress option when creating a new instance of remoteStorage:

const remoteStorage = new RemoteStorage({
  serverAddress: 'https://api.remote.storage',
  userId: '123e4567-e89b-12d3-a456-426614174000',
  instanceId: 'my-cool-app'
})

The server can be spun up using Docker in a few minutes. See the server documentation for more information.

FAQ

What data should I store in remoteStorage?

remoteStorage should only be used for non-sensitive data. We recommend using it for things like user preferences, settings, and other non-sensitive data. Due to the nature of the public API, it's not a good fit for storing sensitive data like passwords or PII.

How is remoteStorage different from localStorage?

localStorage is a browser API that allows you to store data in the browser. The data is stored locally on the user's device and is not shared across devices or browsers. remoteStorage is a library that combines the localStorage API with a remote server to persist data across browsers and devices.

How do I authenticate requests to remoteStorage?

remoteStorage can be used without any authentication, but we highly recommend using JSON Web Tokens (JWT) to authenticate requests to the server. This can be done by setting the JWT_SECRET environment variable in .env to your JWT secret for the server. See the server documentation for more information.

Contributing

Pull requests are always welcome. Note that if you are going to propose drastic changes, make sure to open an issue for discussion first. This will ensure that your PR will be accepted before you start working on it.

For any existing issues that do not yet have an assigned contributor, feel free to comment on the issue if you would like to work on it. We will assign the issue to you if we think you are a good fit.

Making changes: implement your bug fix or feature, write tests to cover it and make sure all tests are passing. Ensure your commit leverages Semantic Commit Messages and that your commit message follows the Conventional Commits format. Then open a pull request to the main branch.