LiftOff Jumpstarter REST API Server Kit
A feature-packed boilerplate for building a REST API server using Node.js
Most of the web applications have a common set of features, both basic and advanced that are more than often rewritten from scratch. Using any kind of boilerplate allows us to focus directly on the actual business logic instead of reinventing the wheel.
With this ideology in mind, we created Jumpstarter to use it as a starting point for many of our projects. Besides the obvious “jumpstart” that we get, this also facilitates code reuse and knowledge sharing within the organization.
Overview of the main components
Jumpstarter is an opinionated boilerplate for building RESTful web applications using Node.js. It uses Hapi.js as the server framework and leverages many plugins from the Hapi ecosystem. All of the following components are neatly wired-up together and provide all the production-level features a web application would require. Thus, one can directly start implementing business logic features.
Features available out-of-the-box
Yarn instead of npm
While the latest version of npm has almost caught up to yarn in terms of most of yarn’s distinguishing features, yarn is still several times faster than npm due to its local cache of packages and parallel installation.
Hapi Server and Plugins
Jumpstarter uses hapi web framework which has a rich set of core APIs, advanced features, and extensible plugin support under the “hapi ecosystem”.
“Build powerful, scalable applications, with minimal overhead and full out-of-the-box functionality — your code, your way”
Authentication
jsonwebtoken is used for JWT based authentication. Login sessions are stored on Redis. Routes for user CRUD operations and password forgot/reset are configured.
Authorization
User roles and scopes are supported and can be configured as needed. Two user roles-user and admin and three user scopes- admin, user, and guest are defined. Entity scoping is supported using entity filters. For example, the table columns to be hidden from the user can be defined in the entity filters list and they will be excluded from the response.
Request Validation
joi is used for validation of path, query, and payload parameters of requests.
Route Policies
mrhorse is used for configuring modular policies for hapi routes.
Swagger Documentation
hapi-swagger is used for automatic generation of swagger documentation.
The payload object model is generated using the joi validation object defined.
ORM
objection is used as the ORM for the PostgreSQL database which enables the use of models, relationships between them, transactions, etc. A base model to be extended by all the models has been defined which contains several useful features.
Database Migration and Seeding
knex is used for database migration and seeding. Separate knex configuration files can be defined per environment as needed. A boolean environment flag DB_RECREATE can be configured which when set to true, database rollback, migration, and seeding are done before starting the server.
Read API
One of the best features of Jumpstarter is its powerful read API, which is inspired by GraphQL. It supports pagination, selection, filtering, and sorting. offset and limit parameters are used for pagination. fields parameter is used for selection, it accepts a comma-separated list of fields to return. Selection also supports fields of the current model’s relations with other models, including nested relations. filters parameter is used for filtering, it accepts an & separated list of conditions using operators such as equal, greater than, in, null, like, etc. Sorting can be done by passing sortField and sortOrder to filters.
Worker and Scheduler
bull is used for queue management for Worker and Scheduler background jobs. Tasks such as sending a welcome email to a new user are shifted to the worker as background jobs. Periodically run jobs are configured as scheduler jobs.
Code Linting and Formatting
eslint is used for javascript linting with the config rules from eslint-config-airbnb for following the best coding practices. prettier is used for code formatting for consistently following the defined coding conventions. VSCode formatOnSave is enabled in workspace settings.
Git Pre-commit Hook
lint command is run on the staged files before committing using husky and lint-staged. This ensures that any erroneous code is reported and fixed, keeping the branch in a working state.
Process Management
Jumpstarter uses pm2 for process management and is ready for production.
Nodemon
nodemon is used for automatically restarting the server after detecting file changes when in dev environment.
Server Config and Environment
The default configuration file picks up the environment variables using dotenv and exports them. Separate configuration files may also be defined for each environment. After merging the default and current environment configuration, an immutable map object Config is exported using immutable.
Tests with Coverage
jest is used as the testing framework along with istanbul for coverage report. API endpoint tests are written for all the endpoints defined in controllers folder. During tests, requests are simulated using the hapi server.inject method.
Coverage is collected from the controllers folder.
CI/CD
As Jumpstarter is hosted on GitHub, CI/CD is configured using GitHub Actions. Test and Deploy jobs are configured in the main workflow. Test job creates an isolated test environment with postgres and redis container services, then it runs database migration and seeding, followed by actual tests. Deploy job is configured to require Test job and it’s just a placeholder that could be replaced to deploy on any provider using any service such as AWS Elastic Beanstalk.
If the Test job fails, the Deploy job is not executed. This ensures that the code which does not pass the tests is never deployed.
Any other CI/CD provider can also be configured instead of GitHub actions simply by deleting the GitHub actions workflow file and configuring the new provider’s workflow file as needed.
WebSockets
@hapi/nes is used as the WebSocket adapter plugin for hapi routes.
Performance Monitoring
newrelic is used for detailed performance monitoring using a New Relic account.
Logging
winston is configured for logging and used in utils, models, controllers, etc.
Emails
nodemailer is used for sending emails. It can be configured to support email services such as SendGrid or Amazon SES.
Lodash
lodash is used as the utility library for writing concise and easy to maintain JavaScript code.
Phone Number Validation
Google’s libphonenumber is used for the validation of international phone numbers.
Scripts
Several npm scripts are available in package.json for ease of access and convenience while managing the web application.
Naming conventions
Though not exactly a feature per se, the following naming conventions are used across the project for consistency:
- Tables, Models: PascalCase
- Columns, Variables: camelCase
- Constants: CONSTANT_CASE
- Routes: kebab-case
- Files: kebab-case[.some-operation].extension
VSCode Extension Recommendations
Several recommended extensions such as eslint, prettier, markdown are defined in .vscode/extensions.json.
Comparison with other similar boilerplate projects
After reviewing the most popular (stars) GitHub Rest API boilerplate projects, we have shortlisted the following projects for comparison with Jumpstarter. Hackathon Starter is still listed here despite being a full-stack boilerplate due to its high popularity.
1. Hackathon Starter
“A boilerplate for Node.js web applications.”
- Full-stack boilerplate
- Frontend — Bootstrap + SASS
- Backend — Node + Express + Passport
- Database — MongoDB + Mongoose
- Multiple third-party API integrations
While it is a great boilerplate for full-stack node applications for this technology stack, it lacks many features such as Swagger Documentation, ORM, Tests, CI/CD, Process Management one would expect from it as a REST API server. As the name suggests, it’s well-suited for hackathons, but probably not for production-level web applications.
2. Express & mongoose REST API Boilerplate in ES6 with Code Coverage
“💥 A boilerplate application for building RESTful APIs Microservice in Node.js using express and mongoose in ES6 with code coverage and JsonWebToken Authentication”
- Backend — Node + Express
- Database — MongoDB + Mongoose
It uses express as the web application framework along with a non-relational database setup with MongoDB and Mongoose. Apart from these differences in the technology stack, it has many features similar to Jumpstarter such as Authentication, Request Validation, ORM, Linting, Logging, Tests, etc. However, it lacks several important features such as Authorization, Database Migration and Seeding, Process Management, CI/CD, etc.
3. Node API boilerplate
“DDD/Clean Architecture inspired boilerplate for Node web APIs”
- Backend — Node + Express
- Database — SQL DB + Sequelize
Of all the boilerplates listed here, this one is the most similar to Jumpstarter with many common features such as ORM, Database Migration and Seeding, Process Management, Nodemon, Tests with Coverage, Linting, Logging, Scripts, etc. Jumpstarter, however, in addition to all these features, has many more features such as Swagger Documentation, Read API, Worker and Scheduler, Git Pre-commit Hook, etc.
4. Express Typescript Boilerplate
“A delightful way to building a RESTful API with NodeJs & TypeScript by @w3tecch”
- Backend — Node + Express + Auth0
- Database — MySQL + TypeORM + GraphQL + TypeGraphQL
Again, this boilerplate also shares many features with Jumpstarter such as Authentication, Request Validation, Swagger Documentation, Worker, ORM, Database Migration, Tests, etc. It also has some additional features such as-
- GraphQL, which is far superior to Jumpstarter’s Read API
- TypeScript which simplifies JavaScript code and makes it easy to read and debug
- Faker which generates database seed data.
On the other hand, Jumpstarter also has many additional features such as Scheduler, Code Linting and Formatting, Git Pre-commit Hook, Process Management, etc. However, most of these additional features of Jumpstarter are quite easy to add to this boilerplate, after which it could be easily considered superior to Jumpstarter.
Upgrades and Maintenance
Jumpstarter was originally developed more than 2 years ago. Since then, it has gone through several upgrades. We put active efforts in adding features to it as we need those features in our projects which use Jumpstarter. We also patch any bugs reported in these projects. We upgrade the packages regularly and fix any broken dependencies. Some of the features such as Transaction Support, Tests with Coverage, CI/CD have been added quite recently.
Drawbacks
- It goes without saying that Jumpstarter is highly opinionated. With so many components wired-up together, it becomes mandatory to follow a certain way of doing things.
- It doesn’t offer an option to conveniently remove unwanted components or choose only selected components, you simply get everything out-of-the-box. You can however manually remove the components you don’t need if you know what you’re doing.
- One could consider it somewhat heavy due to the usage of plugins and middleware. Thus, it may not be suitable for small-scale applications that hardly leverage any of the features offered by Jumpstarter, which then just become bloatware.
- Unlike the selection of
fieldsin the Read API which supports nested fields based on the current model’s relations,filterscannot be applied to these nested fields.
Future Scope
- Fixing current limitations such as nested
filters - Adding Microservices support for PDF Generation, Image Upload/Transformation, etc.
- Adding Rate-Limit support, especially for critical APIs
- Adding Internationalization support
- Using better error schema for response
- Adding Typescript support
Thanks for reading! Have any questions or suggestions? Please let us know in the comments below!
