... | ... | @@ -23,6 +23,7 @@ |
|
|
* [node-kit Tooling](#node-kit-tooling)
|
|
|
* [Generating API End-Points](#generating-api-end-points)
|
|
|
* [Generating React Components](#generating-react-components)
|
|
|
* [Migrations](#migrations)
|
|
|
* [The Future of the Automaton](#the-future-of-the-automaton)
|
|
|
* [Debugging](#debugging)
|
|
|
* [The Debug Module](#the-debug-module)
|
... | ... | @@ -84,7 +85,7 @@ Next, you'll want to start a project using the node-kit CLI. You have several pr |
|
|
To install the MVC Template using node-kit, run the following command from your terminal/command-prompt:
|
|
|
|
|
|
```bash
|
|
|
nkm generate --project --type api MyAPIProject
|
|
|
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](#the-project-wizard) as soon as you enter the command. Follow the prompts to complete your intended action.
|
... | ... | @@ -102,7 +103,7 @@ At this point, you are ready to leverage the remaining tooling in developing you |
|
|
To install the React Template using node-kit, run the following command from your terminal/command-prompt:
|
|
|
|
|
|
```bash
|
|
|
nkm generate --project --type react MyReactProject
|
|
|
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](#the-project-wizard) as soon as you enter the command. Follow the prompts to complete your intended action.
|
... | ... | @@ -120,7 +121,7 @@ At this point, you are ready to leverage the remaining tooling in developing you |
|
|
To install the XRM Template using node-kit, run the following command from your terminal/command-prompt:
|
|
|
|
|
|
```bash
|
|
|
nkm generate --project --type xrm MyXRMProject
|
|
|
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](#the-project-wizard) as soon as you enter the command. Follow the prompts to complete your intended action.
|
... | ... | @@ -194,7 +195,7 @@ For instance: |
|
|
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
|
|
|
nkm generate --type endpoint MyAPIEndpoint
|
|
|
nkm add endpoint --type standard MyAPIEndpoint
|
|
|
```
|
|
|
|
|
|
This will generate a file/folder structure for the End-Point:
|
... | ... | @@ -258,7 +259,7 @@ You can easily generate React components, modeled after a specific component bas |
|
|
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
|
|
|
nkm add component --type presentation MyPresentationComponent
|
|
|
```
|
|
|
|
|
|
This will generate a file/folder structure for the presentation component:
|
... | ... | @@ -315,7 +316,7 @@ The exports roll-up file makes it easier to reference exports by allowing to imp |
|
|
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 --component --type container MyContainerComponent
|
|
|
nkm add component --type container MyContainerComponent
|
|
|
```
|
|
|
|
|
|
This will generate a file/folder structure for the container component:
|
... | ... | @@ -346,14 +347,81 @@ 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 its directory path, instead of having to specify the complete path, leading to - and including - the file name which provides it.
|
|
|
|
|
|
### 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:
|
|
|
|
|
|
```bash
|
|
|
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 `your-named-migration-xxx.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:
|
|
|
|
|
|
```bash
|
|
|
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.
|
|
|
|
|
|
```bash
|
|
|
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 any migrations which have been successfully applied. It stores a record of any migrations that have been applied inside of said table, so th at 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.
|
|
|
* Handling database provisioning using seed (`*.sql`) files.
|
|
|
* Generating database migrations.
|
|
|
* Handling migrations.
|
|
|
* Generating default administrative users.
|
|
|
* Generating user password hashes from a string password (or resetting passwords).
|
|
|
|
... | ... | |