Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


API Services Made Easy With Node.js

Subscribe to updates I use nodal

Statistics on nodal

Number of watchers on Github 4535
Number of open issues 42
Average time to close an issue 18 days
Main language JavaScript
Average time to merge a PR 1 day
Open pull requests 23+
Closed pull requests 21+
Last commit about 2 years ago
Repo Created over 4 years ago
Repo Last Updated over 1 year ago
Size 1.23 MB
Homepage http://www.nodalj...
Organization / Authorkeithwhor
Page Updated
Do you use nodal? Leave a review!
View open issues (42)
View nodal activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating nodal for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


API Services Made Easy with Node.js

Build Status Join the chat at

Nodal Logo

View the website at

Nodal is a web server and opinionated framework for building data manipulation-centric (Create Read Update Destroy) API services in Node.js for web, mobile or IoT apps.

Why Nodal?

Hello, Nodal Building Node.js Servers for Everybody is our first blog post that helps you get acquainted with the reasons behind the creation of the framework. :)

Post Parse Prototyping is also a fantastic read explaining the benefits of Nodal for quick and easy mobile / IoT backend development.


Nodal is built upon an ideology of a robust, scalable architecture for data storage and retrieval APIs. It is an opinionated, explicit, idiomatic and highly-extensible full-service framework that takes care of all of the hard decisions for you and your team. This allows you to focus on creating an effective product in a short timespan while minimizing technical debt.

Nodal servers are not meant to be monoliths. They're stateless and distributed, meant to service your needs of interfacing with your data layer effortlessly. While you can output any data format with Nodal, it's recommended you offload things like static page rendering to other optimized services like CDNs.

Check out the first Nodal Screencast here.

Stateless Dogma

It's important to note that Nodal is meant for stateless API services. This means you should not rely on memory within a specific process to serve multiple requests, and Nodal will use process clustering (even in development) to actively discourage this practice. If you need to work with unstructured data for rapid prototyping, connect Nodal to a PostgreSQL database and use the JSON field type. You'll find yourself encountering a lot of trouble if you start trying to use in-process memory across different requests.

Remember: one input, one output. Side effects dealing with model state should be managed via your Database. Nodal should not be used for streaming (long poll) requests and the HTTP request and response objects are intentionally obfuscated.

This also means you can not rely on socket connections. If you need to incorporate realtime functionality in your application, there should be a separate server responsible for this. It can interface with your Nodal API server and even receive events from it, but your API server should never have a stateful (prolonged) connection with any client.

Getting Started

