Getting started
Boltzmann is a node http server framework constructed from the same building blocks as many other frameworks, using well-tested libraries like the ones from the jshttp project, which support Express. It makes some choices that are notably different from many other node frameworks, and you'll want to know about these choices even if you're an experienced node developer.
The first difference you're likely to notice is that Boltzmann is not a versioned dependency of your application. It's implemented in a single file that lives alongside your code. Its dependencies are dependencies of your project. This decision makes some tradeoffs that we found useful in our projects: we can choose when to upgrade core dependencies, and aren't tied to waiting for the framework to update. We can also choose to modify Boltzmann's source code directly if the project needs this, at the cost of no longer being able to update automatically.
As a result, you don't install Boltzmann using a package manager like yarn.
Instead, you scaffold a Boltzmann project using its templating tool. The
easiest way to run this tool is to use npx
: npx boltzmann-cli --help
. You
can also build the tool yourself from source if you have the Rust toolchain, or
install a pre-built
release. This tool
generates a single javascript file with all of Boltzmann's implementation, and
some scaffolding for a full Boltzmann app if it's not already present. Passing
options to the tool enables or disables specific Boltzmann features. The tool
is safe to re-run, provided you are running it in a versioned git directory.
The next major difference boltzmann has from frameworks like Express is its approach to middleware. It doesn't use the Connect-style API and it doesn't offer lifecycle hooks. Instead, Boltzmann uses an approach borrowed from aspect-oriented programming, which you'll be familiar with if you've been using frameworks like React. Middleware is how you'll implement new behavior that can be re-used in your route handlers. You can also change Boltzmann's core behavior with custom middleware!
The third difference is in the API of Boltzmann's route
handers. To respond with data from a route, return the
data. Boltzmann sets content type headers based on what you return, deferring
to any headers you provide in the headers
symbol on your response. To respond
with an error, throw: Boltzmann will translate to http semantics automatically.
(To control how thrown errors are translated, you can write middleware!) Learn
more about building responses in the responses
documentation.
Boltzmann also relies on a little bit of convention to simplify configuration.
For instance, it assumes that all route handlers are exported from
handlers.js
or a handlers/
directory in the same level of the project. The
same is true for middleware: you can move to exports from a middleware/
directory if you outgrow the initial middleware.js
file.
Hello world
Let's look at a hello-world project. You can create one by running the scaffolding tool with its default options:
code|⇒ npx boltzmann-cli hello --redis
Scaffolding a Boltzmann service in /Users/cj/code/hello
initializing a new NPM package...
writing boltzmann files...
updating dependencies...
adding are-we-dev @ ^1.0.0
adding uuid @ ^8.3.0
adding @hapi/iron @ ^6.0.0
adding culture-ships @ ^1.0.0
adding find-my-way @ ^3.0.4
adding bole @ ^4.0.0
adding ajv @ ^6.12.2
adding dotenv @ ^8.2.0
adding accepts @ ^1.3.7
adding handy-redis @ ^1.8.1 (redis activated)
adding redis @ ^3.0.2 (redis activated)
adding cookie @ ^0.4.1
adding tap @ ^14.10.7 (dev)
adding ansi-escapes @ ^4.3.1 (dev)
adding supports-hyperlinks @ ^2.1.0 (dev)
adding get-function-location @ ^2.0.0 (dev)
adding @hapi/shot @ ^5.0.4 (dev)
adding bistre @ ^1.0.1 (dev)
adding eslint @ ^7.1.0 (dev)
adding @typescript-eslint/parser @ ^3.1.0 (dev)
adding @typescript-eslint/eslint-plugin @ ^3.1.0 (dev)
adding eslint-config-prettier @ ^6.11.0 (dev)
adding eslint-plugin-prettier @ ^3.1.3 (dev)
adding prettier @ ^2.0.5 (dev)
adding nodemon @ ^2.0.4 (dev)
writing updated package.json...
running package install...
Boltzmann at 0.2.0-alpha1 with githubci, ping, redis, status
As you can see, boltzmann informs you about what top-level dependencies it is adding
and why those dependencies are present. handy-redis
is present in this scaffold because
we asked for the redis feature.
You now have a complete hello world project in the hello
directory, with commented source files to
edit in place. To run your scaffolded project, : ./boltzmann.js
. And to view the response: curl http://localhost:5000/hello/world
In development, you can use npm start
to run under nodemon.
The scaffolded project includes examples for most of the features you can choose to enable.
For instance, if you enable the templates
feature, the scaffold gives you a hello world
template file to start with. Here's what you get with the default options:
hello|⇒ ls
boltzmann.js* handlers.js middleware.js node_modules/ package-lock.json package.json
Take a look at handlers.js
:
import { Context } from './boltzmann.js' // optionally pull in typescript definition
greeting.route = 'GET /hello/:name'
export async function greeting(/** @type {Context} */ context) {
return `hello ${context.params.name}`
}
module.exports = {
greeting
}
A Boltzmann route handler is a function that returns an object or throws an error. Input to the function is the context object. The context object is where Boltzmann puts all data it derives from the initial request. It expects you to modify the context object in middleware: it is there to hold data you find useful through the request lifecycle. The raw node request object is available on the context object if you need it.
The default scaffolded project also provides a commented middleware.js
file to help you write your
first middlewares. And finally, a linter is configured for you. Use npm run
in a Boltzmann project
to see the run scripts provided out of the box for you.
Learn more!
To learn more about Boltzmann's fundamentals, check out the concepts documentation. If you need to deep-dive into details, see the reference documentation.