hoodie

A generic backend with a client API for Offline First applications

Hoodie lets you build apps without thinking about the backend and makes sure that they work great independent from connectivity.

This is Hoodie’s main repository. It starts a server and serves the client API. Read more about how the Hoodie server works.

A good place to start is our Tracker App. You can play around with Hoodie’s APIs in the browser console and see how it works all together in its simple HTML & JavaScript code.

If you have any questions come say hi in our chat.

Setup

Hoodie is a Node.js package. You need Node Version 4 or higher and npm Version 2 or higher, check your installed version with node -v and npm -v.

First, create a folder and a package.json file

mkdir my-app
cd my-app
npm init -y

Next install hoodie and save it as dependency

npm install --save hoodie

Now simply use npm start to start up your Hoodie app!

You can find a more thorough description in our Getting Started Guide.

Usage

hoodie can be used as as CLI (Command Line Interface) or as hapi plugin. The options are slightly different, see below

CLI

Once you finished the setup, you can start your hoodie server with

npm start

To pass CLI options to Hoodie, you have to separate them with --, for example:

npm start -- --port=8090 --inMemory

Available CLI options are

option	default	description
--address	'127.0.0.1'	Address to which Hoodie binds
--data	'.hoodie'	Data path
--dbUrl	-	If provided, uses external CouchDB listening at the given URL. (Can contain auth credentials)
--dbUrlUsername	-	Username to authenticate with the external CouchDB (requires --dbUrl and --dbUrlPassword to be set).
--dbUrlPassword	-	Password to authenticate with the external CouchDB (requires --dbUrl and/or --dbUrlUsername to be set).
--dbAdapter	pouchdb-adapter-fs	Default PouchDB adapter. Ignored if dbUrl or inMemory set
--adminPassword	-	Password to login to Admin Dashboard. Login is not possible if adminPassword option is not set
--loglevel	'warn'	One of: silent, error, warn, http, info, verbose, silly
-m, --inMemory	false	Whether to start the PouchDB Server in memory
--port	8080	Port-number to run the Hoodie App on
--public	'public'	path to static assets
--url	-	Optional: external URL at which Hoodie Server is accessible (e.g. http://myhoodieapp.com)
-h, --help, --usage	-	Prints help and available options
-v, --version	-	Shows Hoodie version

Hoodie CLI is using rc for configuration, so the same options can be set with environment variables and config files. Environment variables are prefixed with hoodie_. Examples: hoodie_port=8090 or hoodie_inMemory=true. Configuration files can be in INI or JSON format and can be placed at different locations. Most commonly you would place a .hoodierc file in your app’s directory, and it can look like this

{
  "port": 8090,
  "inMemory": true,
  "adminPassword": "secret"
}

The priority of configuration:

1. command line arguments
2. Environment variables
3. .hoodierc files
4. Your app’s defaults form "hoodie" key in "package.json"
5. Hoodie’s defaults as shown in table above

hapi plugin

You can load hoodie as hapi plugin to use it in your existing hapi application:

var Hapi = require('hapi')
var hoodie = require('hoodie').register

var server = new Hapi.Server()
server.connection({
  host: 'localhost',
  port: 8000
})

server.register({
  register: hoodie,
  options: { // pass options here
    inMemory: true,
    public: 'dist'
  }
}, function (error) {
  if (error) {
    throw error
  }

  server.start(function (error) {
    if (error) {
      throw error
    }

    console.log(('Server running at:', server.info.uri)
  })
})

The available options are

option	default	description
PouchDB	–	PouchDB constructor. See also custom PouchDB builds
paths.data	'.hoodie'	Data path
paths.public	'public'	Public path
adminPassword	–	Password to login to Admin Dashboard. Login is not possible if adminPassword option is not set
inMemory	false	If set to true, configuration and other files will not be read from / written to the file system
client	{}	Hoodie Client options. client.url is set based on hapi’s server.info.host
account	{}	Hoodie Account Server options. account.admins, account.secret and account.usersDb are set based on db option above
store	{}	Hoodie Store Server options. store.couchdb, store.PouchDB are set based on db option above. store.hooks.onPreAuth is set to bind user authentication for Hoodie Account to Hoodie Store

Extending Hoodie for your app

You can add custom behavior to your hoodie-based application in a few ways:

1. The server-side functionality can be extended by adding a module constructed as a hapi plugin to the path hoodie/server. E.g:

exports.register = function (server, options, next) {
  // server-relevant code here
  next();
}

exports.register.attributes = {
  'name': 'my-app'
}

2. The client-side functionality can be extended by adding a module that can be interpreted as a hoodie plugin to the path hoodie/client, which by default will be built into the client.js package by browserify.

module.exports = {
  demonstratePlugin: function () { // will be attached as hoodie.demonstratePlugin()
    // client-relevant code here
  }
}

Both of the above paths will be imported as if Node modules, so the path to the entry file for each module can be hoodie/{server,client}.js or hoodie/{server,client}/index.js.

Note that for now only the file modification time of the entry file of the client module is used to determine the freshness of the client bundle and therefore whether it should be rebuilt on the first request after a server restart. If your client code stretches to many files, you may need to update the mtime of the client entry file by using touch or a similar method before restarting your server to ensure that the client bundle is rebuilt.

Testing

Local setup

git clone https://github.com/hoodiehq/hoodie.git
cd hoodie
npm install

The hoodie test suite is run with npm test. You can read more about testing Hoodie.

You can start hoodie for itself using npm start. It will serve the contents of the public folder.

Backers

Become a backer and show your Hoodie support!

Official Sponsors

Show your support for Hoodie and help us sustain our inclusive community. We will publicly appreciate your support and are happy to get your word out, as long as it aligns with our Code of Conduct.

License

Apache 2.0