node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



This project allows you to use Pumlhorse as a controller engine in Express.


First, see the Express documentation for setting up a project. Then run npm install --save pumlhorse-express.

Next, in your server file, add the following code:

//This is probably already in your file 
const express = require('express');
const app = express();
//Load Pumlhorse 
const pumlhorseExpress = require('pumlhorse-express')

Route Configuration

The last line in the example above tells Pumlhorse to use a file named site.json for configuring routes. Here is an example configuration file.

    "routes": {
        "/api/animals": {
            "get": "api/animals/list.puml",
            "post": "api/animals/create.puml"
        "/api/animals/:id": {
            "get": "api/animals/test.puml",
            "delete": "api/animals/delete.puml"
        "/home": {
            "get": "ui/home.puml"

For example, a POST request to the route /api/animals will call the api/animals/create.puml script.

Request Parameters

In a script, you can access the request parameters

name: Sample controller for route /users/:userId
  # Retrieve request headers 
  log: Authorization is $headers.Authorization 
  # Retrieve route values with "path" 
  log: User id is $path.userId
  # Retrieve query string values with "query" 
  log: Query param is $query.myValue

If you are using the body-parser package, you can also retrieve the body with $body.

Returning Responses

The following functions are available for returning responses:

  • ok - Returns 200
  • created - Returns 201
  • accepted - Returns 202
  • noContent - Returns 204
  • badRequest - Returns 400
  • unauthorized - Returns 401
  • forbidden - Returns 403
  • notFound - Returns 404

These functions can be used as follows:

# Return a JSON response with status code 200 
    name: Horse
    weight: a lot
    color: Brown

Additionally, you can return other status codes:

# Return a JSON response with status code 123 
    code: 123
      name: Horse
      weight: a lot
      color: Brown

Returning UI views

Pumlhorse supports returning HTML views. You can use whatever Express rendering engine you like.

    view: ./myView.jade
    data: # View model used for the view (if applicable) 
      firstName: John
      lastName: Smith
      lastLogin: July 1st, 1997