fastify-cli

Command line tools forFastify. Generate, write, and run an application with one single command!

Install

npm install fastify-cli --global

Usage

fastify-clioffers a single command line interface for your Fastify project:

$ fastify

Which will print a help message:

Fastify command line interface, available commands are:

* start start a server
* eject turns your application into a standalone executable with a server.(js|ts) file being added
* generate generate a new project
* generate-plugin generate a new plugin project
* generate-swagger generate Swagger/OpenAPI schema for a project using @fastify/swagger
* readme generate a README.md for the plugin
* print-routes prints the representation of the internal radix tree used by the router, useful for debugging.
* print-plugins prints the representation of the internal plugin tree used by avvio, useful for debugging.
* version the current fastify-cli version
* help help about commands

Launch 'fastify help [command]' to know more about the commands.

The default command is start, you can hit

fastify start plugin.js

to start plugin.js.

start

You can start any Fastify plugin with:

$ fastify start plugin.js

A plugin can be as simple as:

// plugin.js
module.exports=function(fastify,options,next){
fastify.get('/',function(req,reply){
reply.send({hello:'world'})
})
next()
}

If you are using Node 8+, you can usePromisesorasyncfunctions too:

// async-await-plugin.js
module.exports=asyncfunction(fastify,options){
fastify.get('/',asyncfunction(req,reply){
return{hello:'world'}
})
}

For a list of available flags forfastify startsee the help:fastify help start.

If you want to use custom options for the server creation, just export an options object with your route and run the cli command with the--optionsflag. These options also get passed to your plugin via theoptionsargument.

// plugin.js
module.exports=function(fastify,options,next){
fastify.get('/',function(req,reply){
reply.send({hello:'world'})
})
next()
}

module.exports.options={
https:{
key:'key',
cert:'cert'
}
}

And if you are using EcmaScript Module format:

exportdefaultasyncfunctionplugin(fastify,options){
// Both `/foo` and `/foo/` are registered
fastify.get('/foo/',asyncfunction(req,reply){
return'foo'
})
}

exportconstoptions={
ignoreTrailingSlash:true
}

If you want to use custom options for your plugin, just add them after the--terminator. If used in conjunction with the--optionsargument, the CLI arguments take precedence.

// plugin.js
module.exports=function(fastify,options,next){
if(option.one){
//...
}
//...
next()
}

$ fastify start plugin.js -- --one

Modules in EcmaScript Module format can be used on Node.js >= 14 or >= 12.17.0 but < 13.0.0'

// plugin.js
exportdefaultasyncfunctionplugin(fastify,options){
fastify.get('/',asyncfunction(req,reply){
returnoptions
})
}

This works with a.jsextension if you are using Node.js >= 14 and the nearest parentpackage.jsonhas"type": "module" (more info here). If yourpackage.jsondoes not have"type": "module",use.mjsfor the extension (plugin.mjsin the above example).

Options

You can pass the following options via CLI arguments. You can also use--configor-cflag to pass a configuration file that exports all the properties listed below in camelCase convention. In case of collision (i.e., An argument existing in both the configuration file and as a command-line argument, the command-line argument is given the priority). Every option has a corresponding environment variable:

