|
|
## Table of Contents
|
|
|
....................................................................................................................................................................................00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000## Table of Contents
|
|
|
|
|
|
| |
|
|
|
|:------------------------------------------------------------------------------|
|
... | ... | @@ -19,86 +19,344 @@ |
|
|
|
|
|
## Prerequisites
|
|
|
|
|
|
Before we can begin building a node-kit application, it's required that some prerequisite - or required - software is installed within your development environment:
|
|
|
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](https://nodejs.org)
|
|
|
* NPM (It comes with node.js)
|
|
|
|
|
|
Options, though likely necessary dependencies include:
|
|
|
|
|
|
* Node.js (https://nodejs.org
|
|
|
* NPM (though it now comes with node.js)
|
|
|
* MySQL or PostgreSQL Server
|
|
|
* In a future release a NoSQL alternative will be supported
|
|
|
|
|
|
Once you have these prerequisites installed, it's time to move forward!
|
|
|
Once you have these prerequisites installed, you're ready to move forward.
|
|
|
|
|
|
## Prepare the Environment
|
|
|
|
|
|
There are two options for using node-kit for building an application.
|
|
|
There are two options for using node-kit to build a @kwaeri application.
|
|
|
|
|
|
1. [Generate a project using node-kit](#generate-a-project-using-node-kit), and leverage end-to-end tooling through out the development of your application.
|
|
|
2. [Download a project template](#project-templates), 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:
|
|
|
|
|
|
```bash
|
|
|
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](#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.
|
|
|
|
|
|
1. Download a project template, install dependencies, and move forward using the nk tooling.
|
|
|
2. Install node-kit globally, move forward using the nk tooling.
|
|
|
## The MVC Template
|
|
|
|
|
|
While option 1 is entirely valid, it's more specific to using node-kit in 1-off situations. If you intend to use node-kit regularly, you'll be able to generate projects on-the-fly, as well as leverage all of nk in your development process in order to enable rapid development.
|
|
|
To install the MVC Template using node-kit, run the following command from your terminal/command-prompt:
|
|
|
|
|
|
### Project Templates
|
|
|
```bash
|
|
|
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.
|
|
|
|
|
|
If you decide to go with option 1, then all you need to do is install 1 of the 2 project templates which are offered at this time:
|
|
|
## The React Template
|
|
|
|
|
|
To install the React Template using node-kit, run the following command from your terminal/command-prompt:
|
|
|
|
|
|
```bash
|
|
|
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.
|
|
|
|
|
|
## The XRM Template
|
|
|
|
|
|
To install the XRM Template using node-kit, run the following command from your terminal/command-prompt:
|
|
|
|
|
|
```bash
|
|
|
nkm generate --project --type xrm MyXRMProject
|
|
|
```
|
|
|
|
|
|
* [Kwaeri API Project](https://gitlab.com/mmod/kwaeri-api-app) for a back-end API project.
|
|
|
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.
|
|
|
|
|
|
## 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:
|
|
|
|
|
|
* [Kwaeri API Project](https://gitlab.com/mmod/kwaeri-api-app) for a basic nk MVC project. This project template is an excellent choice for building a @kwaeri API application.
|
|
|
* [Kwaeri React Project](https://gitlab.com/mmod/kwaeri-react-app) for a front-end React project.
|
|
|
|
|
|
Once you have decided on a project type (and we understand you may require both, ultimately) it's as easy as cloning the project:
|
|
|
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:
|
|
|
|
|
|
```bash
|
|
|
git clone https://gitlab.com/mmod/kwaeri-api-app
|
|
|
```
|
|
|
|
|
|
And then installing dependencies:
|
|
|
Change directories:
|
|
|
|
|
|
```bash
|
|
|
cd kwaeri-api-app
|
|
|
```
|
|
|
|
|
|
Finally, install dependencies:
|
|
|
|
|
|
```bash
|
|
|
npm install .
|
|
|
```
|
|
|
|
|
|
From here, you can follow the same documentation as option 2 from after generating a project - HERE.
|
|
|
From here, you can follow the same documentation as any other option for starting a project - from after generating the project - [Take me there](#the-node-kit-tooling).
|
|
|
|
|
|
It is important, however, that you do browse the [project wizard](#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 `kcfg.json` file according to your environment/application).
|
|
|
|
|
|
## 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 `kcfg.json` file, 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 `kcfg.json` file so that the information present is accurate - according to your environment/application.
|
|
|
|
|
|
### node-kit Tooling
|
|
|
### Skipping the Wizard
|
|
|
|
|
|
node-kit is a platform for development which makes it easy to develop applications for Node.js. In order to make full use of node-kit tooling, simply install the platform globally within your development environment:
|
|
|
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 `kcfg.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:
|
|
|
|
|
|
```bash
|
|
|
npm install -g @kwaeri/node-kit
|
|
|
nkm generate --type endpoint MyAPIEndpoint
|
|
|
```
|
|
|
|
|
|
This will generate a file/folder structure for the End-Point:
|
|
|
|
|
|
```bash
|
|
|
/MyAPIProject
|
|
|
/src
|
|
|
/controllers
|
|
|
my-api-endpoint.js
|
|
|
/models
|
|
|
my-api-endpoint.js
|
|
|
```
|
|
|
|
|
|
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 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.
|
|
|
|
|
|
#### 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:
|
|
|
|
|
|
```bash
|
|
|
nkm generate --component --type presentation MyPresentationComponent
|
|
|
```
|
|
|
|
|
|
Now you're set to make full use of node-kit tooling. You can generate project structures easily. Start by changing your working directory within your command-prompt/terminal to a workspace directory for @kwaeri projects:
|
|
|
This will generate a file/folder structure for the presentation component:
|
|
|
|
|
|
```bash
|
|
|
mkdir -p ~/workspaces/@kwaeri
|
|
|
cd ~/workspaces/@kwaeri
|
|
|
/MyReactProject
|
|
|
/src
|
|
|
/components
|
|
|
/MyPresentationComponent
|
|
|
index.ts
|
|
|
MyPresentationComponent.tsx
|
|
|
styles.scss
|
|
|
styles.scss.d.ts
|
|
|
test.spec.tsx
|
|
|
```
|
|
|
|
|
|
Then generate the project type you desire. For an API project run the following command:
|
|
|
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 build into the matching *declaration* 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](#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, 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`. Please refer to the [Jest documentation](https://jestjs.io/docs/en/snapshot-testing) 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 the component 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:
|
|
|
|
|
|
```bash
|
|
|
nkm generate --project --type api MyAPIProject
|
|
|
nkm generate --component --type container MyContainerComponent
|
|
|
```
|
|
|
|
|
|
Or, for a React project, run the following command:
|
|
|
This will generate a file/folder structure for the presentation component:
|
|
|
|
|
|
```bash
|
|
|
nkm generate --project --type react MyReactProject
|
|
|
/MyReactProject
|
|
|
/src
|
|
|
/containers
|
|
|
/MyContainerComponent
|
|
|
index.ts
|
|
|
MyContainerComponent.tsx
|
|
|
```
|
|
|
|
|
|
node-kit makes full use of asynchronous methods, and contains the file contents within generators - so there is no waiting for any downloads, and file-contents are customized according to several bits of information which you will provide during the wizard.
|
|
|
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.
|
|
|
|
|
|
###### 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 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 will see several new additions for the Automaton brought to the CLI, including:
|
|
|
|
|
|
* Generating MVC architecture for XRM Templates.
|
|
|
* Handling database provisioning using seed (`*.sql`) files.
|
|
|
* Generating database migrations.
|
|
|
* 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
|
|
|
|
|
|
## Start a Project
|
|
|
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.
|
|
|
|
|
|
Documentation coming soon!
|
|
|
### Debug Module
|
|
|
|
|
|
## Kwaeri API Project
|
|
|
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.
|
|
|
|
|
|
Documentation coming soon!
|
|
|
### 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.
|
|
|
|
|
|
### Putting it Together
|
|
|
|
|
|
To leverage the debugging features that node-kit applications offer, there are a couple of options
|
|
|
|
|
|
#### Using the Built-in Scripts
|
|
|
|
|
|
Make use of the built-in NPM scripts to start and stop debugging sessions:
|
|
|
|
|
|
```bash
|
|
|
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.
|
|
|
|
|
|
#### Manually Start Debug Mode
|
|
|
|
|
|
You are also able to manually start a debugging session:
|
|
|
|
|
|
```bash
|
|
|
DEBUG=nodekit,nodekit:* NODE_ENV=development node --nolazy --inspect-brk=9229 index.js
|
|
|
```
|
|
|
|
|
|
## Kwaeri React Project
|
|
|
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.
|
|
|
|
|
|
Documentation coming soon!
|
|
|
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 Future
|
|
|
|
|
|
Documentation coming soon! |
|
|
\ No newline at end of file |