Giter VIP home page Giter VIP logo

koan's Introduction

KOAN

Build Status

KOAN Stack is a boilerplate that provides a starting point for full stack JavaScript Web development with Koa, AngularJS, and Node.js along with MongoDB and WebSockets. A summary of tech stack:

  • Client: AngularJS and Bootstrap. Client side is fully static and CDN ready. All client packages are located at client\bower_packages.
  • Server: Koa for RESTful API serving on Node.js. ES6 async/await functions all the way!
  • WebSockets along with JSON-RPC is used for real-time client-server communication and browser sync.
  • OAuth 2 is used for social authentications. Instead of auth cookies, we use JWT along with HTML5 local storage.
  • Grunt tasks are used to facilitate development and testing.
  • MongoDB for persistence.

Live Example

Below are the screenshots from the bundled demo app, which is a Facebook like real-time sharing app. Follow instructions in the next section if you want to play with it locally, or deploy it to Heroku.

Login page:

Login Page

User home page:

Home Page

Getting Started

Make sure that you have Node.js v7.6 or higher (for Node <7.6, use v1.6 release), and MongoDB v2 or higher (running on the default port 27017) installed on your computer. To get started with KOAN stack, do following:

git clone --depth 1 https://github.com/soygul/koan.git
cd koan
npm install
npm start

Your application should run on the 3000 port so in your browser just go to http://localhost:3000. If you want to run tests, simply type:

npm test

Configuration

All configuration is specified in the /server/config directory, particularly the config.js file. Here you can hook up any social app keys if you want integration with Twitter, Facebook, or Google.

Heroku Deployment

Deploy

Procfile and app.json are making this repo readily available for Heroku deployment. You can start by clicking the above button.

Testing

You can run all the tests with npm test. Tests are run with:

  • Client (unit): Jasmine + Karma (Angular default)
  • Client (e2e): Jasmine + Protractor (Angular default)
  • Server: Mocha/SuperTest/Should (Koa default)

See /test/server/users.js for an example.

Credits

Client side is entirely based on the official: Angular Seed. Server side simply utilizes generally accepted Koa middleware and Node.js best practices.

The Name

The project name is an acronym for Koa, Angular, and Node. It also is the name for a Zen Buddhist riddle used to focus the mind during meditation and to develop intuitive thinking.

License

MIT

koan's People

Contributors

ilyachenko avatar soygul avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

koan's Issues

'npm postinstall' gulp tasks

On production environments, we need grunt tasks to execute on 'npm postinstall' and do following:

  • Use *.min.js files if available, in place of regular .js files
  • Generate a random JWT secret (or better public/private key pair) and write it to the config.js file
  • We need to create and put processed files in a Dist folder.
  • We need to process config file not to have development configuration info in them for release builds.
  • Optionally, we can ng-annotate the js files, ng-html2js the templates, and merge everything into a single js/css file (though this hinders bug hunt in release builds as it will obscure exception stack traces so this is debatable)
  • Possibly a lot more..

Refactor server configurations

Configuration options are leaking all over the code. Even the project name (KOAN) is used in many different places in plain text. Consolidate all config options in config.js

Specify dependency version numbers

Once the core is more stable, we really need dependency numbers in package.json and bower.json in place of "latest" tags.

It's also good to use ranged versions only locking the major version like "koa-logger": "~1"

Store state information in ctx.state

The is new Koa recommendation to store request state info is ctx.state namespace. We have lots of this.user as state info and can make them into this.state.user but that kind of adds verbosity so this is to be evaluated further.

Why differ from using monogoID for the new user?

Hello,
First I have to thank you for this project. You have save me countless hours attempting to organize all of this on my own.

Question: When you create a new user you are not using the default mongoID. Why are you using a sequence instead?

// get the latest userId+1 as the new user id
// this is exceptional to user creation as we want user ids to be sequential numbers and not standard mongo guids

Create koa-ws (or co-ws) package for notifications + bidirectional JSON RPC 2.0 over WebSockets

We now have this implemented over several files. We can make a proper npm package (or use an existing one if such thing exists) for this exact purpose.

WebSocket reconnect with exponential back-off is important. We can use code from one of:

which is basically:

function createWebSocket () {
  var connection = new WebSocket();

  connection.onclose = function () {
    setTimeout(function () {
        // Connection has closed so try to reconnect every 10 seconds.
        createWebSocket(); 
    }, 10*1000);
  }
};

This is related to #16.

Use access_token query param in place of HTTP authorization header