Getting started with Nodal is easy.

  1. Download and install the newest Node 6.x version from
  2. Open terminal, and type npm install nodal -g. (If you get an error, run sudo npm install nodal -g or fix permissions permanently by following these directions
  3. Using your terminal, visit your projects folder. Perhaps with cd ~.
  4. Run nodal new.
  5. Follow the on screen instructions, enter your new project directory and type nodal s.

That's it! Your Nodal webserver is up and running.

Hooking Up Your Database

Once Nodal is up and running, it's likely that you'll want to connect your project to a database. Nodal comes packaged with Migrations, a Query Composer and full PostgreSQL integration.

First you'll need to install PostgreSQL. OS X users, I recommend using for your development environment.

Once you've installed Postgres, make sure to run:

$ createuser postgres -s

To create a default postgres superuser with no password. (Default for Nodal's configuration.)

To begin using your database, start with:

$ nodal db:create

To create the database and then,

$ nodal db:prepare

To prepare for migrations.

From here, nodal db:migrate runs all pending migrations and nodal db:rollback will roll back migrations, one at a time by default.

Server Types

Nodal works best when you follow its ideology, and that means creating a new service to solve specific Problem Domains of your application and business.

The main three suggestions are Branding Server, API Server and Application Server.

Nodal's core competency is building API servers. We do, however, also have a project called dotcom for building Branding Servers (search engine optimized server-generated pages). More on this soon.

API Server

Create an API server using Nodal's Models, PostgreSQL integration, built-in JSON API formatting, and Query Composer (ORM). Bi-directional migrations are packaged with Nodal, meaning you can maintain the integrity of your data. User (including password) and OAuth AccessToken models and controllers are pre-built for you and can be added easily to your project.

Packaged with Nodal are workers, scheduling modules, and much more for all of your data needs.

We can look at what an API Controller might look like for, say, blog posts:

class BlogPostsController extends Nodal.Controller {

  index() {

      .end((err, blogPosts) => {

        this.respond(err || blogPosts);



  show() {

    BlogPost.find(, (err, blogPost) => this.respond(err || blogPost));


  create() {

    BlogPost.create(params.body, (err, blogPost) => this.respond(err || blogPost));


  update() {

    BlogPost.update(, params.body, (err, blogPost) => this.respond(err || blogPost));


  destroy() {

    BlogPost.destroy(, (err, blogPost) => this.respond(err || blogPost));



Beginner's Guide

You'll be able to learn more about Nodal at


Check out the website at


View the roadmap at


Nodal is under active development and maintained by Keith Horwood.

Contributors welcome!

Follow me on Twitter, @keithwhor

Fork me on GitHub, keithwhor

Thanks for checking out Nodal!

nodal open issues Ask a question     (View All Issues)
  • about 3 years Cannot set property 'user_id' of undefined
  • about 3 years Returning models in ModelFactory createFromModels callback
  • about 3 years Testing access_tokens endpoint
  • about 3 years Content-Type Header Not Set in `EndpointRequest.mock`
  • about 3 years Multiple foreignkey
  • about 3 years Joining on columns that don't end with "_id"
  • about 3 years Add TypeScript definition file.
  • about 3 years Add link to Wiki in the about text.
  • about 3 years Is it possible to use nodal with an existing database?
  • over 3 years What is suggested way of implementing security in a nodal API?
  • over 3 years Can't use Nodal behind corporate proxy
  • over 3 years addColumn in a migration does not take "unique" into account
  • over 3 years Ignoring folders for livereload in development
  • over 3 years error on poly:deploy
  • over 3 years Add support for multiple named seeds and import them by name
  • over 3 years React as front-end
  • over 3 years please note on how to deal with transactions?
  • over 3 years Support documentationjs to Nodal Project API reference documentation generation
  • over 3 years Set custom values in response meta field
  • over 3 years Vague error messages when they occur in Controllers. StackTrace stops at router.js
  • over 3 years Geometric Types
  • almost 4 years nodal g:model Address generates 'Addres' model, migration
  • over 2 years Suggestion for updated wiki docs content for 'Adding new fields columns to an existing model'
  • over 2 years Modelarray.from
  • over 2 years AcessToken.verify is not working
  • over 2 years Callback being called multiple times in failing controller tests
  • over 2 years Setting "global" variables from middleware
  • almost 3 years Aggregation on joined relationship column
  • almost 3 years JSONApi support
  • almost 3 years Error on TestRunner class when adding subdirectories in test directory
nodal open pull requests (View All Pulls)
  • Cors authorization middleware
  • [DOC] added actual CRUD abbreviation
  • Updates task CLI command to pass same number of arguments as scheduler
  • v0.10.0 docs
  • Print Usage if Arguments are Not Provided
  • Fix the creation of test database
  • Minor fix to new.js CLI to fix author param
  • fix package.json.jst
  • Update
  • Update controller example
  • Fix the creation of test database
  • Bug fix for a few nodal poly commands
  • seed selected models only
  • Add more information for how to use Model#hides
  • Allow Header Overrides on Controller Tests
  • fix migrations to ignore hidden files in the migrations directory
  • Allow Header Overrides on Controller Tests
  • Add typescript definitions.
  • Fix Typo in Comment for ModelArray#setAll
  • Fix Issue #310 Re: ModelArray#toObject
  • issue #328 - AcessToken.verify modified
  • Fixes issue with using functions with is comparators
  • Update model Array.from
nodal questions on Stackoverflow (View All Questions)
  • jquery ui dialog nodal messege doesn't center
  • How to update nodal value of Abaqus odb file using python script?
  • Creating an orphan mesh from nodal coordinates in abaqus using python
  • syncing 2 arrays into another (nodal connectivity)
  • How to get the nodal raw numbers (from all the trees for a particula test vector) from which random forest calculates the prediction in R?
  • Allow users to add nodal points of a region in space and the region can be color of user's choice.
  • python nodal/piecewise-linear power-law generator
  • Nodal graph in Qt for Programmable Flow Charts
nodal list of languages used
Other projects in JavaScript