|
|
....................................................................................................................................................................................00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000## Table of Contents
|
|
|
## Table of Contents
|
|
|
|
|
|
| |
|
|
|
|:------------------------------------------------------------------------------|
|
... | ... | @@ -59,9 +59,9 @@ Next, you'll want to start a project using the node-kit CLI. You have several pr |
|
|
1. [The MVC Template](#the-mvc-template) generates a basic nk MVC project, and is intended for use as an API project.
|
|
|
2. [The React Template](#the-react-template) generates a basic front-end React project, and is intended as and option for a browser-counterpart to MVC Template project.
|
|
|
3. [The XRM Template](#the-xrm-template) generates one of several project structures, depending on the developers needs:
|
|
|
1. 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.
|
|
|
2. 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.
|
|
|
3. 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.
|
|
|
* 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
|
|
|
|
... | ... | @@ -73,6 +73,14 @@ nkm generate --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](#the-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:
|
|
|
|
|
|
```bash
|
|
|
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:
|
... | ... | @@ -83,6 +91,14 @@ nkm generate --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](#the-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:
|
|
|
|
|
|
```bash
|
|
|
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:
|
... | ... | @@ -93,6 +109,14 @@ nkm generate --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](#the-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:
|
|
|
|
|
|
```bash
|
|
|
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:
|
... | ... | @@ -304,7 +328,7 @@ As components are designed in a standard way, that is - according to the impleme |
|
|
|
|
|
The exports roll-up file makes it easier to reference exports by allowing to import a named export directly from the component directory path, instead of having to specify the complete path, leading to - and including - the file name which provides it.
|
|
|
|
|
|
## The Future of the Automaton
|
|
|
### The Future of the Automaton
|
|
|
|
|
|
The future will see several new additions for the Automaton brought to the CLI, including:
|
|
|
|
... | ... | @@ -314,31 +338,146 @@ The future will see several new additions for the Automaton brought to the CLI, |
|
|
* Generating default administrative users.
|
|
|
* Generating user password hashes from a string password.
|
|
|
|
|
|
### Until Then
|
|
|
|
|
|
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.
|
|
|
|
|
|
Continue reading the remaining documentation for the remaining tooling available to developers through out the development life-cycle.
|
|
|
|
|
|
## Debugging
|
|
|
|
|
|
As you develop your application, if you are making use of node-kit as your web server, there are provisions in place for helping to debug your application.
|
|
|
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.
|
|
|
|
|
|
### Debug Module
|
|
|
### The Debug Module
|
|
|
|
|
|
All of the core components of the nk MVC Framework leverage the Debug Module for providing feedback that is helpful in debugging issues with your 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 module in a subsequent section.
|
|
|
|
|
|
### Break-Points
|
|
|
|
|
|
A node-kit server application offers a debug mode which enables developers to leverage break-points when working with Visual Studio Code or similar debugger tools that work with the Node.js debugger.
|
|
|
A node-kit (MVC) application offers a debug mode which enables developers to leverage break-points when working with the [Node.js debugger](https://nodejs.org/api/debugger.html).
|
|
|
|
|
|
#### The Debugger Keyword
|
|
|
|
|
|
The [Node.js debugger](https://nodejs.org/api/debugger.html) 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.
|
|
|
|
|
|
To make use of the functionality, you'll need to run scripts using the `inspect` keyword:
|
|
|
|
|
|
```bash
|
|
|
node inspect myscript.js
|
|
|
```
|
|
|
|
|
|
Here's an example of its usage within the `myscript.js` file:
|
|
|
|
|
|
```javascript
|
|
|
// myscript.js
|
|
|
global.x = 5;
|
|
|
setTimeout(() => {
|
|
|
debugger;
|
|
|
console.log('world');
|
|
|
}, 1000);
|
|
|
console.log('hello');
|
|
|
```
|
|
|
|
|
|
Here is some example output within the terminal used when invoking the script:
|
|
|
|
|
|
```bash
|
|
|
$ 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`. Again, more information on debugging in this fashion can be viewed by browsing the [Node.js Debugger](https://nodejs.org/api/debugger.html) 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 borrow:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
// 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, simply open the debug panel in your sidebar within Visual Studio Code, and open the drop down at the top, followed by selecting `Add a config (workspace)`.
|
|
|
|
|
|
### Putting it Together
|
|
|
A blank launch configuration will be created, within which you can paste the above configuration.
|
|
|
|
|
|
To leverage the debugging features that node-kit applications offer, there are a couple of options
|
|
|
###### 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 debug session:
|
|
|
|
|
|
```bash
|
|
|
npm run debug
|
|
|
```
|
|
|
|
|
|
Finally, you can also manually 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 debug session:
|
|
|
|
|
|
```debug
|
|
|
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 IDE will provide panels for inspection of variables and pertinent data.
|
|
|
* The IDE provides a panel which lists all the break-points and their types as well.
|
|
|
|
|
|
###### 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-emptively - 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:
|
|
|
|
|
|
* Visual Studio Code's [Debugging Overview](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations)
|
|
|
* Visual Studio Code's [Node.js Debugging documentation](https://code.visualstudio.com/docs/nodejs/nodejs-debugging)
|
|
|
|
|
|
### 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 the 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:
|
|
|
Make use of the built-in NPM scripts to start and stop debugging sessions from the root of your project:
|
|
|
|
|
|
```bash
|
|
|
npm run debug
|
... | ... | @@ -354,9 +493,57 @@ 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 (documentation for which can be found HERE) - allowing developers to leverage break-points and utilize a full development workflow.
|
|
|
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](#debugging) section for more information) - allowing developers to leverage break-points and utilize a powerful development workflow.
|
|
|
|
|
|
The `NODE_ENV=development` does not enable debugging in any way, but instead is the flag for using the development configuration for your application. 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 differ from that of a development configuration, and do not push those changes to a shared repository.
|
|
|
* Ensure IP and internal port settings for production configurations differ from that of development configurations and do not push those changes to a shared repository
|
|
|
* Keep release/deployment branches locked-down to the 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.
|
|
|
|
|
|
More features are planned for the platform, and as they are realized this documentation will be updated - and new documentation will become available.
|
|
|
|
|
|
Documentation coming soon! |
|
|
\ No newline at end of file |
|
|
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. |