Lumen

An MVC-style Node.js framework for building JSON:API 1.0 compliant REST APIs with very little code. Controllers get create, read, update and delete for free — including pagination, sorting, filtering, sparse fieldsets and compound documents — and the ORM sits on top of Knex.

import { Controller } from 'lumen-framework';

class PostsController extends Controller {
  params = ['title', 'body'];
}

export default PostsController;

That controller, a model and a serializer are a complete /posts resource: GET /posts?sort=-title&page[size]=10&fields[posts]=title, GET /posts/1, POST, PATCH and DELETE all work.

Features

• Automatic CRUD actions in controllers, overridable one at a time
• Pagination, sorting and filtering from query params, limited to the fields you allow
• JSON:API compound documents (?include=), sparse fieldsets, relationship and related endpoints
• Visibility rules declared once per namespace and applied to every query a request makes — listings, lookups, relationships and includes
• Database queries shaped by what the serializer actually outputs
• Structured request logging (JSON or plain text) with credential filtering
• A CLI that generates models, controllers, serializers, migrations and whole resources
• Written in TypeScript; type declarations ship with the package
• SQLite, PostgreSQL and MySQL via Knex

Requirements

• Node.js 22.14 or later
• One of better-sqlite3, pg or mysql2 (lumen new adds the one you pick)

Getting started

npm install -g lumen-framework

lumen new blog

cd blog

lumen generate resource post title:string body:text

lumen db:migrate

lumen serve

The API is now on http://localhost:4000:

curl -X POST localhost:4000/posts -H 'Content-Type: application/vnd.api+json' -d '{"data":{"type":"posts","attributes":{"title":"Hello","body":"First post"}}}'

lumen new --database postgres (or mysql) starts a project on another database; lumen --help and lumen <command> --help list every command and option. The getting-started guide walks through this step by step, with related resources and the requests the API answers.

Documentation

• Guides — start with Getting started.
• UPGRADING.md — what an app has to change, or check, to move to Lumen 4.0.
• CHANGELOG.md — release notes.
• examples/social-network — an example app that uses most of the framework, with a map of where each feature lives.
• API reference — every exported class and type, generated from the source: pnpm docs:api in a checkout of this repository, then open docs/api/index.html.

Contributing

pnpm install

pnpm build && pnpm test

The test suite needs the fixture app's dependencies (pnpm --dir test/test-app install) and builds a SQLite database on first run. RELEASE.md describes how releases are cut.

Attribution

Lumen is a fork of Lux, created by Zachary Golba and originally developed and maintained by Postlight. Essentially all of the framework's design — the convention-over-configuration approach, the automatic CRUD controllers, the JSON:API serialization, the ORM built on Knex — is their work.

Upstream development stopped after v1.2.3 (2018). This fork picks it up from there: it was renamed to Lumen to avoid confusion with the original, since it is no longer a drop-in continuation of it — the toolchain has been modernized (TypeScript, esbuild, Vitest, Node 22+) and the public API has been allowed to change. Lumen is not an official Postlight project, and the Postlight team provides no support for it.

The original is MIT licensed, and Lumen remains MIT licensed under the same terms. The original copyright notice is retained in LICENSE alongside that of this fork's contributors.

• Original repository: postlight/lux
• Original announcement: Not Another Node.js Framework