Hoodie Documentation¶

Welcome to Hoodie¶

Hoodie is a backend for web applications with a JavaScript API for your frontend. If you love building apps with HTML, CSS and JavaScript or a frontend framework, but dread backend work, Hoodie is for you.

Hoodie’s frontend API gives your code superpowers by allowing you to do things that usually only a backend can do (user accounts, emails, payments, etc.).

All of Hoodie is accessible through a simple script include, just like jQuery or lodash:

<script src="/hoodie/client.js"></script>
<script type="javascript">
  var hoodie = new Hoodie();
</script>

From that point on, things get really powerful really quickly:

// In your front-end code:
hoodie.ready.then(function () {
  hoodie.account.signUp({
    username: username,
    password: password
  })
})

That’s how simple signing up a new user is, for example. But anyway:

Hoodie is a frontend abstraction of a generic backend web service. As such, it is agnostic to your choice of frontend application framework. For example, you can use jQuery for your web app and Hoodie for your connection to the backend, instead of raw jQuery.ajax. You could also use React with Hoodie as a data store, or any other frontend framework or library, really.

Open Source¶

Hoodie is an Open Source project, so we don’t own it, can’t sell it, and it won’t suddenly vanish because we got aquired. The source code for Hoodie is available on GitHub under the Apache License 2.0.

How to proceed¶

You could read up on some of the ideological concepts behind Hoodie, such as noBackend and Offline First. These explain why Hoodie exists and why it looks and works the way it does.

If you’re more interested in the technical details of Hoodie, check out How Hoodie Works. Learn how Hoodie handles data storage, does syncing, and where the offline support comes from.

Eager to build stuff? Skip ahead to the quickstart guide!

Quickstart¶

In this guide you’ll learn how to create a demo Hoodie app, learn about the basic structure of a Hoodie project and its folders, the endpoints and app URLs and how to include and use the Hoodie library in your project.

Prerequisites¶

For all operating systems, you’ll need Node.js installed. You can download Node from nodejs.org. We recommend the LTS (Long Term Support) version.

Make sure you have version 4 or higher. You can find out with

$ node -v

Create a new Hoodie Backend¶

First you need to create a new folder, let’s call it testapp

$ mkdir testapp

Change into the testapp directory.

$ cd testapp

Now we need to create a package.json file. For that we can use npm which comes with Node by default. It will ask you a few questions, you can simply press enter to leave the default values.

$ npm init

Now we can install hoodie using npm

$ npm install hoodie --save

The resulting package.json file in the current folder, should look something like this

{
  "name": "funky",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "hoodie",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Now you can start Hoodie with

$ npm start

Great, your Hoodie backend started up and is now telling you at which URL you can access it. By default that is http://127.0.0.1:8080

Congratulations, you just created your first Hoodie Backend :) You can now load the Hoodie client on any website with

<script src="http://127.0.0.1:8080/hoodie/client.js"></script>

You can also create a public/index.html file, which will be served at http://127.0.0.1:8080 after you restart the server. All assets in the public folder, like images, CSS files or JavaScript files, will be served by your Hoodie Backend at http://127.0.0.1:8080/<path/to/your/file.ext>.

What’s next?¶

Our Hoodie Tracker App is a great place to see how to use a Hoodie backend. It’s an intentionally simple and well commented application built with only HTML, JavaScript and CSS, without using any library or framework. You can see it running at https://tracker.hood.ie/

Having Trouble?¶

Sorry it didn’t go smoothly for you. Come chat with us or ask a question on StackOverflow

Configuration¶

Your Hoodie backend can be configured using default options that are part of your repository as well as using hidden files, CLI arguments and environment variables.

Options¶

Here is a list of all available options

Option	Default value	CLI argument	ENV variable	description
address	`'127.0.0.1'`	`--address`	`hoodie_address` \| Address to which Hoodie binds
data	`'.hoodie'`	`--data`	`hoodie_data` \| Data path
dbUrl	–	`--dbUrl`	`hoodie_dbUrl` \| If provided, uses external CouchDB. URL has to contain credentials. Sets `dbAdapter` to `pouchdb-adapter-http`
dbAdapter	`'pouchdb-adapter-fs'`	`--dbAdapter`	`hoodie_dbAdapter` \| Sets default PouchDB adapter <https://pouchdb.com/adapters.html> unless `inMemory` or `dbUrl` set
loglevel	`'warn'`	`--loglevel`	`hoodie_loglevel` \| One of: silent, error, warn, http, info, verbose, silly
inMemory	`false`	`-m`, `--inMemory`	`hoodie_inMemory` \| Whether to start the PouchDB Server in memory. Sets `dbAdapter` to `pouchdb-adapter-memory`
port	`8080`	`--port`	`hoodie_port` \| Port-number to run the Hoodie App on
public	`'public'`	`--public`	`hoodie_public` \| path to static assets
url		`--url`	`hoodie_url` \| Optional: external URL at which Hoodie Server is accessible (e.g. `http://myhoodieapp.com`)
adminPassword		`--adminPassword`	`hoodie_adminPassword`	Password to login to Admin Dashboard. Login is not possible unless set

Defaults¶

Default options are set in your app’s package.json file, using the "hoodie" key. Here is an example with all avaialble options and their default values

