Getting started with Node

To get started with Curveball and Node, first make sure you have node installed. Open a terminal and type the following two commands:

node -v
npm -v

Curveball currently requires a Node version higher than 16, and any npm version that came with it.

Typescript is strongly suggested, and everything in Curveball is written with Typescript in mind, including the documentation. The drawback of this is that it’s a bit more effort in Node.js to get everything up and running.

To make this easier, we made a starter template that you can use as a starting point. It’s very lightweight and unopiniated, but if you’re already comfortable configuring Typescript you don’t need the template.

Template or not, here’s roughly how you start an application from scratch:


Get the NPM package

npm i @curveball/core

Hello world

This is the canonical ‘Hello world’ application in Curveball:

import { Application, Context } from '@curveball/core';

const app = new Application();
app.use((ctx: Context) => {

  ctx.response.body = {msg: 'hello world!'};



In Curveball (like Koa) everything is a middleware, so to respond to a request you use the .use() method.

The .use() method requires a ctx object as its argument. This ctx object contains all the information about the HTTP request and the response, accessible via ctx.request and ctx.response.

In this case we are setting the reponse body to contain an object.

ctx.response.body = {msg: 'Hello world!'}

By default this will be turned into a JSON string.

Lastly, call listen() to listen on a specific TCP port.

After this, open http://localhost:4000 to see if it worked.

Now we’ve covered the Node-specific documentation, go read next steps to go over all the common use-cases.