A component-based Node.js library to reduce boilerplate and provide sane project structure 🍻
Switch branches/tags
@atlas.js/templates@1.0.2 @atlas.js/templates@1.0.1 @atlas.js/templates@1.0.0 @atlas.js/templates@0.1.3 @atlas.js/templates@0.1.2 @atlas.js/templates@0.1.1 @atlas.js/templates@0.1.0 @atlas.js/service@1.1.1 @atlas.js/service@1.1.0 @atlas.js/service@1.0.2 @atlas.js/service@1.0.1 @atlas.js/service@1.0.0 @atlas.js/service@0.1.0 @atlas.js/service@0.0.4 @atlas.js/service@0.0.3 @atlas.js/service@0.0.2 @atlas.js/service@0.0.1 @atlas.js/sequelize@2.0.1 @atlas.js/sequelize@2.0.0 @atlas.js/sequelize@1.1.0 @atlas.js/sequelize@1.0.1 @atlas.js/sequelize@1.0.0 @atlas.js/sequelize@0.4.0 @atlas.js/sequelize@0.3.0 @atlas.js/sequelize@0.2.1 @atlas.js/sequelize@0.2.0 @atlas.js/sequelize@0.1.1 @atlas.js/sequelize@0.1.0 @atlas.js/repl@2.0.2 @atlas.js/repl@2.0.1 @atlas.js/repl@2.0.0 @atlas.js/repl@1.0.2 @atlas.js/repl@1.0.1 @atlas.js/repl@1.0.0 @atlas.js/repl@0.2.0 @atlas.js/repl@0.1.6 @atlas.js/repl@0.1.5 @atlas.js/repl@0.1.4 @atlas.js/repl@0.1.3 @atlas.js/repl@0.1.2 @atlas.js/repl@0.1.1 @atlas.js/repl@0.1.0 @atlas.js/repl@0.0.2 @atlas.js/repl@0.0.1 @atlas.js/objection@2.1.1 @atlas.js/objection@2.1.0 @atlas.js/objection@2.0.0 @atlas.js/objection@1.1.1 @atlas.js/objection@1.1.0 @atlas.js/objection@1.0.0 @atlas.js/objection@0.4.0 @atlas.js/objection@0.3.1 @atlas.js/objection@0.3.0 @atlas.js/objection@0.2.0 @atlas.js/objection@0.1.2 @atlas.js/objection@0.1.1 @atlas.js/objection@0.1.0 @atlas.js/nodemailer@2.0.1 @atlas.js/nodemailer@2.0.0 @atlas.js/nodemailer@1.0.3 @atlas.js/nodemailer@1.0.2 @atlas.js/nodemailer@1.0.1 @atlas.js/nodemailer@1.0.0 @atlas.js/nodemailer@0.3.0 @atlas.js/nodemailer@0.2.3 @atlas.js/nodemailer@0.2.2 @atlas.js/nodemailer@0.2.1 @atlas.js/nodemailer@0.2.0 @atlas.js/nodemailer@0.1.1 @atlas.js/nodemailer@0.1.0 @atlas.js/nodemailer@0.0.2 @atlas.js/nodemailer@0.0.1 @atlas.js/mongoose@3.1.0 @atlas.js/mongoose@3.0.2 @atlas.js/mongoose@3.0.1 @atlas.js/mongoose@3.0.0 @atlas.js/mongoose@2.0.0 @atlas.js/mongoose@1.1.0 @atlas.js/mongoose@1.0.1 @atlas.js/mongoose@1.0.0 @atlas.js/mongoose@0.3.0 @atlas.js/mongoose@0.2.0 @atlas.js/mongoose@0.1.3 @atlas.js/mongoose@0.1.2 @atlas.js/mongoose@0.1.1 @atlas.js/mongoose@0.1.0 @atlas.js/koa@3.1.1 @atlas.js/koa@3.1.0 @atlas.js/koa@3.0.0 @atlas.js/koa@2.0.0 @atlas.js/koa@1.2.0 @atlas.js/koa@1.1.1 @atlas.js/koa@1.1.0 @atlas.js/koa@1.0.0 @atlas.js/koa@0.5.0 @atlas.js/koa@0.4.0 @atlas.js/koa@0.3.3 @atlas.js/koa@0.3.2 @atlas.js/koa@0.3.1 @atlas.js/koa@0.3.0
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.vscode chore: add VS Code Launch configuration Jul 6, 2018
test chore: Switch back to sinon-chai May 10, 2018
.commitlintrc.js chore: switch to commitlint May 11, 2018
.gitignore feat(generator): include local.mk in the output Jul 12, 2018
.languagebabel chore: Add Atom's language-babel config Nov 1, 2017
.travis.yml build: update NPM_TOKEN in Travis config Jul 16, 2018
makefile chore: disable lerna's hoisting Aug 20, 2018
package.json chore: upgrade deps 💣 Nov 2, 2018


Atlas.js @atlas.js

Build Status Coverage Status Built with GNU Make Required Node.js version Greenkeeper badge

