CLI to start a nodejs web api or application
This CLI will serve as a starting point to create a new web api or application based on Koa (https://koajs.com).
To use it, install the package globally
npm install -g @juntoz/koa-app-starter
And then you can call the command koa-app-starter
from any folder.
To update to a new version, simply run the same command.
Why this CLI? Because I need to create many APIs and I want them to share a single base design, dependencies, and configurations. However, doing it while creating a node package is not the best solution because customizing to the needs of a specific API would be very hard and not future-proof.
By providing a CLI to do so, we can have a shared base which we can adapt and yet update it in the future very easily, as long as the pattern is followed.
This is definitely an opinionated starter based on my own experience and what I'm continuously learning about NodeJs.
-
Create your project using
npm init
as usual. This will create the package.json for your project. -
Type in
koa-app-starter
. This will start showing the needed questions for you to fill in, so the application can be created. The starter will automatically create the needed files to run the application and install the needed dependencies. -
Once the CLI is finished, you just need to run it using
node src/index.js --port 3000
, and you have your new app running!. -
The CLI will create an additional file called
.starterlast
which will contain the timestamp and version from which the application was created. This file is just as a trace. It is not used to run the application and you can certainly commit it or not as you see fit.
The CLI will copy and minify those files that are core to the application, because we want to keep those files intact. If you want to modify the logic within those files, you should upgrade this starter, so this way all applications can benefit from that change.
Those files that are considered to be part of the application layer will not be minified, and you can certainly modify them at will.
Once you have your app running, and you want to upgrade to a new version of the starter, you should:
- This CLI will OVERWRITE any file found, therefore the first step is to either commit all your changes to your local git or stash them.
- The CLI will add new packages to
package.json
and upgrade those that were brought before to their latest version. The rest ofpackage.json
is left intact. - Once the CLI is finished, you should review the changes that were made:
- Any core file should just be accepted as is (they are minified).
- App files that were overwritten should be reviewed and merged. Do not make the mistake to just discard the incoming changes because you may be missing an important update on those files.
Every time you make a change either to the core or to a template, you need to commit and also publish a new version to npm.
Steps:
- Go to command line and open the root folder.
- Run the command
npm version patch
to have the new patch version (e.g. 1.2.10 > 1.2.11). If you want to update the minor or major version, you use the same command asnpm version minor/major
. - Commit and push.
- Run
publish.bat
to upload to npm.
The Plugin
class is the tool we have to extend the CLI which must have the following folder structure:
/koa-app-starter
|---/myplugin
|---|---/mysubfolder
|---|---|---mysubfile.js
|---|---myfile.js
|---|---plugin-cfg.yml
- A subfolder within the CLI
- A
plugin-cfg.yml
file that will instruct the CLI what to do in each step. - [files] Any file that is in the folder (next to plugin-cfg.yml) will be copied maintaining the folder structure. So in the above example, the target application will contain
/myappfolder
|---/mysubfolder
|---|---mysubfile.js
|---myfile.js
|---package.json >> (that was created when the application was initialized)
Every plugin is an instance of the same process. The process has the following steps:
- Copy (and minify)
- Insert settings to application configuration (
default.yml
) - Insert settings to configuration environmnent file (
custom-environment-variables.yml
) - Add npm dependencies to target application
If one of the steps is deleted from the file, it will not execute except for the Copy step which will always be executed.
This file contains the configuration options that will tell the CLI how to execute the plugin. Below the complete settings with their default values.
Globs are processed with fast-glob.
copy:
ignore: [] # array of glob paths to ignore when copying. Default ['!**/node_modules', '!**/package*.json', '!**/readme.txt', '!**/plugin-cfg.yml']
minify:
enabled: boolean # whether the minify is turned on or not. Default true.
extensions: [] # list of extensions to minify. Default [.js].
ignore: [] # array of glob paths to ignore when minifying. Default [].
npm:
install: # yaml array of packages that need to be installed
- mssql
configfile: # objects to add to the default.yml config file
foo:
bar: 1
baz: 2
waldo:
found: 1
qux: xyz
envfile: # objects to add to custom-environment-variables.yml config file
foo:
bar: FOO_BAR
waldo:
found: WALDO_FOUND
NOTE: to understand the difference between configfile
and envfile
, go to node-config.
A Plugin
can be either a template or a partial.
A Template
is the target application basis or boilerplate.
A Partial
is a component that we can add to that application.
A template is an application boilerplate, and as such, it has to be able to run as is.
A template must have a package.json
on its own, and be able to run/debug without needing to be installed by the CLI. This package.json
will contain also the needed dependencies required for the target application to run.
Try to not commit the package-lock.json
for the template. This is very important otherwise it could break the target application (although is in the copy default ignore list, so it will never be copied).
In order to run either the CLI or the template, you can modify your launch.json
to have two configurations like this:
{
"configurations": [
{
"type": "node",
"request": "launch",
"name": "CLI",
"program": "${workspaceFolder}/index.js",
"outputCapture": "std",
"console": "externalTerminal"
},
{
"type": "node",
"request": "launch",
"name": "KOA",
"program": "${workspaceFolder}/template-koa/src/index.js",
"args": ["--port", "3000"],
"outputCapture": "std"
}
]
}
The first configuration is for the CLI. console: externalTerminal
means that it must run on an outside console because it requires user input (and VS Code Debug console does not support input).
The second configuration is to run the template application.
This template was designed to create an API based on Koa. It comes with many functionalities built in.
standard packages
koa-pino-logger
as loggerkoa-bodyparser
to parse input body as jsonkoa-passport
to authenticate using jwtkoa-x-request-id
to mark each request with a unique idnode-config
for layered configuration
juntoz packages
- Health probe route (default is
/tools/probe
) - Version route (default is
/tools/version
)
This template only supports http
intentionally. This is because we want to force https
to an external process (probably an API gateway).