@noveo/scaffolding

Description

The package is designed to quickly create a Node.js application avoiding writing a lot of boring boilerplate code. Finally it could provide an http server based on express and @noveo/swagger-middleware. The server is considered to be an REST API providing CRUD methods for several entities and supporting authentication for methods. Finally it will be similar to boilerplate application

Although it also lets to create React based frontend application. You need to use generator-ui which is described below.

The package is designed as cli tool based on yeoman-environment You might get to be familiar with yeoman and yeoman-environment documentation. It is not necessary, but you'd better to understand what 'generator' is.

Installation

Often it DOESN'T NEED TO BE INSTALLED. For example you don't need to install it for creating application from scratch. You can just run it with npx. See the chapter Running.

Some generators could be run in an existing application root folder. In such case it could be convenient to have the package installed in the application. You can install it from npm registry

npm i @noveo/scaffolding

Sometimes it could be useful to install it from git repo.

npm i git+ssh://[e-mail]:devteam/back/scaffolding.git#develop

Here you can read more about installing packages from git repo.

Actually you don't need to add it as a project dependency, especially as production dependency. Just run generators and forget them. Even you have decided to include it into dependency list than add it into development dependencies using --save-dev.

We DO NOT RECOMMEND to install it GLOBALLY.

Running

If you just want to create a new Node.js application than you can just run (in case you have installed the package in the current directory)

npx scaffolding

It runs default generator generator-app which combines several generators. It asks you several questions and then creates the application. generator-app documentation paragraph describes questions. It can help you to understand how to build an application as you want.

When you want to run it without installation you can do it in a such way

npx @noveo/scaffolding

or

npx git+ssh://[e-mail]:devteam/back/scaffolding.git#develop

Then you can run any generator described in Generators

npx scaffolding [<generator-name> [<generator-arguments>]]

Set generator name to call it. By default generator-app is called. Then you can set generator arguments

Generators

generator-app

Description

It creates a basic application structure and calls other generators to advance application.

Running

npx scaffolding app

Questions

? app name

It requires application name, stores and uses further.

? app folder

It requires application folder name which could be a name of the folder into the current directory, relative path to the folder from the current directory, absolute path to the folder.

If you specify an existing folder, the generator wil ask for confirmation Create in none empty folder?. If you decline, the generator will stop without creating any files.

It is RECOMMENDED to run generator on non-existent folder.

? init git

If you confirm, the generator will call another generator generator-git at the end of the current generator chain. See below for more information about generator-git.

? add security

If you confirm, the generator will call another generator generator-security. See below for more information about generator-security.

? use database

If you confirm, the generator will call another generator generator-database. See below for more information about generator-database.

? add user management API

If you confirm, the generator will call another generator generator-users. See below for more information about generator-users.

? add react-ui for manipulating models in /ui directory?

If you confirm, the generator will call another generator generator-ui. See below for more information about generator-ui.

Created application

The application is supposed to be a Node.js REST API http server.

Created files are package.json, .gitignore, .npmrc, .eslintrc, app.js Then config and application folders are created. app.js file just runs server defined in application folder.

Config folder is supposed to store application configuration in terms of node-config package. This package is user in application for configuration management. You may see standalone.js file in config folder. It is a definition for application with NODE_ENV=standalone. Ask Andrey Dergaev why there is 'standalone' env instead of usual 'development'.

Application folder contains all the application stuff. There is a definition of http server based on express and
@noveo/swagger-middleware. Then there is a basic definition of REST API in terms of swagger. Then there is an essences folder which is considered to store source codes for API entities. Basically there is only one entity defined called 'ping' with only one method. Then there are some libraries. With all additional generators called finally the application is similar to boilerplate

generator-git

Description

It just runs git init command silently and then commits all files as Initial commit.

Running

npx scaffolding git

generator-security

Description

