@kwaeri/node-kit

A simple, yet powerful, and fully-featured tooling for Node.js.

Usage no npm install needed!

<script type="module">
  import kwaeriNodeKit from 'https://cdn.skypack.dev/@kwaeri/node-kit';
</script>

README

@kwaeri/node-kit

pipeline status coverage report CII Best Practices

node-kit is the entry point to the @kwaeri suite of components, which collectively provide a platform that makes it easy to develop applications with Node.js.

Table of Contents

MMOD DOCUMENTATION WIKI (node-kit SERIES)
Introduction
The History of NK
How to Build a Kwaeri Application

In this Article

Development Status

This section outlines the available features, as well as the current focus of development - in order to provide a clue as to when it will become useful for others to leverage node-kit.

If you have taken an interest in node-kit, and would like to see a focus on something that you feel is more important and/or useful to you in the near future, please submit an issue. We pay close attention to the issues list, and if we see there is a strong desire for certain features to be completed before others - we could certainly work to expedite those features more quickly.

Here is the current feature/support list (to be updated regularly):

Stage Feature DEPS Status
SC GLI001 ES6 Support via Babel WORKING
SC GLI018 Typescript Support WORKING
SC GLI001 Gulp builds application WORKING
SC GLI001 Gulp cleans application WORKING
SC GLI001 Gulp manages versions WORKING
CF GLI001 Server WORKING
CF GLI001 Sessions WORKING
CF GLI001 Router WORKING
CF GLI001 Database WORKING
CF GLI001 Direct Response (API ARCH) WORKING
CF GLI019 Sever-Side Rendering PLANNED
CLI GLI016 Generate API Project Template WORKING
CLI GLI015 Generate React Project Template WORKING
CLI GLI020 Generate XRM Project Template GLI019 PLANNED
CLI GLI014 Generate Template Endpoints WORKING
CLI GLI014 Generate Template Components WORKING
CLI GLI021 Database Provisioning WORKING
CLI GLI022 Generate/Manage Migrations WORKING
CLI GLI024 Generate Passwords TBA
CLI GLI023 Generate Admin User TBA

Legends

  • Stage

    • SC: Source Control. This represents a feature related to source control. (i.e. is Typescript supported in user-defined source code?).
    • CF: Core Functionality. This represents a core function provided to the application by @kwaeri/node-kit. (i.e. Does it work to serve an API?).
    • CLI: CLI Feature. This represents a planned CLI feature for @kwaeri/node-kit. (i.e. Is the Node-kit CLI functional for generating API endpoints?)
  • Status

    • PLANNED: It's planned, but a long way off...there's more important work to do for now.
      • However, you could probably figure it out yourself easily enough - we're already transpiling the es6 javascript using babel from src to app. Browse the Gulpfile.
    • WORKING: It's working 100% and mostly reliable.
    • TBA: To be annonced when it's PLANNED.

Latest Changes:

  • Migration support added with the new migration system component
    • The migration system can be generated automatically by attempting to generate a migration. If you need to regenerate the migration system; delete the migrations table, delete the migrations configuration - along with the data/migrations directory - and then generate a migration.
    • Migrations can be run using nkm migrate.
    • Migrations can be reverted using nkm migrate --step-back <number_of_migrations>
  • Typescript support added to API projects
    • If Typescript is selected in wizard during project creation, then the gulpfile will be generated to use Typescript compile tasks in place of Babel transpile tasks for the npm run build and npm run debug npm scripts.
    • If kwaeri.{default|development|production}.json has typescript as the value for the tech property then the component generator will use typescript variants of controllers and models for generating end-points.

Upcoming Changes:

  • Inclusion of the render system in full, for full MV(a)C support.
  • Enhancement of the service support in node-kit, and of the API template - respectively.
    • The Controller module will support directory based actions with index main entry points
  • Enhancement of the React tooling
    • The tooling will incorporate the context-api
    • A React template type that supports server-side rendering in a hybrid server-side/client-side application.
  • Inclusion of the XRM/XMS template.

The Implementation

node-kit is the entry point to the @kwaeri suite of components, which collectively provide a platform that makes it easy to develop applications with Node.js.

node-kit couples an original MVC framework with a customizable application architecture, and completes the pairing with end-to-end tooling that additionally supports popular technologies (such as React.js) - allowing for a diverse application stack.

The Kit