Built with ❤️ at STRV

Atlas.js is a component-based library for writing Node.js apps of all kinds of purposes. Its main goal was to encapsulate common application boilerplate code into a set of small, reusable components so that you can focus on writing code specific to your needs. You just provide the configuration for each component and you are good to go.

Available components

Here is a list of STRV-maintained components.

Component Version Info
@atlas.js/atlas @atlas.js/atlas The main package with everything needed to get rolling
@atlas.js/cli @atlas.js/cli A CLI utility to manage your Atlas app
@atlas.js/generator-atlas @atlas.js/generator-atlas Yeoman generator to quickly scaffold your new Atlas app
@atlas.js/aws @atlas.js/atlas For interfacing with AWS
@atlas.js/braintree @atlas.js/atlas For interfacing with Braintree payments
@atlas.js/firebase @atlas.js/atlas For interfacing with Firebase services
@atlas.js/koa @atlas.js/atlas Service and hooks for implementing Koa-based HTTP APIs
@atlas.js/mongoose @atlas.js/atlas Service and hooks for working with MongoDB and Mongoose models
@atlas.js/objection @atlas.js/atlas Service and hooks for working with Objection.js
@atlas.js/sequelize @atlas.js/atlas Service and hooks for working with Sequelize
@atlas.js/nodemailer @atlas.js/atlas Generic emailing service with support for multiple providers
@atlas.js/repl @atlas.js/atlas A component to drop into an interactive shell with Atlas loaded
@atlas.js/templates @atlas.js/atlas Action for rendering templates into html strings using consolidate.js

Did not find what you were looking for? Write your own! Check the tutorials linked below.


Need help? Check out the tutorials folder for... well... tutorials. 🤓

Core ideas

What this is?

  • A lightweight, component-based state management container
  • A tool to speed up application development by not having to write the same boilerplate code over and over again

What this is not?

  • An MVC framework
  • A microservices framework (you can certainly use this to build microservices, it just does not contain the functionality that such a framework should have)



The Atlas class is the primary container holding and managing your services. It provides a very basic functionality which consists of:

  • Gathering and distributing all of your configuration to all registered components
  • Managing your components' lifecycle (starting/stopping services, running hooks etc.)


A Service is a component which usually connects or interacts with an external service or other interface (like a database). The most common trait of all services is that they have state - ie. an open connection. The purpose of a Service component is to manage that state for you so that you don't have to (ie. connecting, reconnecting and disconnecting from a database).


A hook is basically an event listener which can react to various application lifecycle events (ie. when the application is about to start or just before stopping). A hook is a great way to perform custom actions when particular things happen within the Atlas container (ie. run database migrations when starting).


Actions are a group of stateless functions which receive some input and generate an output. Their use within Atlas.js is completely optional but they are a great place to put business-specific code. Their main benefit is that they are reusable - you could call an action either from a CLI utility or from a route handler - they do not depend on the surrounding context.


You always need to install the main atlas package:

npm i --save @atlas.js/atlas

If you want, you can install any of the official components (you can always write your own if none of them suit your needs). Let's install the koa component:

npm i --save @atlas.js/koa

That's it! Nothing else needs to be installed. 🎉


This is a complete usage example. Real world apps would split at least the configuration part out into its own module instead of writing it inline like this.

Also, you may want to check out Atlas.init(), which initialises all the components for you based on file/folder layout you specify. 💪

If you would like to take the easy road, check out our Yeoman generator to quickly generate the basic folder structure and install all the needed things.

// We start by importing the required components...
import { Atlas } from '@atlas.js/atlas'
import * as Koa from '@atlas.js/koa'

// Now we need an instance of Atlas, so let's make one
const atlas = new Atlas({
  // We MUST specify the root folder where our app resides
  // This should usually point to the folder where your package.json resides
  root: __dirname,
  // Setting env is optional and it fallbacks to NODE_ENV, of course
  env: process.env.NODE_ENV,
  // This is where all the configuration data should be specified, for all the components
  config: {
    // Configuration for services
    services: {
      // The `http` configuration will be given to the service which we will name as `http`
      // (see the `atlas.service()` call below)
      http: {
        // This goes to the `listen()` function call
        listen: {
          port: 3000,
        // Any properties which Koa supports can be set here
        koa: {
          proxy: true,
    // Configuration for actions
    actions: {},
    // ...aaand configuration for hooks
    hooks: {},

// We need to add the components we want to use to the application
// The first argument is the component's name - it will be used to locate the component's configuration and also the service will be exposed on that property:
// `atlas.services.http`
atlas.service('http', Koa.Service)

// Great, we can finally start the app!
.then(() => console.log('ready!'))
.catch(err => console.error(err))

export default atlas

The configuration options each component accepts are documented in their own package repository/folder.

Great... what now?

So you have an app with a Koa service configured and running... Great! But you probably wonder where to define your middleware and routes and all the other important things? You should check out the tutorials folder for much more info!


See the LICENSE file for information.