@atlas.js

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

Tutorials

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)

Components

Atlas

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.)

Service

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).

Hook

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).

Action

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.

Installation

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. 🎉

Usage

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!
atlas.start()
.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!

License

See the LICENSE file for information.

romeopatrick11 / atlas.js