Kraken.js Module Routing: How the `routes` Config Maps URLs to Controllers

Kraken.js lets you define routes declaratively in a routes configuration object instead of writing app.get() calls by hand. Each entry maps a URL path to a controller action inside a module, which keeps large Express apps organized by feature. The catch: route registration is silent when it fails, and registration order matters. This guide shows a working configuration, explains the mechanism, and covers the mistakes that produce unexplained 404s.

Note on maintenance: Kraken.js (originally from PayPal) is unmaintained. The behavior described here reflects the last published versions (Kraken 2.x on Express 4, Node 10–14 era). It still runs, but security fixes are not guaranteed — treat this as guidance for maintaining existing apps, not for starting new ones.

The useful answer first

To wire a URL to a controller in Kraken, you need three things aligned: a routes entry in your config with both module and path keys, a controller file that exports the named action, and route registration that happens after Kraken's initialization callback fires. If any of the three is off, you typically get a 404 with no error message — not a startup crash.

A worked configuration

Assume a standard Kraken project layout with config/config.json, a controllers/ directory, and index.js as the entry point. The examples below assume Kraken 2.x conventions.

In config/config.json:

{
  "routes": {
    "/users/list": {
      "module": "users",
      "path": "list"
    },
    "/users/:id": {
      "module": "users",
      "path": "show"
    }
  }
}

In controllers/users.js, export functions matching the path values. Each receives the Express request and response objects:

module.exports = {
  list: function (req, res) {
    res.json({ users: [] });
  },
  show: function (req, res) {
    res.json({ id: req.params.id });
  }
};

In index.js, register routes inside Kraken's callback, not before it:

var kraken = require('kraken-js');
var express = require('express');
var app = express();

app.use(kraken());

app.listen(8000, function () {
  console.log('Listening on 8000');
});

Run the app from the project root with node index.js (no special permissions needed). Then verify with curl http://localhost:8000/users/list — you should get the JSON response, not a 404. Check the startup log for Kraken's initialization output confirming config was parsed.

How the mechanism works

During startup, Kraken reads the merged configuration (base config.json plus the file matching your NODE_ENV, e.g. development.json), walks the routes object, resolves each module to a file under the controllers directory, and attaches the exported function named by path to the Express router at the given URL. URL parameters like :id behave exactly as they do in Express, because that is what Kraken delegates to underneath.

Environment-aware config works the same way for everything else: keys in development.json override config.json when NODE_ENV=development. If a key is absent, Kraken falls back to the base value rather than failing — convenient, but it can mask typos in environment files.

Limits and common mistakes

• Silent registration failures. If module or path is missing or misspelled, or the exported function name doesn't match path, Kraken skips the route without throwing. The only symptom is a 404 at runtime. In a large app, add a startup check that logs registered routes (e.g., walk app._router.stack in Express 4) so failures surface immediately.
• Registration order. Middleware and routes you add manually must come after Kraken's middleware has initialized. Hand-registered routes added too early can be shadowed or never reached.
• No hot reload. Changes to config.json or environment files require a full restart. Use a process supervisor like nodemon during development to restart on file changes.
• Environment key mismatches. A top-level key in an environment file that doesn't correspond to your actual NODE_ENV value is ignored silently. Confirm with echo $NODE_ENV (Linux/macOS) or echo %NODE_ENV% (Windows cmd) before debugging config that "isn't being read."

Verifying the result

Three quick checks after any routing change: (1) the startup log shows Kraken initialized without config errors; (2) curl -i against each defined route returns the expected status and body rather than Express's default 404 HTML; (3) a deliberately wrong URL returns 404, confirming your routes — not a catch-all — are what responded. If a route 404s unexpectedly, check the module/path spelling against the controller file first; that is the most common cause.