Repository files navigation

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

npm install fastify-cli --global

fastify-cli offers a single command line interface for your Fastifyproject:

$ 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 commandsLaunch 'fastify help [command]' to know more about the commands.The default command is start, you can hit  fastify start plugin.jsto start plugin.js.

You can start any Fastify plugin with:

$ fastify start plugin.js

A plugin can be as simple as:

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

If you are using Node 8+, you can usePromises orasync functions too:

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

For a list of available flags forfastify start see 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--options flag.These options also get passed to your plugin via theoptions argument.

// plugin.jsmodule.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 registeredfastify.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--options argument, the CLIarguments take precedence.

// plugin.jsmodule.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.jsexportdefaultasyncfunctionplugin(fastify,options){fastify.get('/',asyncfunction(req,reply){returnoptions})}

This works with a.js extension if you are using Node.js >= 14 and the nearest parentpackage.json has"type": "module"(more info here).If yourpackage.json does not have"type": "module", use.mjs for the extension (plugin.mjs in the above example).

You can pass the following options via CLI arguments. You can also use--config or-c flag 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:

By default,fastify-cli runsdotenv, so it will load all the env variables stored in.env in your current working directory.

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

When deploying to a Docker container, and potentially other, containers, it is advisable to set a fastify address of0.0.0.0 because 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.0 listen address is set automatically.

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

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

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 frameworkconstFastify=require('fastify')// Require library to exit fastify process, gracefully (if possible)constcloseWithGrace=require('close-with-grace')// Instantiate Fastify with some configconstapp=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 finishcloseWithGrace({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)}})

fastify-cli can also help with generating some project scaffolding tokickstart 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 withpino-pretty pretty 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.js file, which is your entry point.It is a standard Fastify plugin and you will not need to add thelisten method to run the server, just run it with one of the scripts above.

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

If the target directory is the current directory (.) and it already contains apackage.json file,fastify generate will fail. This canbe overridden with the--integrate flag:

fastify generate . --integrate

This will add or alter themain,scripts,dependencies, anddevDependencies fields on thepackage.json. In cases of file name collisionsfor any files being added, the file will be overwritten with the new file added byfastify generate. If there is an existingapp.js in this scenario,it will be overwritten. Use the--integrate flag with care.

fastify-cli can 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

fastify-cli can also help with generating a concise and informative readme for your plugin. If nopackage.json is 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.md file, which provides internal information about your plugin e.g:

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

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

fastify generate-swagger app.js

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

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

When you usefastify-cli to run your project you need a way to load your application because you can run the CLI command.To do so, you can use 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 thefastify instance without calling thelisten method.
• listen: starts your application and returns thefastify instance 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-cli command.
• 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--options command line argument

// load the utility helper functionsconst{ build, listen}=require('fastify-cli/helper')// write a testconst{ 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 consolethe 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'})})

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.

Instead of using thefastify keyword before each command, usenode cli.js
Example: replacefastify start withnode cli.js start

MIT