HTTP authorization header forces browser to do and additional preflight request (OPTIONS) before the actual request so it is better to simply stick to access_token=JWT query param.

This will also require a pull request to koa-jwt module as query token feature is not implemented yet.

Add tests

Add tests w/:

  • Server: Integration tests with Mocha + Karma
  • Client: Unit tests with Jasmine + Karma
  • Client: End to end (system) tests with Jasmine + Protractor

Also divide grunt test task into test:client-unit, test:client-e2e, test:server tasks.

Note: Client side tests should run in a real browser (Chrome by default) in a development environment rather than PhantomJS (which is the default for test environment like Travis). This sort of usage schema is nicely laid out in angular-seed tests.

Fix Passport.js implementation

Currently implementation is just a stub so expand it into real working stuff along with proper configuration options.

Unsubscribe from events automatically in controllers

Controllers get instantiated each time the user browses to the same route so not unregistering from events inside controllers will prevent controller destruction. Users can always manually unregister from events using $scope.$on('$destroy', fn) but we can automate this process during event registration with a stub like following:

event.subscribe($scope, fn) {
  callbacks.add(fn);
  $scope.$on('$destroy', event.unsubscribe(fn));
}

AngularJS modular architecture

Currently we're using angular-seed repo 1:1 in our client app. However this is very basic and does not incorporate a modular structure. There are great examples of that out there like:

We might however just wait for angular-seed to migrate to a more modular architecture (probably with angular 2.0). So there is a decision to be made here.

Implement post search feature

This could be implemented as a real-time search if MongoDB 2.6 full-text search feature becomes available. Otherwise regex search would be too slow for real-time searching.

Add client side configuration file

Basic things like app name, home title (KOAN Home) is all plain text. Put these configurable stuff in a simple configuration file in a central location (maybe not?)

Also rename comments/docs like "KOAN configuration ..." to "App configuration ..." so that rebranding will be easier.

Refactor code

Code is getting rather cluttered and duplicated in places. Review, refactor, and simplify the code (especially ws and controllers).

Also we should use a lot more of jsdoc to properly document a lot of the design choices and the code in general.

Simplify login

Remove the separate login.html page (and jquery dependency - still needed for bootstrap though).

Instead make the first landing page the credentials page, which redirects to home if token is in localstorage already. I don't know if this would look nice or flicker so needs experimentation.

WebSocket connection failed

Hi soygul,

This problem show up recently.

WebSocket connection to 'ws://localhost:3000/?access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImNodWNrQGtvYW4uaGVyb2t1YXBwLmNvbSIsIm5hbWUiOiJDaHVjayBOb3JyaXMiLCJpZCI6MiwicGljdHVyZSI6Ii9hcGkvdXNlcnMvMi9waWN0dXJlIiwiaWF0IjoxNDI3ODIzNDEwLCJleHAiOjE0MzU1OTk0MTB9.2EjG683rHAAK6oexDJw_vzD6m3aDeT5BTrsKgy0Sdo4' failed: HTTP Authentication failed; no valid credentials available

After digging, I found it is caused by koa-jwt update.
[email protected] is workable.

I think you might need to specify the version or fix the hack in ws.js
(https://github.com/soygul/koan/blob/master/server/config/ws.js#L29)

Don't use absolute urls in templates

It makes serving angular from a sub-directory a nightmare.

Also need to test this from a sub-directory and make sure that everything works as expected.

Mocha explosion!

grunt test doesn't pass.

Mocha test of server side code fails with:

"SyntaxError: Unexpected token *"

Separate infrastructure related code from sample app implementation

Mixing infrastructure related code with sample app implementation code makes merging changes from KOAN repo into user's own app repo very hard. For instance in client/js/services.js file contains the REST API client and WebSocket client implementations as well as sample app related endpoint code. This is quite confusing when resolving merge conflicts while pulling KOAN repo. Following files are specially problematic:

  • client/*.html
  • client/partials/*.html
  • client/js/*.js
  • server/config/mongo-seed.js
  • server/config/mongo.js
  • server/controllers/*.js
  • server/controllers/*.js
  • test/**/*.js
  • probably even more..

We can even separate the sample app implementation into a sub directory like /example.

Also implementing things like chat box (IM window) as re-usable addons may remove lots of clutter and possible merge conflict headaches.

Do not store user picture path in JWT token or the database

Current user object refs stored in the database and JWT token are like {id:1, name: ..., picture: '/api/users/:id/picture'}

Picture path is really something that needs to be resolved during runtime. It also should not be embedded in the JWT token as it makes the token very long. It is a shame that this even slipped through!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.