A boilerplate of RESTful API server that provides abilities to register, login, and look-up user profile. It enables uses of JWT-based for user authentication and verification. The sample of client-side application that interacts with this API can be found at node-rest-client repository.
- koa2 - An expressive async and middleware web framework for Node.js
- knex.js - A "batteries included" SQL query builder and migration
- Objection.js - An SQL-friendly ORM for Node.js, built on an knex query builder
- ObjectModel - A delightful JS testing framework
- Joi - A validator library for JavaScript objects
- Bull - A background job queue for Node.js
- Jest - Just don't let tests get in your way
- supertest - HTTP integration assertions tests
- eslint - The pluggable linting utility for JavaScript
- standardjs - An opinionated JavaScirpt style guide
- JWT-based Authentication - JSON Web Tokens authentication
- NodeMailer - A email client library for Node.js
- UPASH Unified API for PASsword Hashing algorithms
- Docker - This app supports bundling into Docker containerization
Coded with ❤️ by Jason Yeh.
In order to be able to send outgoing emails, you will need to configure the SMTP setup to the .env
file on root of the directory:
SMTP_HOST=smtp.mailgun.org
SMTP_USER=postmaster@XXXXXXXXXXX.mailgun.org
SMTP_PASS=XXXXXXXXXXX
Build and run using Docker Compose:
$ docker-compose up
This Docker builds will load containers including Server API, Client App, Queue Worker, PostgreSQL DB, and Redis. The client app can be found at http://localhost:8080, the Server API is served at port 3000
.
- Node.JS 10+ LTS
- PostgreSQL 9 or higher (or available via Docker container)
- Redis
- Yarn
- Docker (optional)
- A SMTP Server details to send outgoing emails
Firstly, you need to install this package.
$ yarn
Note: You can replace
yarn
withnpm
command, both will work the same.
Add some configuration setup via .env
file:
SMTP_HOST=smtp.mailgun.org
SMTP_USER=postmaster@XXXXXXXXXXX.mailgun.org
SMTP_PASS=XXXXXXXXXXX
PGHOST=localhost
PGPORT=5432,
PGUSER=postgres
PGPASSWORD=XXXXXX
PGDATABASE=api-dev
Finally, run the Server API:
$ yarn start
or, in developer mode with autoreload (nodemon
):
$ yarn run dev
Note: Please make sure you don't forget create database (it's currently default to
api-dev
) before you start, or alternatively to use this script to create and migrate database automatically:$ yarn run server:init
The API is served at http://localhost:3000/api/v1, please see the API documentation below for details.
This application also includes migrations tools to allow for you to define sets of schema changes so upgrading a database is a breeze. Here are the collection of user commands you can use to build, update, or rollback the database migration scripts:
yarn run server:init
- Automatically create new databases, run migration, and then start app.yarn run db:setup
- Automatically create new databasesyarn run db:make
- This commands allows you to create a new migration scripts (i.e.yarn run db:name {name}
)yarn run db:latest
- Upgrade all the schema migrations scripts to the latest versionyarn run db:rollback
- Rollback to the previous successful migration scriptyarn run db:seed:make
- Create a seeding file (i.e.yarn run db:seed:make {name}
)yarn run db:seed:run
- Run seeing files to load data into databasesyarn run db:reset
- Rollback and then repeat the migrate script again
yarn run worker
- This is the command to run service worker separately from main appyarn run lint
- Runs a code linting report over your existed codeyarn run lint-fix
- Runs lint and automatically fix themyarn run test
- Runs unit and integration testsyarn run test:watch
- Runs a fast interactivewatcher mode
that runs only test files related to changed files.yarn run test:coverage
- Run this command gets you a full code coverage report, open the HTML report file (./coverage/lcov-report/index.html
) for the extensive "visual" code coverage report.
Here are the high-level API documentation:
- [GET]
/boom
- KABOOOMMMM! - [GET]
/ping
- Receives health status and the datetime - [GET]
/api/v1/user
[AUTH] - Retrieve user profile - [GET]
/api/v1/user/confirm/{:token}
- Email Confirmation from email notification - [POST]
/api/v1/user/register
- User Registeration - [POST]
/api/v1/user/authenticate
- User Login
As of today, ES6 module is not yet supported in Node.JS and is still in the experimental stage. ES6 Module and TypeScript will require us to transpile the code, therefore is not a native server-side language since it transpiles into standardized JavaScript code with polyfills. In order to troubleshooting, you will need source map to understand the transpiled code which becomes more difficult to operate via the server-side.
Well, the idea was to keep the client, and server-side agnostic from each other yet communicates via Web Server API. It gives us an easier time to maintain a subset of application and scale our team as we continue to grow. I have considered using Mono repo
architecture to bundle two of our modules together into the same repository, and this allows us to maintain two sides of applications within the same subset of a testing platform and source repository. It should take me a day to implement them together. Unfortunately, I didn't have much time left for this idea.
Node.JS is perfect for IO-heavy application, Data-intensive real-time Apps, API-Driven (Micro) Services, and Streams (processing data on the fly). However, Node.JS is not so great for Serving Static Files, CPU-bound application, or creating a Monolithic application. Depending on many factors, we could consider using Load Balancing Server (HaProxy, gobetween, Traefik), Separate SSL Termination Server (Stud, NGiNX), Serve GZIP Compression separately (use NGiNX front), and Serving Static Assets separately (NGiNX, Varnish, or CDN). Node.JS serves really well as highly concurrent networking application, but significant of time the issues tend to be IO-bound and encouraged to offload into other worker or (micro)services.
- The internal-side of
config
loader design can be improved, and we could try loaddotenv
module once instead of per each subset config files. - Add a universal
Logger
tools for debugging and integration with centralized log collection service. - API Documentation, possibly using auto-generator tools. Consider improving code documentation using JSDoc tools.
- Improve more integrated environment configuration in between
.env
environment file anddocker-composer.yml
file. - The code coverage is shallow, we should continue to add more unit and integration tests to improve code assurance. Consider integration with [Coveralls]](https://coveralls.io/) or Codecov for visual code coverages and Continuous Integration (CI) service.
- If we increase services and data modules, we can move up
src/routes.js
into a separateroutes
folder with a collection of multiple routing files. So goes the same for the serviceworkers/
folder.
MIT