@noveo/scaffolding
v0.1.0
Published
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](https://expressjs.com/) and [@noveo/swagger-middleware](https://gitlab.noveogrou
Downloads
7
Keywords
Readme
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://[email protected]: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://[email protected]: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 (генератор не работает)