Description	Short command	Full command	Environment variable
Path to configuration file that can be used to manage the options listed below	-c	--config	FASTIFY_CONFIG or CONFIG
Port to listen on (default to 3000)	-p	--port	FASTIFY_PORT or PORT
Address to listen on	-a	--address	FASTIFY_ADDRESS
Socket to listen on	-s	--socket	FASTIFY_SOCKET
Module to preload	-r	--require	FASTIFY_REQUIRE
ES Module to preload	-i	--import	FASTIFY_IMPORT
Log level (default to fatal)	-l	--log-level	FASTIFY_LOG_LEVEL
Path to logging configuration module to use	-L	--logging-module	FASTIFY_LOGGING_MODULE
Start Fastify app in debug mode with nodejs inspector	-d	--debug	FASTIFY_DEBUG
Set the inspector port (default: 9320)	-I	--debug-port	FASTIFY_DEBUG_PORT
Set the inspector host to listen on (default: loopback address or0.0.0.0inside Docker or Kubernetes)		--debug-host	FASTIFY_DEBUG_HOST
Prints pretty logs	-P	--pretty-logs	FASTIFY_PRETTY_LOGS
Watch process.cwd() directory for changes, recursively; when that happens, the process will auto reload	-w	--watch	FASTIFY_WATCH
Ignore changes to the specified files or directories when watch is enabled. (e.g.--ignore-watch='node_modules.git logs/error.log')		--ignore-watch	FASTIFY_IGNORE_WATCH
Prints events triggered by watch listener (useful to debug unexpected reload when using--watch)	-V	--verbose-watch	FASTIFY_VERBOSE_WATCH
Use custom options	-o	--options	FASTIFY_OPTIONS
Set the prefix	-x	--prefix	FASTIFY_PREFIX
Set the plugin timeout	-T	--plugin-timeout	FASTIFY_PLUGIN_TIMEOUT
Defines the maximum payload, in bytes, that the server is allowed to accept		--body-limit	FASTIFY_BODY_LIMIT
Set the maximum ms delay before forcefully closing pending requests after receiving SIGTERM or SIGINT signals; and uncaughtException or unhandledRejection errors (default: 500)	-g	--close-grace-delay	FASTIFY_CLOSE_GRACE_DELAY

By defaultfastify-clirunsdotenv,so it will load all the env variables stored in.envin your current working directory.