{
  "hoodie": {
    "address": "127.0.0.1",
    "port": 8080,
    "data": ".hoodie",
    "public": "public",
    "dbUrl": "",
    "dbAdapter": "pouchdb-adapter-fs",
    "inMemory": false,
    "loglevel": "warn",
    "url": "",
    "adminPassword": ""
  }
}

.hoodierc¶

The .hoodierc can be used to set configuration when running your Hoodie backend in that folder. It should not be comitted to your repository.

The content can be in JSON or INI format. See the rc package on npm for more information

CLI arguments and environment variables¶

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

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

All environment varibales are prefixed with hoodie_. So to set the port to 8090 and to start Hoodie in memory mode, you have to

set the hoodie_port environment variable to 8090
set the hoodie_inMemory environment variable to true

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_.

The priority of configuration¶

command line arguments
Environment variables
.hoodierc files
Your app’s defaults form the "hoodie" key in "package.json"
Hoodie’s default values as shown in table above

Plugins¶

You can extend your Hoodie backend in two ways

App-specific plugins
3rd party plugins

App-specific plugins¶

You can extend your Hoodie’s client by creating the file hoodie/client/index.js in your app’s repository, which should export a Hoodie Client plugin <https://github.com/hoodiehq/hoodie-client#hoodieplugin>. It will dynamically be bundled into your client accessible at the /hoodie/client.js route.

You can extend your Hoodie’s server routes and API by creating hoodie/server/index.js in your app’s, which should export a hapi plugin <https://hapijs.com/tutorials/plugins>.

3rd party plugins¶

Hoodie will soon support loading 3rd party plugins from npm packages. You can watch this pull request for updates.

To get an idea how 3rd party plugins will work and look like, have a look at https://github.com/hoodiehq/hoodie-plugin-example

Deployment¶

One line deploy¶

After you’ve built your Hoodie app you probably want to put it online. You can choose to deploy your app as read-only or deploy the backend couchdb database as well. This video and the text below descibes how to deploy your app using one line of code. Alternatively, you can deploy your app using Docker, please refer to the Docker section.

Deploying to Now¶

Now allows you to deploy a Node application with its command line tool. It’s 100% free for Open Source projects. You can deploy an app from your computer or right from a GitHub repository. For example, to deploy our Hoodie Tracker demo app all you have to do is to run this command:

$ now hoodiehq/hoodie-app-tracker --npm -e NODE_ENV=production -e hoodie_inMemory=true

To decribe this further:

hoodiehq/hoodie-app-tracker is the GitHub repository slug.
--npm tells now to deploy using npm as there is also Dockerfile in the repository.
-e NODE_ENV=production sets the NODE_ENV environment variable to production, which makes the deployment faster as no devDependencies will be installed.
-e hoodie_inMemory=true makes the Hoodie app run in-memory mode, meaning that no data is persisted and no files are written. This is important because now is a read-only file system. That means that all user accounts and data will be lost on the next deployment, but it is great for for a quick test or demo of your application.

Alternatively, add this script to your package.json and you are good to go:

"now-start": "hoodie --inMemory",

Store Data With Cloudant¶

Cloudant is a DBaaS (database-as-a-service). It provides most of CouchDB’s APIs and can be used as Hoodie’s database backend. Signing up for a free account only takes a moment. After sign up, you need to slightly adjust the now deployment command above.

$ now hoodiehq/hoodie-app-tracker -e NODE_ENV=production -e hoodie_inMemory=true -e hoodie_dbUrl=https://username:password@username.cloudant.com/

The hoodie_inMemory environment variable makes sure that Hoodie does not try to write any files like the bundled /hoodie/client.js library. The hoodie_dbUrl environment variable sets the address and credentials to your CouchDB. Replace username and password to whatever you signed up with.

Test and set an alias¶

When you deploy with now you will receive a random subdomain where you can access your application. It looks something like https://hoodie-app-tracker-randomxyz.now.sh/ and was already copied to your clipboard during the deployment. Open the URL in your browser to give it a try. Once everything is good, you can change the subdomain to your preference by running:

$ now alias set hoodie-app-tracker-randomxyz my-tracker-app

That will make your deployed Hoodie Tracker app accessible at https://my-tracker-app.now.sh. For example, here is the app that I deployed myself: https://hoodie-app-tracker.now.sh/

Docker¶

We continuously deploy our Hoodie Tracker App using Docker. You can read about our continuous deployment set at hoodie-app-tracker/deployment.md.

Hoodie API¶

Hoodie provides two APIs

The Hoodie Client API

The Hoodie Client API is what you load into your web application using a script tag. It connects to your Hoodie Backend’s routes
The Hoodie Server API

The Hoodie Server API is used within Hoodie’s route handlers and by plugins to manage accounts, data and to securely integrate with 3rd party services.

The Hoodie Client API¶

hoodie¶

Introduction¶

This document describes the functionality of the hoodie base object. It provides a number of helper methods dealing with event handling and connectivity, as well as a unique id generator and a means to set the endpoint which Hoodie communicates with.

Initialisation¶

The Hoodie Client persists state in the browser, like the current user’s id, session or the connection status to the backend. On page load, Hoodie has to load this state from the local store before you can use its APIs. You can use the Promise returned by hoodie.ready to wait until all APIs are fully initialised

hoodie.ready.then(function () {
  // all hoodie APIs are ready now
})