We have already mention @noveo/swagger-middleware It has a mechanism for authentication management. There are some poor documentation here and here Then you can try to figure it out with an usage example or boilerplate repo

Running

npx scaffolding sequrity

Questions

? select security definition types: (Basic auth, Api key)

It requires to choose which types of authentication you want to add into project. Briefly Basic auth is supposed to use some login and password. It looks more like authorization stuff. Api key is supposed to use some Access Token or Authorization header.

? API_KEY header name

If you chose Api key on previous question, It requires to set a name of a request header which will be used as api key.

Result

Finally it adds security definitions into ./application/api.yml Then it adds securityCollection items initialization into ./application/index.js Then it adds secure middleware into server initialization into ./application/index.js securityCollection items requires callback implementation afterwards. They could be implemented by you or defined by generator-users after.

Notice

Usually you need to add apiKey auth for all methods excluding several like login and logout (they do not require authentication, usually they have their own security definition overriding common) Sometimes you need to add basic auth for several or all methods. And it seems pointless to turn on both auth for all methods, but you have such possibility with the generator.

When you added one or both auth with the generator you have auths being turned on global level in api.yml (it means they are turned on for all methods of api). You may remove it from api.yml and add it into security definition of any method to make it responsible not for all methods but for several.

generator-database

Description

It creates some stuff to initialize database connection and Sequelize instance. It supports PostrgeSQL and SQLite now. Also it provides compatibility to use sequelize-cli.

Running

npx scaffolding database

Questions

? kind of user management API: (PostrgeSQL, SQLite)

It requires to choose what kind of database you want to use.

? host

It requires to configure the database connection host for PostgreSQL. The host is appended into default config.

? port

It requires to configure the database connection port for PostgreSQL. The port is appended into default config.

? database

It requires to configure the database connection name for PostgreSQL. The database name is appended into default config.

? username

It requires to configure the database connection username for PostgreSQL. The database username is appended into default config.

? password

It requires to configure the database connection password for PostgreSQL. The database password is appended into default config.

? SQLite file path

It requires to configure the database file path for SQLite. The database file path is appended into default config.

Result

It adds database configuration into default config.

It creates folder application/libs/postgres or application/libs/sqlite. The folder contains initialization of Sequelize instance based on database config. Also the folder contains sequelize-config-proxy.js file that provides config transformation from project's format to sequelize (and sequelize-cli) compatible format.

Then it creates .sequelizerc. This file is required for sequelize-cli correct config access.

Then it creates ./docker/postgres-docker-compose.yml file for PostgreSQL. So you have convenient way to start database quickly.

Then it adds "migrate" script into package.json file.

Finally it adds database connection initialization into ./application/index.js

generator-users

Notice

Current generator implementation will fail on trying to run it without generator-database being run before. It relies on database stuff.

Description

The generator is designed to create CRUD methods for user entity and login/logout methods based on user models and token model.

Running

npx scaffolding users

Question

? kind of user management API: (list+CRUD, authentication API)

It requires you to choose what kinds of stuff it is necessary to create.

list+CRUD means that definitions and controllers for methods of getting list of users, getting user by id, creating user, updating user, deleting user will be created.

authentication API means that definitions and controllers for methods creating user access token (login) and removing user access token (logout) will be created.

• Current implementation of generator will fail on trying to create authentication API without list+CRUD created (previously or together)
• Current implementation of generator will fail on trying to create authentication API without security stuff generated by generator-security

? DB adapter inited. Use?

You have to confirm because current implementation cannot work without database stuff generated by generator-database

Result

