Development Process¶
This page briefly describes a typical MEAN app development process.
Process¶
- Environment setup
Prepare OS
- Install node.js
- Install Mongodb
- Install global packages
- Yeoman and makrina Installation
Start project
- Use makrina Main app generator:
yo makrina
- Review generated files
- Review meta documents (
README, LICENSE, CONTRIBUTING, CHANGELOG
)
- Use makrina Main app generator:
Configure packages
- Review
package.json
- Review
gulpfile.js
- Start with
npm start
ornode bin/www
- Review
- Angular and front-end
- Bootstrapping
- Review
views/index.ejs
- Review Admin template
- Review and add js files in gulp
- Static template
- Add static files
- Style up
- Review and add sass/css files in gulp
- Angular setup
- Review
public/javascripts/app
folder - Review
karma.conf.js
for Tests
- Components
- Review list component
object-list.component.js
- Review list unit test
object-list.component.spec.js
- Module and file Organization
- Review
app.module.js
and inject any additional module dependency - Review list template
object-list.template.html
- Filters
- Add custom filters to list
- Extend e2e tests
- Review
protractor.conf.js
- Review e2e tests
e2e-tests/app.scenarios.js
- XHR
- Templating list
- Expand on the list template
- Angular Routing
- Template: review
ng-view
- Dependency: using
angular-route
. Reviewapp.module.js
- Configure in
app.config.js
- Review detail component
object-detail/object-detail.component.js
- Review detail module
object-detail.module.js
and inject inapp.module.js
- Extend e2e tests
- Templating detail
- Expand on the detail template
- Review
node-detail.component.spec.js
- Extend e2e tests
- Core module
- Review core module
core/core.module.js
and inject inapp.module.js
- Add custom filters in
core/filter_name/filter_name.filter.js
(optional) - Add unit tests in
filter_name.filter.spec.js
- Event handlers
- REST and custom services factory
- Dependency: using
angular-resource
- Review module
core/object/object.module.js
with dependency tongResource
- Review service
object.service.js
- Inject
core.object
tocore.module.js
,object-list.component.js
,object-detail.component.js
- Review unit test
object.service.spec.js
- Animations
- Dependency: using
angular-animate
inapp.module.js
- Review
app.animations.sass
- Review template: jquery loaded in head, relevant classes to
ng-view
- Extend animations with js
- Node and back-end
Models: Mongoose
- Review
services/mongoose.js
- Review and create
models/
- Review express-session in
services/session-config.js
- Add CSRF to non-Angular forms
- Review
newrelic.js
.
- Review
Routes: Express
- Review i18n urls in
services/i18n-config.js
androutes/index.js
- Connect Angular service to routes: review
routes/api/
.
- Review i18n urls in
Breadcrumb
Environment setup¶
Install Mongodb¶
- Latest Mongodb (at the time of writing) is v3.2.
- Ubuntu 16.04 comes with v2.6.
- Ubuntu 14.04 comes with v2.4 (see how to upgrade Mongo).
- Version 2.6 will be used throughout due to availability on hosts.
Install global packages¶
~/.nvm/v4.4.7/lib
├── gulp-cli@1.2.1
├── karma-cli@1.0.1
└── npm@3.10.6
Install with:
nvm install 4
npm update -g npm
npm install -g gulp-cli karma-cli
Angular¶
The outline follows the Angular tutorial. Gulpfile is configured to concatenate the angular app.
Sanitize¶
angular-sanitize
can be used to present a sanitized scope variable with ng-bind-html
.
To further sanitize HTML stored in db, the module mongoose-html can be used. The project is abandoned and has unmet peer dependencies so don’t install it directly, the relevant piece of code is very small and can be used directly.
It is based on sanitize-html which can be used at a lower level. It is not possible to easily use it though with custom validators as they do not return the value but only a boolean, and also they are yet harder to use within objects.
Tests¶
Unit tests¶
All unit tests can be invoked from npm test
, which essentially invokes gulp test
:
npm test
Unit tests involve front-end tests with karma and back-end tests with mocha.
Both provide coverage report using istanbul.
If browser is not starting, export CHROME_BIN
.
For fish see this fish configuration gist.
End-to-end tests¶
npm start
npm run protractor
Server needs to have started before. Protractor can only run in local. Protractor is tested only for Chrome due to #3044:
npm start
node_modules/protractor/bin/webdriver-manager update
node_modules/protractor/bin/protractor e2e-tests/protractor.conf.js
Extend tests¶
The generated unit tests cover 100% or nearly of the generated code. Nevertheless, the following files have been excluded out from testing and coverage:
- The object api endpoint route
routes/api/object.js
. It needs further development and custom test. - The mongoose service
services/mongoose.js
. This will get indirectly covered by the above. - The object angular components need further development.
Consequently, after developing the above, add the relevant files in the gulpfile.js
js_cover
section and
karma.conf.js
files
and preprocessors
section.
Admin template¶
The Gentelella admin theme is adapted into views/admin.ejs
.
The adaptations include:
- Most static files are loaded from minified output from gulpfile.
- Context is provided from
routes/admin.js
. - The main view is adopted for Angular route using
ng-view
. - Also, a
views/login.ejs
template has been added.
Lastly, the ng-gentelella package is used.
Mongoose¶
The files servives/mongoose.js
and models/object.js
need to be reviewed.
Models are used in routes by requiring:
var mongoose = require('mongoose');
var Object = mongoose.model('Object');
Mongoose quick reference¶
Sanitize and injection¶
Mongodb injection is very much possible
with mongo queries, especially when a where criterion is provided from a public form or url.
The module mongo-sanitize can be easily used to sanitize
req.body
and req.query
from mongo $
operators.
CSRF¶
CSRF protection is ensured by the Csurf package.
Angular forms respect CSRF due to the XSRF-TOKEN
cookie that we make in app.js
.
All other forms require manual append of CSRF:
- In router context:
context.csrf = req.csrfToken();
- In forms:
<input type="hidden" name="_csrf" value="<%= csrf %>">
The responses are automatically checked by the module and 403 is returned appropriately. This is tested in mocha too.
Updates¶
Most generated code gets signed by the Makrina version and date in a comment at the top of file.
All changes are documented in CHANGELOG.md
. Any change that may affect existing generated files
is marked with a warning sign. Usually changes in existing files that may have been generated
in existing projects exist in minor releases (version numbering: major, minor, revision).
If you feel like using a latest feature or change, you can manually update the relevant files, and append the Makrina version in the comment for future reference:
* Updated to yeoman generator-makrina <%= version %> on <%= date %>.
Or re-run the generator by carefully selecting which files to replace when asked.