The node-kit platform allows developers fine-tuned control of their application stack. node-kit's MVC framework makes it possible to choose an architecture supported entirely by @kwaeri, and complimented by a variety of technologies.

  • Use a @kwaeri API application for your back-end application - and leverage existing technologies (such as React) for your front-end application.
  • Choose to leverage server-side rendering by using @kwaeri's (X)Cross-Render Managment (XRM) stack:
    • @Kwaeri's rendering facility offers built-in support for a theme system, modules, and comes complete with a HTML Template Engine. Render a response entirely server-side - or render an initial container server-side that's followed up with React.js, similar technologies, or a custom client-side application.

node-kit is built around AJAX concepts, and supports AJAX design principles entirely.

The CLI

The nkm binary provides a project CLI (command-line interface) for developers to leverage with @kwaeri projects. With the CLI, developers can save time they would otherwise spend on redundant processes and tasks. A subset of functionality the CLI provides includes:

  • Generate a project, either a @kwaeri API or a @kwaeri-style React application. @Kwaeri XRM project templates are planned to be included with a future release.
  • Generate template API endpoints on the fly (controller/model pairs).
  • Generate template React components on the fly (either presentation or container, with or without Redux support).
  • Seed a database from the command line (using a seed, or *.sql file).
  • Generate database migrations.
  • Execute database migrations.
  • Create an administrative user (when utilizing @kwaeri's provided context-based user management).

The CLI leverages a configuration (kwaeri.config.json in React projects, or kwaeri.{default|development|production}.json in API projects) through out the life of a @kwaeri project to assist with generating content on a per-file basis.

More features are planned for the CLI.

How it works

@kwaeri/node-kit is intended to be used as the core tool for developing @kwaeri applications. Initially, it should be installed globally, making the tooling accessible on a global scope to developers. Subsequently, once a project is generated, a copy of @kwaeri/node-kit which is local to the project will be installed when npm install . is run.

A @kwaeri project's structure is important when considering how project structure, files, and other content are generated. This can often be manipulated through the use of a configuration (app.environment.json) which is expected either at the root (React projects) - or within the conf (API projects) - directory of any @kwaeri project.

For a deeper understanding of a @kwaeri application, especially the inner workings of the MVC framework - browse the respective documentation within the MMOD Documentation Project's wiki

A Prelude to Getting Started

@kwaeri/node-kit is not ready for production. We've published this module (and any others already published) for testing and development purposes. You're free and welcome to try out anything that may already be available, but please be aware that there is likely to be many aspects of the platform which are not working and/or completely broken. As we near completion of the new platform, we'll update documentation and provide complete examples and tutorials for getting started.

As an aside, the README.md file is very large; while certain major aspects of this README.md file are going to be maintained - expect that some information could be outdated. We will strive to get documentation migrated out to the MMOD Documentation Project's wiki in the mean time, so that this file may be eventually reduced to only the information that is necessary for helping developers and end users pointed in the right direction(s).

Prerequisites

Before we can begin building a node-kit application, it's required that some prerequisite - or required - software be installed within your development environment:

  • Node.js
  • NPM (It comes with node.js)

Optional, though likely necessary, dependencies include:

  • MySQL or PostgreSQL Server
    • In a future release a NoSQL alternative will be supported

Once you have these prerequisites installed, you're ready to move forward.

Prepare the Environment

There are two options for using node-kit to build a @kwaeri application.

  1. Generate a project using node-kit, and leverage end-to-end tooling through out the development of your application.
  2. Download a project template, install dependencies, and leverage node-kit tooling while developing your application.

Generate a Project Using node-kit

The first option is the intended method of leveraging node-kit. This option allows developers to leverage node-kit tooling from end-to-end.

To begin, you'll want to install node-kit so that you may leverage it on a global scope.

Installation

To install node-kit, run the following command within your terminal/command-prompt:

npm install -g @kwaeri/node-kit

Start a Project

Next, you'll want to start a project using the node-kit CLI. You have several project templates to choose from:

  1. The MVC Template generates a basic nk MVC project, and is intended for use as an API project.
  2. The React Template generates a basic front-end React project, and is intended as an option for a browser-counterpart to the MVC Template (or any other consumable back-end/service).
  3. The XRM Template generates one of several project structures, depending on the developer's needs:
    • A basic server-side application generates a basic nk MVC project that fully encapsulates the framework's view system. This provides powerful server-side rendering, complete with themes, and includes a HTML Template Engine.
    • A (X)Cross-Render Management application can also provide you with complete server-side rendering for loading an initial view - but in awareness of, and expecting, that a third party client-side application (such as React) is being leveraged on the end-users machine. This provides another tier of tooling that makes it easy to provide server-side rendering for the third-party client-side application to make use of. It it useful when not fully encapsulating the framework's view system.
    • A multi-app architecture can also be leveraged, which provides an application architecture that is aware of a back-end and front-end application. This allows developers to build upon a complete application using extensions - and is an excellent choice for building applications which are easily distributed to the intended audience. Several facets of an application are provided for by the framework - such as user management - and developers are able to focus solely on the offerings they want to distribute. An end-user can manage their own node-kit installation on their server, and subscribe to your extension.

The MVC Template

To install the MVC Template using node-kit, run the following command from your terminal/command-prompt:

nkm new project --type api MyAPIProject

You can change MyAPIProject to the name of your choosing. You can also, in fact, drop the name altogether - as you will be presented with a project wizard as soon as you enter the command. Follow the prompts to complete your intended action.

Once the Project Wizard completes, the last step in preparing your environment is to install the remaining application dependencies. Run the following command in your terminal/command-prompt:

npm install .

At this point, you are ready to leverage the remaining tooling in developing your application.

The React Template

To install the React Template using node-kit, run the following command from your terminal/command-prompt:

nkm new project --type react MyReactProject

As with the other project types, you can change MyReactProject to the name of your choosing. You can also, in fact, drop the name altogether - as you will be presented with a project wizard as soon as you enter the command. Follow the prompts to complete your intended action.

Once the Project Wizard completes, the last step in preparing your environment is to install the remaining application dependencies. Run the following command in your terminal/command-prompt:

npm install .

At this point, you are ready to leverage the remaining tooling in developing your application.

The XRM Template

To install the XRM Template using node-kit, run the following command from your terminal/command-prompt:

nkm new project --type xrm MyXRMProject

As with the other project types, you can change MyXRMProject to the name of your choosing. You can also, in fact, drop the name altogether - as you will be presented with a project wizard as soon as you enter the command. Follow the prompts to complete your intended action.

Once the Project Wizard completes, the last step in preparing your environment is to install the remaining application dependencies. Run the following command in your terminal/command-prompt:

npm install .

At this point, you are ready to leverage the remaining tooling in developing your application.

Download a Project Template

If you decide to go with downloading a project template, then all you need to do is install 1 of the 2 project templates which are offered at this time (documentation exposes templates not yet implemented):

Once you have decided on a project type (and we understand you may require both, ultimately) it's as easy as cloning the project.

For instance, for an the API project, clone the respective repository:

git clone https://gitlab.com/mmod/kwaeri-api-app

Change directories:

cd kwaeri-api-app

Finally, install dependencies:

npm install .

From here, you can follow the same documentation as any other option for starting a project - from after generating the project - Take me there.

It is important, however, that you do browse the project wizard section, as there is information applicable to this option of building a @kwaeri application as well (i.e. for tooling to work - post setup - you will need to modify the kwaeri.{default|development|production}.json or kwaeri.config.json file according to your environment/application-type).

The Project Wizard

When generating a project template, you will be confronted by a project wizard after entering your command. Due to this, commands may be simplified to just specifying the project's --type (i.e. you can drop the project name from the command as the wizard will ask you for it any way).

The project wizard generates a kwaeri.default.json or kwaeri.config.json file, depending on application-type (API or React, respectively), which the node-kit tooling will leverage through out the development process for populating template content with real content:

  • Project name, author, copyright holder, and other applicable template content will be replaced when project template content is generated by tooling.
  • Similar information will be used in replacing their respective placeholders in file headers - as well as through out file contents - when tooling is utilized through out the development life-cycle.

What About Downloaded Templates?

If you have downloaded (or cloned, rather) the template you are using, it is advised to open and edit the kwaeri.default.json or kwaeri.config.json file so that the information present is accurate - according to your environment/application.

Skipping the Wizard

The wizard may be skipped, though this functionality is not yet present within the tooling. It will be implemented in a future release, and the flag or switch - and applicable wizard option - to do so will be documented then.

All that is necessary for this to be implemented, is for the logic to check for a kwaeri.default.json or kwaeri.config.json file at the time a generate command is run - and to ensure that appropriate data is present within the file according to the specified project type - to be added. A routine will also be needed for working around the different situations that can occur, and our focus right now is on completing the tooling so that the full development life-cycle is covered.

node-kit Tooling

Once you have your project set up, whichever option you chose, you can begin developing your application. node-kit provides tooling to help ease the process. Several time-consuming and redundant tasks can be easily and effortlessly completed by leveraging the tooling.

For instance:

Generating API End-points

You can easily generate a template API End-point, modeled after the tasks end-point, by running the following command from the project root within your terminal/command-prompt:

nkm add end-point --type standard MyAPIEndpoint

This will generate a file/folder structure for the End-Point:

/MyAPIProject
  /src
    /controllers
      my-api-endpoint.ts
    /models
      my-api-endpoint.ts

You are free to change the endpoint name to your liking. Please note that the tooling strictly follows several rules:

  • End-point names will generally be untouched when used as a name for reference.
  • End-point names will be modified when used as a file name:
    • File names will be separated at every capital letter, by a hyphen.
    • File names will have all special characters, such as forward and/or backwards slashes, replaced by a hyphen.
  • Through out files and their contents, depending on the file type and purpose, several deviations of the name provided will be utilized:
    • For file headers, the project name will be used and untouched.
    • For file headers, the author name will be used and untouched.
    • For file headers, the copyright holder information will be generated using the author name and email, untouched.
    • For file headers, the end-point name will be used and untouched.
    • For controller class names, the end-point name will be untouched.
    • For controller file names, the end-point name is subject to the same rules as that of file names.
    • For model class names, the end-point name will be untouched.
    • For model file names, the end-point name is subject to the same rules as that of file names.

API Controllers

API controllers will have basic CRUD functionality generated. There will be a method for each controller action, and all but the base action (index) will have empty method bodies.

Notice how action methods are named according to the HTTP method utilized. Also notice that each method has a comment above it that exposes the route (and method) required to reach it. This is intended as a means of providing direction, and helping newcomers to the platform. It is also a suggested best practice to add these comments to any new methods you may create.

For the base action (default route for the end-point) method body, a very basic implementation is generated for you, and provides an excellent example - as well as starting point - for any newcomer to the platform:

  • A most basic implementation of model inclusion is utilized. The generated model is loaded, fed a response callback, and the model's default list method is invoked by the controller.
  • Although a model is utilized, the default application as-is post-setup will still function, as database interaction is disabled within the model.
  • A sample code snippet is also present which provides an example for directly responding, and providing a well formatted response, with out utilizing a model (the respective code is comented out).

API Models

API Models will have a basic listAll method generated. There will be a complete example of interacting with a database, however it will be commented out - a default return is used so as not to generate an error when an application is tested immediately after generating new end-points.

This allows for easy testing of the route. The complete example is intended to provide direction for newcomers and may be deleted.

If you do not require a model for whatever reason, you may delete the model - and ensure that you remove any references from the controller as well.

Summary

That is the over-all direction of an API project. You will continuously add end-points until you've designed the API to your liking.

A context-based user management system is in the works, and future documentation will step newcomers through utilizing the facility. For now, any user management is left to the developer.

Generating React Components

You can easily generate React components, modeled after a specific component based on the type.

Presentation Components

For a presentation component that is modeled after the provided ErrorHandler presentation component, run the following command from the project root within your terminal/command-prompt:

nkm add component --type presentation MyPresentationComponent

This will generate a file/folder structure for the presentation component:

/MyReactProject
  /src
    /components
      /MyPresentationComponent
        index.ts
        MyPresentationComponent.tsx
        styles.scss
        styles.scss.d.ts
        test.spec.tsx

You are free to change the presentation component name to your liking. Please note that the tooling strictly follows several rules:

  • Component names will generally be untouched when used as a name for reference.
  • Component names will generally be untouched when used as a file name.
  • Through out files and their contents, depending on the file type and purpose, several deviations of the name provided will be utilized:
    • For file headers, the project name will be used untouched.
    • For file headers, the component name will be used untouched.
    • For file headers, the author name will be used and untouched.
    • For file headers, the copyright holder information will be generated using the author name and email, untouched.
    • For file headers, the license type and name will be used untouched.
Modular CSS

Presentation components are designed in a standard way, according to the implementation used by Massively Modified developers within our own internal projects.

This includes the use of modular (s)css. The initially generated files will have the bare minimum syntax for allowing the component to build properly. Any new SCSS added to the styles.scss file will need to be built - updating the matching declarations file - before it can be utilized within the component file.

Within the component file, examples of usage of modular scss exist, so that newcomers to the platform - and possibly to React - will have an example to provide direction in leveraging modular CSS.

Jest Testing

As it was explained in Modular CSS - components are designed in a standard way, that is - according to the implementation used by Massively Modified developers for internal projects. This includes the testing of components. The initially generated files will have the bare minimum syntax for allowing the component to build and be leveraged with out error.

Presentation components use Jest with shallow-rendering, which leverages snapshots where the output of a component uses references, mocks, and/or object proxies - where content would normally be replaced by the real output of references to yet other components, by a file's content, or by the generated hash of a modular css style's class-name - which are subsequently compared between test runs to see if expected output matches up between tests.

When output changes, and if it is indeed intended - there is a command to run at such a time for indicating this, and updating the stored snapshot; jest --updateSnpshot. Another approach is to delete the __snapshots__ directory of the modified component.

Please refer to the Jest documentation for how to do this, and for best practices.

Exports Roll-up

As components are designed in a standard way, that is - according to the implementation used by Massively Modified developers for internal projects - the same standards are used for an exports roll-up file.

The exports roll-up file makes it easier to reference exports by allowing to import a named export directly from its directory path, instead of having to specify the complete path, leading to - and including - the file name which provides it.

Container Components

For a container component that is modeled after the provided App container component (less Jest and SCSS infrastructure), run the following command from the project root within your terminal/command-prompt:

nkm add component --redux --type container MyContainerComponent

This will generate a file/folder structure for the container component:

/MyReactProject
  /src
    /containers
      /MyContainerComponent
        index.ts
        MyContainerComponent.tsx

You are free to change the container component name to your liking. Please note that the tooling strictly follows several rules:

  • Component names will generally be untouched when used as a name for reference.
  • Component names will generally be untouched when used as a file name.
  • Through out files and their contents, depending on the file type and purpose, several deviations of the name provided will be utilized:
    • For file headers, the project name will be used untouched.
    • For file headers, the component name will be used untouched.
    • For file headers, the author name will be used and untouched.
    • For file headers, the copyright holder information will be generated using the author name and email, untouched.
    • For file headers, the license type and name will be used untouched.
Redux Wrapper

If you pass the --redux flag, ensure you do so before passing the --type flag, as it does not take an argument and must stack prior to an object that does in order to ensure that the subcommand argument which is intended to be interpreted as the component's name is not interpreted as an argument to the --redux flag.

By passing the --redux flag, your container component will be wrapped with connect, and come loaded with a stateFromProps type declaration, as well as a mapStateFromProps definition that is loaded into connect.

Dispatch configuration will be required to be done by the developer, though in the future flags may become available to allow for this generic content to be generated for end users of the tooling.

Exports Roll-up

As components are designed in a standard way, that is - according to the implementation used by Massively Modified developers for internal projects - the same standards are used for an exports roll-up file.

The exports roll-up file makes it easier to reference exports by allowing to import a named export directly from its directory path, instead of having to specify the complete path, leading to - and including - the file name which provides it.

Summary

The overall direction of a React project is to continuously add container and/or presentation components as your application logic and UI/UX calls for them. You might find you'll want/need to add one of the several different files for building out your Redux implementation, but this is not currently a target of the tooling - though it may be at some later time.

Additionally, the React project type is generated with library and helper directories which both possess an export roll-up for easing the use of either type of facility within your React project:

Library

Library additions are useful for adding features to an application that are not intended for, nor appropriate for the definition of to be included within, the methods of a container component. If you have need for a library that a container component might call upon, this is the suggested place for it within your project.

As an example, we've provided a very minimal validation library, which is useful for creating form control input filters and validation. The library handles applying validation requirements based on minimal input from the developer, and subsequently handles the logic and state management for visual queues behind the scenes with minimal implementation and setup within a component.

Helpers

Helper files are useful for creating collections of simple tasks or routines that may be used within the methods of a container component, but which would otherwise result in redundancy - very similar in purpose to that of a library, though less targeted or involved.

Let's say you regularly use a timestamp, and there is a process you use for generating them; a timestamp helper is the perfect solution to wrap that process into a single method invocation (and you'll see that we've provided such a timestamp helper as an example for you!).

Migrations

The node-kit migration system is a very minimal solution for managing the state of an application database, per project, The system requires:

  • A working MySQL or PostgreSQL installation (A custom option will be made available at a later time).
  • A completed database configuration, at least the default, present within the conf directory of an API (and later an XRM) project.
    • The database and databae user that is provided in the configuration should be created and valid for use prior to leveraging the migration system.

When the requirements are met the migration system is ready to use.

Generating Migrations

To generate a new migration all that is required - pending that the above requirements are met - is that the following command be run:

nkm add migration <your-named-migration>

If migrations have yet to be configured, then the migration system will:

  • Create the migrations database nodekit_migrations (this assumes you have provided the database.default.js configuration under the conf directory in an API project.)
  • Create the data directory within the root of your API project.
  • Create the migrations directory within the data directory.
  • Generate a migrations configuration migrations.json.
  • Generate a year directory for the respective year.
  • Generate a month directory for the respective month.
  • Generate the migrations file mmddyyyy_your-named-migration.ts

Any future migrations which are generated will cause the migrator to verify all aspects of the migration system's configuration, and ensure each exists and is complete. Pending this, the migrator will generate a new migration file.

Applying Migrations

To apply any pending migrations all that is required - assuming all requirements are met and at least one migration has been generated - is that the following command be run:

nkm migrate

This will cause the system to read the available migrations as well as any applied migrations found in the migrations table. Each pending migration is applied - post being queued for process management - and flagged as completed in the migration table.

Reverting Migrations

To revert a migration, it is required that it was first applied. Assuming it was, you can step back through the applied migrations any number of times required to revert the migration state to that which is desired.

nkm migrate --step-back <#-of-steps>

The number of steps supplied, is the number of migrations - in reverse applied order - that the migrator will revert.

How Migrations Work

The migration system uses a table that stores a record of any migrations which have been successfully applied. It stores this record, so that regardless of what migrations exist on disk - migrations would never be applied twice unless there was a serious mismanagement of migration files.

Migration Paths

There may be a version associated with a particular migration path. This version is useful for consolidating migrations which cover a large period of time into a subsequent version seed.

Let's say that there is an initial version 1 seed, and 20 subsequent version 1 migrations: Developers following said migration path will continue applying migrations as they become available.

Next, let's say that a version 2 seed becaomes available which consolidates the version 1 seed and all of version 1's subsequent migrations. New developers to said project will run the version 2 seed (with out knowing so, the migration system will detect and decide upon this), and then follow along with any version 2 migrations that may subsequently become available.

Developers on the version 1 migration path will continue on the version 1 path until they've reached its end, and then begin along the version 2 path from its first migration - bypassing the version 2 seed.

In such a fashion, migrations can eventually be archived and stripped from the project as a way of consolidating - or bike shedding.

Database Support for migrations

At this time, the @kwaeri/driver module/component supports MySQL and PostgreSQL - as well as any custom driver that is passed into it which follows its API requirements. Literally, the database support is endless. Presuming that the query structure is similar, the migration system should function seamlessly - though the future may bring some configurable options to the table with regards to the migration system, such that other database options are supported.

The Future of the Automaton

The future will realize several new additions for the Automaton incorporated in the node-kit CLI, including:

  • Generating MVC architecture for XRM Templates.
  • Generating default administrative users.
  • Generating user password hashes from a string password (or resetting passwords).

Until the new additions are included in the node-kit CLI for the Automaton, you are still able to leverage the end-to-end tooling available for the currently included templates.

Debugging

As you develop your application, if you are making use of node-kit as your web server (this applies to the nk MVC and the nk XRM templates), there are provisions in place for helping to debug your application.

The Debug Module

All the core components of the nk MVC Framework are configured to leverage the Debug Module for providing feedback that is helpful in debugging issues with an application.

The Debug module allows developers to log output from their application in an organized fashion.

  • When the DEBUG environment variable is not defined, calls to debug are dead code and can be removed safely.
  • When the DEBUG environment variable is defined, calls to debug become organized output that is colorized and sorted by namespace.

We'll touch on how to enable the DEBUG environment variable in a subsequent section.

Break-Points

A node-kit (MVC) application offers a debug mode which enables developers to leverage break-points when working with the Node.js debugger.

The Debugger Keyword

The Node.js debugger allows for debugging by using the debugger keyword within your source code in order to set 'break-points'. While this can be considered a nuance, it does save the trouble of making unnecessary console.log calls over and over - and can provide invaluable insight to issues experienced during development.

To make use of the functionality, you'll need to run scripts using the inspect keyword:

node inspect myscript.js

Here's an example of its usage within the myscript.js file:

// myscript.js
global.x = 5;
setTimeout(() => {
  debugger;  // This is a break-point!
  console.log('world');
}, 1000);
console.log('hello');

Here is some example output within the terminal used when invoking the script:

$ node inspect myscript.js
< Debugger listening on ws://127.0.0.1:9229/80e7a814-7cd3-49fb-921a-2e02228cd5ba
< For help, see: https://nodejs.org/en/docs/inspector
< Debugger attached.
Break on start in myscript.js:1
> 1 (function (exports, require, module, __filename, __dirname) { global.x = 5;
  2 setTimeout(() => {
  3   debugger;
debug> cont
< hello
...

As you can see above, there are keywords used for manipulating the debugger once it has been triggered, such as cont. More information on debugging in this fashion can be viewed by browsing the Node.js Debugger documentation.

Advanced Debugging Tools

You can avoid having to use the debugger keyword within your source code by leveraging the advanced features of an IDE such as Visual Studio Code.

Debugging Node Applications Using VSCode

To get started quickly with debugging Node.js applications using Visual Studio Code, here's an example configuration you can make use of:

Please note that comments in json files are bad practice, and typically not supported. However, Visual Studio Code allows for this within an IDE configuration file

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Kwaeri API App",
            "program": "${workspaceFolder}/index.js",
            "console": "integratedTerminal",
            "runtimeExecutable": "npm",
            "runtimeArgs":[
                "run", "debug"
            ],
            "port": 9229,
            "outFiles": [
                "${workspaceFolder}/**/*.js"
            ],
            "trace": true,
            "sourceMaps": true
        }
    ]
}

To set this configuration:

  1. Open the Debug Panel in your sidebar within Visual Studio Code (CTRL+SHIFT+D)
  2. Open the drop down at the top of the Debug Panel, and select Add a config (workspace).

A blank launch configuration will be created, within which you can paste the above basic configuration.

Starting the Debugger

Once the configuration is set, you can start you're server application in debug mode using the F5 key.

You can also start a debugging session using the provided NPM script from the root of your project - Visual Studio Code will detect that a debugger-enabled process is running and attach its toolkit to the process:

npm run debug

Finally, you can also invoke a debugging session manually from the root of your project - Again, Visual Studio Code will detect that a debugger-enabled process is running and attach its toolkit to the process:

NODE_ENV=development node --nolazy --inspect-brk=9229 index.js

This allows you to set break-points within the controller and model files that you've created:

  • The IDE will provide the controls you need to manipulate your debugging session (Step, Step-In, Step-Over, Step-Out, etc). The controls appear once a debugging session has started.
  • The IDE will provide panels for inspection of variables and pertinent data. You can hover over any variable to see its current value within a code file too, a resulting pop-up is also able to be navigated, objects/arrays expanded, etc.
  • The IDE provides a panel which lists all the break-points and their types. You can remove them, or modify functional break-points.
Setting Break-Points

Setting break-points is very easy, you just click the left-most side of a line of code you want a break-point set for, and a red circle will indicate that you have set a break-point. Break-points can be set actively or pre-preemptively - meaning you can set them before or after you've started a debugging session.

You can also set special break-points which run a function when the break-point is hit. Read up on all the options you have at your disposal by browsing the following documentation:

Put it Together

To leverage the debugging features that node-kit applications offer, there are a couple of options. The first is to leverage the provided NPM scripts, which will allow you the most verbose debugging possible.

The second option is to manually invoke debug mode. In this fashion you can control the level of verbosity to the exact degree of your choosing.

Using the Built-in Scripts

Make use of the built-in NPM scripts to start and stop debugging sessions from the root of your project:

npm run debug

The above command will start the node-kit server, enabling break-points and all of the debug module namespaces to allow you the most verbose debugging possible.

Note that CTRL+C in the same terminal you ran the debug script in, will stop the debug session - as will pressing the STOP button within Visual Studio Code's debug mode controls.

Manually Start Debug Mode

You are also able to manually start a debugging session:

DEBUG=nodekit,nodekit:* NODE_ENV=development node --nolazy --inspect-brk=9229 index.js

The above command is the equivalent to the provided npm debug script. It enables the most verbose debugging possible.

By passing the DEBUG environment variable we are enabling the debug module to log valuable debug information to the console - and the nodekit and nodekit:* namespaces ensure that we'll get valuable debug information for all of the node-kit components.

The --nolazy and --inspect-brk flags instruct Node.js to allow a debugger to attach to a running process - the 9229 being the port that the debugger should attach to. IDE's like Visual Studio Code will automatically attach to a debug session with some configuration (read the debug section for more information) - allowing developers to leverage break-points and utilize a powerful development workflow.

The NODE_ENV=development argument does not enable debugging in any way, but instead is the flag for using the development configuration for your application (from the config.js file). This is the mode developers would use most often through out development, as it is typically used for running a local version of the application.

Production

When your application is ready for production you have many options, such as:

  • Run your application in a virtual environment.
  • Run your application in a container-based environment.
  • Run your application from a physical server.

There is no limitation to how you can deploy a node-kit application. The requirements for a production environment should be obvious enough, but we can go over the basics for clarification.

Production Environments

A production environment is simply an environment that is intended to be used end-game. This should be a secure environment, where nothing but the required dependencies for your application to run - safely and securely - are installed.

Things to Consider

  • Only install the necessary dependencies (i.e. Node.js, NPM, Forever?, MySQL/PostgreSQL/NoSQL).
  • Do not use root users (Not for OS accounts nor DB accounts), create real user accounts and ensure the account is secure with a strong password (i.e. use numbers, upper and lowercase letters, special characters, and make the password at least 8-12 characters long).
  • Make sure your SSL setup is secure, and ALWAYS make sure your OS and any software running on it are up-to-date, including any fixes for security vulnerabilities.

Reverse Proxies

A good setup for Node.js applications is to use a reverse proxy, such as NGINX.

In this fashion you can set domains to proxy back to specific ip:port combinations, and force the use of SSL - maintaining an extra level of security.

Production Configurations

This should be a no-brainer:

  • Do not share production configurations with the public. It is best that developers do not share configurations at all, even though it is common to standardized and share development configurations.
  • Ensure database settings in the production configuration differ from that of the development configuration, and do not push those changes to a shared repository.
  • Ensure IP and internal port settings for a production configuration differ from that of the development configuration and do not push those changes to a shared repository.
  • Keep release/deployment branches locked-down to product owners only, and keep a separate hidden version of your config.js or pipeline configuration file(s) there if you make use of CI/CD for release operations.

Summary

By following those guidelines - and more - you can ensure a secure and stable production environment from which you can deploy your node-kit application.

Conclusion

node-kit is a platform that makes developing applications with Node.js easy - the end-to-end tooling is powerful, and helps to save time by removing the nuance of performing regular and redundant tasks.

In future releases, even more powerful features will be added to the tooling, providing an arsenal of functionality for developers to leverage through out the development life-cycle of an application. As these new features are realized this documentation will be updated - and new documentation will become available.

Check back often for updates, and browse other areas of this wiki for information on how to contribute - and even to learn about the history of @kwaeri, and node-kit.

How to Contribute Code

Our Open Source projects are always open to contribution. If you'd like to cocntribute, all we ask is that you follow the guidelines for contributions, which can be found at the Massively Modified Wiki

There you'll find topics such as the guidelines for contributions; step-by-step walk-throughs for getting set up, Coding Standards, CSS Naming Conventions, and more.

Other Ways to Contribute

There are other ways to contribute to the project other than with code. Consider testing the software, or in case you've found an Bug - please report it. You can also support the project monetarly through donations via PayPal.

Regardless of how you'd like to contribute, you can also find in-depth information for how to do so at the Massively Modified Wiki

Bug Reports

To submit bug reports, request enhancements, and/or new features - please make use of the issues system baked-in to our source control project space at Gitlab

You may optionally start an issue, track, and manage it via email by sending an email to our project's support desk.

For more in-depth documentation on the process of submitting bug reports, please visit the Massively Modified Wiki on Bug Reports

Vulnerability Reports

Our Vulnerability Reporting process is very similar to Gitlab's. In fact, you could say its a fork.

To submit vulnerability reports, please email our Security Group. We will try to acknowledge receipt of said vulnerability by the next business day, and to also provide regular updates about our progress. If you are curious about the status of your report feel free to email us again. If you wish to encrypt your disclosure email, like with gitlab - please email us to ask for our GPG Key.

Please refrain from requesting compensation for reporting vulnerabilities. We will publicly acknowledge your responsible disclosure, if you request us to do so. We will also try to make the confidential issue public after the vulnerability is announced.

You are not allowed, and will not be able, to search for vulnerabilities on Gitlab.com. As our software is open source, you may download a copy of the source and test against that.

Confidential Issues

When a vulnerability is discovered, we create a [confidential issue] to track it internally. Security patches will be pushed to private branches and eventually merged into a security branch. Security issues that are not vulnerabilites can be seen on our public issue tracker.

For more in-depth information regarding vulnerability reports, confidentiality, and our practices; Please visit the Massively Modified Wiki on Vulnerability

Donations

If you cannot contribute time or energy to neither the code base, documentation, nor community support; please consider making a monetary contribution which is extremely useful for maintaining the Massively Modified network and all the goodies offered free to the public.

Donate via PayPal.com