Getting started

Installation

Marble.js requires node v8.0 or higher:

$ npm i @marblejs/core @marblejs/middleware-logger @marblejs/middleware-body rxjs

or if you are a hipster:

$ yarn add @marblejs/core @marblejs/middleware-logger @marblejs/middleware-body rxjs

Bootstrapping

The very basic configuration consists of two steps: HTTP listener definition and HTTP server configuration.

httpListener is the basic starting point of every Marble application. It includes definitions of all middlewares and API effects.

http.listener.ts

import { httpListener } from '@marblejs/core';
import { logger$ } from '@marblejs/middleware-logger';
import { bodyParser$ } from '@marblejs/middleware-body';
import { api$ } from './api.effects';

const middlewares = [
  logger$(),
  bodyParser$(),
  // ...
];

const effects = [
  api$,
  // endpoint2$
  // ...
];

export default httpListener({ middlewares, effects });

And here is our simple "hello world" endpoint.

api.effects.ts

import { r } from '@marblejs/core';
import { mapTo } from 'rxjs/operators';

export const api$ = r.pipe(
  r.matchPath('/'),
  r.matchType('GET'),
  r.useEffect(req$ => req$.pipe(
     mapTo({ body: 'Hello, world!' }),
  )));

To create Marble app instance, we can use createServer, which is a wrapper around Node.js server creator with much more possibilities and goods inside. When created, it won't automatically start listening to given port and hostname until you call .run() method on it.

server.ts

import { createServer } from '@marblejs/core';
import httpListener from './http.listener';

export const server = createServer({
  port: 1337,
  hostname: '127.0.0.1',
  httpListener,
});

server.run();

you can always visit example repository for a complete Marble.js app example.

We'll use TypeScript in the documentation but you can always write Marble apps in standard JavaScript (and any other language that transpiles to JavaScript).

To test run your server you can install typescript compiler and ts-node:

$ yarn add typescript ts-node

then add the following script to your package.json file:

"scripts": {
  "start": "ts-node server.ts"
}

Now go ahead, create server.ts, http.listener.ts, api.effects.ts modules in your project and run your server:

$ yarn start

finally test your "functional" server by visiting http://localhost:1337

For more API specific details about server bootstraping, visit createServer API reference.

If you prefer to have standard Node.js control over server creation, you can also easily hook the app directly into Node.js http.createServer

server.ts

import { createContext } from '@marblejs/core';
import * as http from 'http';
import httpListener from './http.listener';

const httpServer = httpListener
  .run(createContext());

export const server = http
  .createServer(httpServer)
  .listen(1337, '127.0.0.1');

In the next chapter you will learn how to create basic Marble.js endpoints using Effects.