Home

Leverage Wiki

This guide will take you through Leverage's concepts and provide you with enough information to use the library efficiently. If you find anything confusing and/or missing, please don't hesitate to file an issue.

General concepts

Leverage was created to allow any developer to create an application by using a common interface. Application configuration should be:

1. Simple

2. As declarative as possible

3. Easy to change later

With these ideas in mind, let's take a look at the structure of Leverage:

NOTE: The above image is a simplification and ignores both Services and Middleware because they can be more complex and will be introduced later.

Plugins and Components are kinds of Units in Leverage. A Leverage Unit is a small, single purpose object which is intended to be composed together with other Units in order to form a full application. In order to compose Units together, Leverage provides a Manager:

Manager

The Leverage Manager is provided in the @leverage/core package and will handle gluing the rest of your application together. Leverage's manager functions as the base of your application that we will then build on top of. All other pieces of your app will be handed off to the manager so that it can work its magic!

Now let's talk briefly about the Plugin and Component Units:

Plugin

A Leverage Plugin defines some kind of interaction or process. For example, a very common plugin would be the HTTP plugin available from the @leverage/plugin-http package. This plugin defines how one would receive and respond to HTTP requests.

Component

A Leverage Component defines a specific interaction within a plugin's process. Were we to create a component for a HTTP plugin, this specific interaction would be handling one HTTP request at a given route.

Hello World

With the general concepts understood, let's put together a very simple Hello World application:

Step 1: Install Leverage

Note: We will be needing both the core library (@leverage/core) as well as a HTTP plugin (@leverage/plugin-http) for this example

npm install --save @leverage/core @leverage/plugin-http

Step 2: Import dependencies

Now that we have the required packages installed, let's start writing our application by importing them:

index.js

// We only need Leverage's manager in this example 
import { Manager } from '@leverage/core';
import HTTP from '@leverage/plugin-http';

Step 3: Instantiate a new Manager and HTTP plugin instance

index.js

import { Manager } from '@leverage/core';
import HTTP from '@leverage/plugin-http';

/*====== NEW CODE ======*/
const manager = new Manager();
const http = new HTTP();

Step 4: Create our HTTP component to handle requests

index.js

import { Manager } from '@leverage/core';
import HTTP from '@leverage/plugin-http';

const manager = new Manager();
const http = new HTTP();

/*====== NEW CODE ======*/
const component = {
  // Let the manager know that this object is a component
  is: 'component',
  
  // Configuration for this component
  config: {
    // Let the manager know what plugin this component is intended to be used in
    type: 'http',
    
    // Configuration that the HTTP plugin will use to set up our request handling
    http: {
      // In this example, we'll respond to all requests using this one component
      path: '*',
      // We'll also let the HTTP component know we are listening for `GET` requests
      method: 'get',
    },
  },

  // Now, we can create a callback that will handle our HTTP requests
  http (request, response) {
    // Send the user a "Hello World" message!
    response.send('Hello World');
  }
};

Step 5: Hand off our application pieces to Leverage's manager

index.js

import { Manager } from '@leverage/core';
import HTTP from '@leverage/plugin-http';

const manager = new Manager();
const http = new HTTP();

const component = {
  is: 'component',
  config: {
    type: 'http',
    http: {
      path: '*',
      method: 'get',
    },
  },
  http (request, response) {
    response.send('Hello World');
  }
};

/*====== NEW CODE ======*/
// `Manager.add` can be given any number of objects to add to our application
manager.add(http, component);

Step 6: Fire it up!

index.js

import { Manager } from '@leverage/core';
import HTTP from '@leverage/plugin-http';

const manager = new Manager();
const http = new HTTP();

const component = {
  is: 'component',
  config: {
    type: 'http',
    http: {
      path: '*',
      method: 'get',
    },
  },
  http (request, response) {
    response.send('Hello World');
  }
};

manager.add(http, component);

/*====== NEW CODE ======*/
// Tell the HTTP server to start listening on a port
http.listen(3000);

Open up localhost:3000 in your browser to see the result!

---

Next Steps

If you are ready to learn about Leverage's structures in depth, start here.