The default value for--plugin-timeoutis 10 seconds. By default--ignore-watchflag is set to ignore `node_modules build dist.git bower_components logs.swp' files.

Containerization

When deploying to a Docker container, and potentially other, containers, it is advisable to set a fastify address of0.0.0.0because these containers do not default to exposing mapped ports to localhost.

For containers built and run specifically by the Docker Daemon or inside a Kubernetes cluster, fastify-cli is able to detect that the server process is running within a container and the0.0.0.0listen address is set automatically.

Other containerization tools (eg. Buildah and Podman) are not detected automatically, so the0.0.0.0listen address must be set explicitly with either the--addressflag or theFASTIFY_ADDRESSenvironment variable.

Fastify version discovery

If Fastify is installed as a project dependency (withnpm install --save fastify), thenfastify-cliwill use that version of Fastify when running the server. Otherwise,fastify-cliwill use the version of Fastify included withinfastify-cli.

Migrating out of fastify-cli start

If you would like to turn your application into a standalone executable, just add the followingserver.js:

'use strict'

// Read the.env file.
require('dotenv').config()

// Require the framework
constFastify=require('fastify')

// Require library to exit fastify process, gracefully (if possible)
constcloseWithGrace=require('close-with-grace')

// Instantiate Fastify with some config
constapp=Fastify({
logger:true
})

// Register your application as a normal plugin.
constappService=require('./app.js')
app.register(appService)

// delay is the number of milliseconds for the graceful close to finish
closeWithGrace({delay:process.env.FASTIFY_CLOSE_GRACE_DELAY||500},asyncfunction({signal,err,manual}){
if(err){
app.log.error(err)
}
awaitapp.close()
})

// Start listening.
app.listen({port:process.env.PORT||3000},(err)=>{
if(err){
app.log.error(err)
process.exit(1)
}
})

generate

fastify-clican also help with generating some project scaffolding to kickstart the development of your next Fastify application. To use it:

1. fastify generate <yourapp>
2. cd yourapp
3. npm install

The sample code offers you the following npm tasks:

• npm start- starts the application
• npm run dev- starts the application with pino-prettypretty logging (not suitable for production)
• npm test- runs the tests
• npm run lint- fixes files accordingly to linter rules, for templates generated with--standardlint

You will find three different folders:

• plugins:the folder where you will place all your custom plugins
• routes:the folder where you will declare all your endpoints
• test:the folder where you will declare all your test

Finally, there will be anapp.jsfile, which is your entry point. It is a standard Fastify plugin and you will not need to add thelistenmethod to run the server, just run it with one of the scripts above.

If the target directory existsfastify generatewill fail unless the target directory is.,as in the current directory.

If the target directory is the current directory (.) and it already contains apackage.jsonfile,fastify generatewill fail. This can be overidden with the--integrateflag:

fastify generate. --integrate

This will add or alter themain,scripts,dependenciesanddevDependenciesfields on thepackage.json.In cases of file name collisions for any files being added, the file will be overwritten with the new file added byfastify generate.If there is an existingapp.jsin this scenario, it will be overwritten. Use the--integrateflag with care.

Options

Description	Full command
To generate ESM based JavaScript template	--esm
Use the TypeScript template	--lang=ts,--lang=typescript
Overwrite it when the target directory is the current directory (.)	--integrate
For JavaScript template, optionally includes Standard linter to fix code style issues	--standardlint

generate-plugin

fastify-clican help you improve your plugin development by generating a scaffolding project:

1. fastify generate-plugin <yourplugin>
2. cd yourplugin
3. npm install

The boilerplate provides some useful npm scripts:

• npm run unit:runs all unit tests
• npm run lint:to check your project's code style
• npm run test:typescript:runs types tests
• npm test:runs all the checks at once

readme

fastify-clican also help with generating a concise and informative readme for your plugin. If nopackage.jsonis provided a new one is generated automatically. To use it:

1. cd yourplugin
2. fastify readme <path-to-your-plugin-file>

Finally, there will be a newREADME.mdfile, which provides internal information about your plugin e.g:

• Install instructions
• Example usage
• Plugin dependencies
• Exposed decorators
• Encapsulation semantics
• Compatible Fastify version

generate-swagger

if your project uses@fastify/swagger,fastify-clican generate and write out the resulting Swagger/OpenAPI schema for you.

fastify generate-swagger app.js

linting

fastify-cliis unopinionated on the choice of linter. We recommend you to add a linter, like so:

"devDependencies": {
+"standard": "^11.0.1",
}

"scripts": {
+"pretest": "standard",
"test": "node --test test/**/*.test.js",
"start": "fastify start -l info app.js",
"dev": "fastify start -l info -P app.js",
+"lint": "standard --fix"
},

Test helpers

When you usefastify-clito run your project you need a way to load your application because you can run the CLI command. To do so, you can use the this module to load your application and give you the control to write your assertions. These utilities are async functions that you may use with theNode Test runner.

There are two utilities provided:

• build:builds your application and returns thefastifyinstance without calling thelistenmethod.
• listen:starts your application and returns thefastifyinstance listening on the configured port.

Both of these utilities have thefunction(args, pluginOptions, serverOptions)parameters:

• args:is a string or a string array within the same arguments passed to thefastify-clicommand.
• pluginOptions:is an object containing the options provided to the started plugin (eg:app.js).
• serverOptions:is an object containing the additional options provided to fastify server, similar to the--optionscommand line argument

// load the utility helper functions
const{build,listen}=require('fastify-cli/helper')

// write a test
const{test}=require('node:test')
constassert=require('node:assert')

test('test my application',asynct=>{
constargv=['app.js']
constapp=awaitbuild(argv,{
extraParam:'foo',
skipOverride:true// If you want your application to be registered with fastify-plugin
})
t.after(()=>app.close())

// test your application here:
constres=awaitapp.inject('/')
assert.deepStrictEqual(res.json(),{hello:'one'})
})

Log output is consumed by Node Test runner. If log messages should be logged to the console the logger needs to be configured to output to stderr instead of stdout.

constlogger={
transport:{
target:'pino-pretty',
options:{
destination:2,
},
},
}
constargv=['app.js']
test('test my application with logging enabled',asynct=>{
constapp=awaitbuild(argv,{},{logger})
t.after(()=>app.close())

// test your application here:
constres=awaitapp.inject('/')
assert.deepStrictEqual(res.json(),{hello:'one'})
})

Contributing

If you feel you can help in any way, be it with examples, extra testing, or new features please open a pull request or open an issue.

How to execute the CLI

Instead of using thefastifykeyword before each command, usenode cli.js
Example: replacefastify startwithnode cli.js start

License

MIT