Getting started
Boltzmann is a node http server framework that uses 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.
code|⇒ npx boltzmann-cli hello
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 culture-ships @ ^1.0.0
adding find-my-way @ ^2.2.1
adding bole @ ^4.0.0
adding ajv @ ^6.12.2
adding dotenv @ ^8.2.0
adding accepts @ ^1.3.7
adding cookie @ ^0.4.1
adding tap @ ^14.10.7 (dev)
adding @hapi/shot @ ^4.1.2 (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)
writing updated package.json...
running package install...
Boltzmann at 0.1.2 with githubci, ping, status
You now have a complete hello world project in the hello
directory, with commented source files to edit in place.
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
}
To run: ./boltzmann.js
. And to view the response: curl http://localhost:5000/hello/world
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, but we suggest you avoid modifying it directly. In particular, you might break body parsing middleware.
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.
To learn more about Boltzmann's fundamentals, check out the concepts documentation. If you need to deep-dive into details, see the reference documentation.