# remoteStorage.js
-[](http://travis-ci.org/RemoteStorage/remoteStorage.js)
+[](http://travis-ci.org/remotestorage/remotestorage.js)
+[](https://david-dm.org/remotestorage/remotestorage.js#info=devDependencies)
+[](https://codeclimate.com/github/remotestorage/remotestorage.js)
+
+remoteStorage.js is a JavaScript library for storing user data locally in the
+browser, as well as connecting to [remoteStorage](http://remotestorage.io)
+servers and syncing data across devices and applications.
### Where to get help?
-* Consult this README
-* Read the Guides:
- * [Adding remoteStorage to your app](http://remotestoragejs.com/doc/code/files2/howto-include-txt.html)
- * [Howto contribute](http://remotestoragejs.com/doc/code/files2/howto-contribute-txt.html)
- * [Working with schemas](http://remotestoragejs.com/doc/code/files2/howto-include-txt.html)
- * [How to configure synchronization](http://remotestoragejs.com/doc/code/files/lib/sync-js.html#How_to_configure_sync)
-* Consult the [API documentation](http://remotestoragejs.com/doc/code)
-* Ask in the [IRC Channel](http://webchat.freenode.net/?channels=remotestorage) (#remotestorage on freenode)
-* Open an issue for discussion, either in the relevant repository or [the website repo for general discussion](https://github.com/remotestorage/remotestorage.io/issues)
+* See [remotestorage.io](http://remotestorage.io/) for documentation, community
+ forums, and links
+* Get instant support via IRC in
+ [#remotestorage](irc://irc.freenode.net:7000/remotestorage) on Freenode
+
+### Running a local test server
+
+To develop remoteStorage-enabled apps, you need to have a
+remoteStorage-compatible storage account. We recommend
+[reStore](https://github.com/jcoglan/restore) for running a local test server.
+(Use the latest version from GitHub, not npm!)
+
+You can also get an account with a hoster, or use one of the various other
+remoteStorage server implementations:
+[get storage](http://remotestorage.io/get/).
+
+### Which version to choose?
+
+You can either use a stable release or the current HEAD build. Stable releases
+can be found in [release/](https://github.com/remotestorage/remotestorage.js/tree/master/release/).
+Directories with a `-rcX` suffix contain release candidates, which may be used
+for testing but aren't necessarily "stable" releases.
-### Running the local Test Server
+[release/head](https://github.com/remotestorage/remotestorage.js/tree/master/release/head/)
+contains a semi-current HEAD build. It is updated manually and irregularly. To
+build an up-to-date version of all files, run `make all` in the repository
+root.
-#### To run the test server, first of all add a line
+### Which build file to use for my app?
- 127.0.0.1 local.dev
+There are a number of different builds available:
-#### to your /etc/hosts file. then run:
+* <kbd>remotestorage.js</kbd> - Contains all components of remotestorage.js for
+ running in a browser.
+* <kbd>remotestorage.amd.js</kbd> - The same as remotestorage.js, but wrapped
+ for use with
+ [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition) loaders
+ such as [RequireJS](http://requirejs.org/).
+* <kbd>remotestorage.min.js</kbd> - Minified version of remotestorage.js
+* <kbd>remotestorage-nocache.js</kbd> - Contains a version of remotestorage.js
+ without any caching features included. Use this if you want your app to write
+ directly to the remote server **without caching** any data in the browser's
+ storage (localStorage or indexedDB).
+* <kbd>remotestorage-nocache.amd.js</kbd>,
+ <kbd>remotestorage-nocache.min.js</kbd> - same as the other .amd / .min
+ build, but based on remotestorage-nocache.js.
- sudo node server/nodejs-example.js
+### Running tests
-### Adding remoteStorage.js v0.7 to your app:
+Install development dependencies including the
+[testing framework](https://github.com/silverbucket/teste):
-#### add "remoteStorage-modules.js" (you can download it from http://remotestoragejs.com/build/0.7.0-head/remoteStorage-modules.js)
-#### in index.html, include this script and any modules you plan to load:
+ npm install
- <script src="remoteStorage-modules.js"></script>
+Run all suites:
-#### at the beginning of the document body, add a div:
+ npm test
- <div id="remotestorage-connect"></div>
+Use the `teste` executable in order to test single files, like so e.g.:
-#### claim access to for instance the 'notes' module, and display the widget:
+ node_modules/.bin/teste test/unit/baseclient-suite.js
- remoteStorage.claimAccess({notes: 'rw'}),then(function() {
- remoteStorage.displayWidget('remotestorage-connect');
- ...
- });
+### How to build
-#### if your app can only be used while connected, then add this on the '...':
+Make sure you have [Natural Docs](http://www.naturaldocs.org/) installed on
+your system (e.g. via `sudo apt-get install naturaldocs`).
- remoteStorage.onWidget('ready', function() {
- showApp();
- });
- remoteStorage.onWidget('disconnect', function() {
- hideApp();
- });
+Display the available build tasks:
-#### in any case, update the DOM when changes come in. This is module-specific:
+ make
- remoteStorage.notes.onChange(function() {
- redrawApp();
- });
+Build everything:
-#### see /examples/minimal/index.html for the full example code.
+ make all
projects / remotestorage.js / blobdiff