ndx-framework

a robust, modular, friendly javascript app framework

• based on trusted technologies (express, angular1) with an emphasis on stability, scalability, code clarity and rapid development.
• ndx-framework uses coffeescript, pug/jade and stylus to keep your codebase tight and legible
• npm and bower support
• fully platform independent
• promotes modularity
• ndx-framework modules are easy to author, especially if you are already acquainted with express servers
• there are already many ndx-framework modules to make common tasks simple, eg user management/user roles/sockets/server syncing
• easy to integrate server profiler
• ssl, tokens, oauth2
• designed to run with a small footprint in constrained environments eg heroku
• built-in lightning fast in-memory sql/nosql/nodb ndxdb that treats javascript objects as first-class citizens and can persist data to s3 in a cost effective/performant manner
• any other database can easily be plugged in, see ndx-database-engine

index

• getting started
• grunt
• yeoman
• environment variables
• commonly used environment variables
• ssl
• modules
• the ndx object
• currently available modules
• api routes and users
• authenticating api routes
• connect to the app
• app monitor
• running your app in production
• the difference between .use() and .controller()
• error handling
• anatomy of an ndx-framework web app
• generated folders
• coming soon

getting started

ndx-framework requires node and npm so make sure you have them installed by typing node -v and npm -v

• install and initialize ndx-framework

    npm install -g ndx-framework
    ndx-framework --init
  

• create an app

    ndx-framework --create --appname=appName
  

• navigate to http://localhost:3000

grunt

ndx-framework uses grunt to run and livereload your app while in development
from within the app folder you can start your app by typing

    grunt

to build your app for production

    grunt build

when adding files to your project you might need to stop and restart grunt

yeoman

ndx-framework uses yeoman to generate/scaffold apps
from within the app folder you can run generator-ndx generators to build out your app

environment variables

we encourage the use of environment variables to store sensitive settings (AWS key etc)
other settings can be passed into the ndx-server .config() function in src/server/app.coffee

commonly used environment variables

ndx-server

ndxdb

other modules may require their own environment variables, check that module’s homepage to see what you need to set

ssl

set the SSL_PORT=[portNo] environment variable and drop key.pem and cert.pem into the app directory

modules

ndx-framework is built around modularity.
all npm installed ndx modules and all user modules in /startup, /services and /controllers get loaded automatically server modules are simply a function that receives the ndx object and adds functionality to it
src/server/app.coffee

require 'ndx-server'
.config
  database: 'db'
.controller (ndx) ->
  ndx.app.get '/', (req, res, next) ->
    res.end 'hi from ndx!'
.start()

as your app grows you’ll find it easier to keep the code for your modules seperate
src/server/controllers/first.coffee

module.exports (ndx) ->
  ndx.app.get '/', (req, res, next) ->
    res.end 'hi from ndx!'

you can also publish your modules to npm
modules installed this way don’t neeed requiring
src/server/app.coffee

require 'ndx-server'
.config
  database: 'db'
.controller 'ndx-static-routes'
.start()

making a module

currently available modules

server modules - install with npm install --save module-name

client modules - install with bower install --save module-name

if you make any cool modules let us know and we’ll add them to the list

the ndx object

the ndx object gets passed to each controller and service

properties

• ndx.app - the express app
• ndx.server - the express server
• ndx.database - the database
• ndx.settings - server settings
• ndx.host - server host
• ndx.port - server port

methods

• ndx.generateHash(string) -> hashed string
• ndx.validPassword(password, hashedPassword) -> bool
• ndx.authenticate() middleware to authenticate a route, see ndx-user-roles for a more robust implementation
• ndx.postAuthenticate(req, res, next) used internally
• ndx.generateToken(string userId, string ip) -> new user token
• ndx.setAuthCookie(req, res) used internally

other modules can add extra properties and methods to the ndx object, eg ndx-passport which adds ndx.passport for the other passport modules to use.

api routes and users

all routes that start with api/ get the currently logged in user as ndx.user, eg
npm install --save ndx-passport
src/server/app.coffee

require 'ndx-server'
.config
  database: 'db'
.controller (ndx) ->
  ndx.app.get 'api/test', (req, res, next) ->
    if ndx.user
      res.end "Hi #{ndx.user.local.email}"
    else
      next 'not logged in'
.start()

ndx-user can not be relied upon in async situations
we recommend that you wrap it in a closure before going async, eg

ndx.app.get 'api/async', (req, res) ->
  ((user) ->
    asyncFunction ->
      ndx.user = user
  )(ndx.user)
### authenticating api routes
without roles  
`npm install --save ndx-passport`  
`src/server/app.coffee`
```coffeescript
require 'ndx-server'
.config
  database: 'db'
.controller (ndx) ->
  ndx.app.get 'api/protected', ndx.authenticate(), (req, res, next) ->
    res.end 'you\'re cool'
.start()

with roles, using ndx-user-roles
npm install --save ndx-passport ndx-user-roles
src/server/app.coffee

require 'ndx-server'
.config
  database: 'db'
.controller (ndx) ->
  ndx.app.get 'api/protected', ndx.authenticate(['admin', 'superadmin']), (req, res, next) ->
    res.end 'you\'re cool'
.start()

connect to the app

add these modules npm install --save ndx-cors ndx-user-roles ndx-auth ndx-superadmin ndx-connect
then type ndx-framework to open the interactive app connector

> ndx-framework
ndx framework v0.0.1
type help for a list of commands
hit Ctrl-C to exit
ndx> login
host> localhost:3000
username> superadmin@admin.com
password>
successfully connected to http://localhost:3000
ndx> backup list
Sun Jan 29 2017 12:10:02 AM
Sun Jan 29 2017 12:12:03 AM
Sun Jan 29 2017 08:38:00 AM
Sun Jan 29 2017 10:38:00 AM
Sun Jan 29 2017 12:38:00 PM
Sun Jan 29 2017 02:38:00 PM

app monitor

you can use ndx-appmonitor to monitor the status of your app in realtime
npm install --save ndx-cors ndx-profiler ndx-user-roles ndx-auth ndx-superadmin
to monitor local apps git clone ndx-appmonitor then run it with grunt
for live apps you can use this pen

running your app in production

build your app with
grunt build
remember to set NODE_ENV=production
then run the app using
node --expose-gc server/app.js
the --expose-gc flag is optional - if you include it ndx-server will do some extra garbage collection which can help keep memory use down (especially useful if you are working with third party packages that might be a bit leaky)

the difference between .use() and .controller()

the only real difference is a matter of timing, both are called on app start and both receive a reference to the ndx object
.use modules get loaded before .controller modules
we recommend that you use .use modules for services and long running operations which will usually add themselves to the ndx object for other modules to use down the line
.controller modules are for api routes etc

error handling

to handle an error within an api route simply call next() with an error message or an object containing a status code and error message

module.exports = (ndx) ->
  ndx.app.get 'api/error', (req, res, next) ->
    if ndx.user
      if ndx.user.local.email is 'a@a.com'
        res.end 'you\'re cool'
      else
        next 'i don\'t like you'
    else
      next
        status: 401
        message: 'not authorized'

anatomy of an ndx-framework web app

generated folders

You should generally avoid messing with these folders

coming soon

- clientside database
- clientside subscriptions to database events
- more generators
- build for mobile
- better documentation
- docker/kubernetes documentation
- testing (e2e/system) documentation