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

| environment | config | required | description | |-------------|----------|-----------|--------------------------------------| |PORT |port |Yes |the port your app will run on | |SSL_PORT |sslPort |No |https port, see ssl | |SESSION_SECRET|sessionSecret|No|used for encryption, it's good practise to set this one| |SKIP_IP_ENCRYPT|skipIpEncrypt|No|by default tokens are IP encrypted, some servers don't like this - set it to false to skip this stage| |AUTO_ID|autoId|No|the id column name, defaults to _id| |USER_TABLE|userTable|No|database table name to store user data, defaults to users| | - |dbEngine|No|database engine to use, defaults to require('ndxdb')| | - |publicUser|No|an object describing which user fields get sent to the client, eg {_id:true,local:{email:true},roles:true}|

ndxdb

|Environment|Config|Required|Description | |-----------|------|--------|------------------------------------------------------------------| | - |tables|Yes |an array of database table names eg ['users','houses','friends']| |LOCAL_STORAGE|localStorage|No|local folder for data storage, eg data or ../data| |AWS_BUCKET|awsBucket|No|AWS bucket name for S3 data persistence| |AWS_REGION|awsRegion|No|defaults to us-east-1| |AWS_ID|awsId|No|your aws id| |AWS_KEY|awsKey|No|your aws key|

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

|name|description| |----|-----------| |ndx-auth| oauth2 authentication routes | |ndx-connect| lets authenticated users connect to the database to perform arbitrary operations | |ndx-cors| adds cors support to api/ routes | |ndx-database-backup| schedule regular database backups | |ndxdb|super-flexible alasql based database | |ndx-framework| this package | |ndx-gmail| sends email through gmail | |ndx-keep-awake| creates and regularly calls an api/ route, this is useful to stop your app going to sleep on hosts where that is a thing (heroku) | |ndx-memory-check| makes an admin authenticated route to check the current memory usage | |ndx-modified| adds modifiedAd and modifiedBy fields to all database updates and inserts | |ndx-passport| provides basic login functions and local user login | |ndx-passport-facebook| facebook oauth login | |ndx-passport-twitter| twitter oauth login | |ndx-passport-github| github oauth login | |ndx-permissions|role based database permissions | |ndx-profiler| collects server stats which can then be collected with ndx-appmonitor | |ndx-publish| publishes database collections for the client to subscribe to | |ndx-rest| automatically generate rest endpoints from your database | |ndx-scheduler|schedule server events | |ndx-server| the server | |ndx-socket| adds websockets | |ndx-static-routes| static routes to serve up the angular app src/client and the public/ folder | |ndx-superadmin| creates a default superadmin user then nags you to change her password | |ndx-sync| synchronizes two or more instances of an ndx-framework app using websockets - provides horizontal scaling when using in-memory (and other) databases | |ndx-timezone| a service for converting dates to a user's timezone with daylight savings| |ndx-user-roles| authenticate api/ routes using roles |

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

|name |description | |-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| |ndx-auth|clientside role based authentication, for use in conjunction with ndx-user-roles|
|ndx-error-redirect|redirect on server errors| |ndx-rest|rest client, to complement ndx-rest| |ndx-pagination|simple angular list paginator| |ndx-scroll-top|scroll to top on page change| |ndx-timezone|collects user's timezone data, for use with ndx-timezone |

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> [email protected]
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 '[email protected]'
        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

| route | description | |-------------------------|------------------------------------| | src/client/ | the angular app | | src/client/directives/| a place to keep angular directives | | src/client/filters/| angular filters | | src/client/routes/| put your routes in here | | src/client/services/| angular services | | src/client/app.coffee| the main angular module | | src/client/app.stylus| global styles, local stylus files should be kept in the relevant directive/route folder | | src/client/index.jade| the page that runs your site, includes dependency injection to automatically include all your scripts and css | | src/client/variables.styl| a place to put your stylus variables | | src/server/| the web server | | src/server/controllers/| keep your app controllers in here | | src/server/services/| app services | | src/server/app.coffee| the main app file - configures and starts ndx-server, register your modules/controllers/services in this file | | public/| statically served resources, put your images/fonts/favicons in here, eg img(src='public/images/logo.png') |

generated folders

You should generally avoid messing with these folders

| route | description | |-----------|------------------| | bower/ | bower components | | build/| the clientside app, served only in dev mode NODE_ENV=dev | | dist/| the built clientside app, served in production mode NODE_ENV=production | | node_modules/| node modules | | server/| the built web server|

coming soon

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