• First it adds security config into default config. It is required for secure token generation and password hashing.
• Then it adds users folder with user model definition, definitions and controllers for user list+CRUD methods and some functions for generating user tokens, password hashing, comparing hashed passwords
• Then it adds migration for creating user table in database. (There are some code prepared to process users storing into memory without database. But it doesn't work yet)
• Then it adds token model definitions, definitions and controllers for login and logout method if 'authentication API' has been chosen.
• Then ./application/index.js securityCollection items get callback implementations based on user and token models.
• Finally it adds migration for creating token table in database.

generator-ui

Description

It creates React application for managing data using REST API.

Running

npx scaffolding ui

Result

It creates ui folder which contains frontend application. Application contains builtin Login form which is considered to be composed with backend application generated by previously described generators. It uses login method, user and token entities. Also it component for representing user entity and providing crud operations on the entity.

generator-db-model

Description

Generator creates model definition and migration both in terms of sequelize. Generation is based on json-schema of model entity. It is supposed to create models for new entities in ./application/essences but generator for creating new entities is not ready yet.

Running

It is required to run this generator into the project root which was generated using generator-database. It check database stuff before run.

Then it REQUIRES model description in json-schema format.

Then you can run it like this

npx scaffolding db-model

Questions

? which source to use: (JSON Schema, SQL)

Choose JSON Schema. SQL does not work for now.

? JSON schema file

Provide path to the file with json-schema of the entity

? model name

Provide name for the model

? table name

Provide table name for the model. This name is used as table name in database.

? which fields are required:

Check properties which are required for the entity. They are set required in validation schemas. The they are set NOT NULL into database.

? which field must stay Primary key:

Choose which property is supposed to be a primary key in database. The property is considered to have flag "primaryKey: true" into model definition (but it seems to be not working)

? rendered model destination folder

Provide the path where the model is set to be placed. The best place is directory of appropriate entity in ./application/essences

Result

• It creates model definition in terms of Sequelize
• It creates sequelize migration for table creation in database. Migration is stored in migrations directory.

generator-essention

Description

It is a generator for creating entity directories into ./application/essences with prepared controllers, validation schemas of CRUD operations.

Running

This generator call generator-db-model. That's why it has the same restrictions:

• It is required to run this generator into the project root which was generated using generator-database. It check database stuff before run.

• Then it REQUIRES model description in json-schema format.

Then you can run it like this

npx scaffolding essention

Questions

? entity name

It is required to put the name of the essence or entity which stuff would be created

? JSON schema file

It is required to put the path to the json-schema description of the entity. The json-schema would be used for creation valiation schemas of crud methods. Then the schema would be used for generator-db-model purposes.

? essences folder

It is required to provide the path where the entity folder would be created. Usually it is ./application/essences. If ./application/essences exists it would be suggested as default.

? create db model

It is required to confirm db-model creation or not. Confirmation will call generator-db-model with some preanswered questions.

• JSON Schema is defined to use as source type
• Provided json-schema file is defined to use as source
• definition subdirectory of entity directory is defined to use as model destination folder
• entity name is defined to use as model name and table name

? methods

You need to choose which methods it is required to add into api definition

Result

• it creates entity folder with package.json file which contains pointing on api definition and controllers
• it creates model json schema definition in definition subdirectory
• it creates api.yml file with api definition in definition subdirectory with references on model json schema definition
• it create file with controllers. Depending on the choice of creation db-model controllers would be a bare stubs throwing errors or very simple implemented methods based model.
• depending on the choice of creation db-model model file would be created into definition subdirectory and/or the other stuff produced by generator-db-mode

generator-ui-model

Description

It is a generator for creating entity form providing CRUD operations.

It is NOT WORKING now. It is on development.

Contributing

There was an old documentation how to add new generators. It looks non-relevant.

TODO

• in generator-database replace the question "? kind of user management API:" (Нужно заменить один вопрос в generator-database, он явно скописастился из другого генератора)
• repair in-memory storage in generator-users (починить возможность хранить данные в памяти)
• repair generator-ui result (сгенерированный ui запускается, но нет возможности пройти дальше формы логин - ошибки при работе с токенами и тд)
• repair generator-db-model (генерация из SQL не работает)
• repair generator-essention (генератор не работает)
• repair generator-ui-model (генератор не работает)