fastify-cli

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

Install

npm install fastify-cli --global

Usage

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

$ fastify

Will print an help:

Fastify command line interface, available commands are:

  * start                 start a server
  * generate              generate a new project
  * generate-plugin       generate a new plugin project
  * 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.
  * version               the current fastify-cli version
  * docs                  starts an interactive terminal session to view the fastify docs for the fastify version installed. navigate with arrow keys
  * 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 use Promises or async functions too:

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

For a list of available flags for fastify 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.

// 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'
  }
}

If you want to use custom options for your plugin, just add them after the -- terminator.

// 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
export default async function plugin (fastify, options) {
  fastify.get('/', async function (req, reply) {
    return options
  })
}

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

Options

You can pass the following options via cli arguments, every options has the corresponding environment variable:

By default fastify-cli runs dotenv, 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.

Fastify version discovery

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

Migrating out of fastify-cli start

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

'use strict'

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

// Require the framework
const Fastify = require('fastify')

// Instantiate Fastify with some config
const app = Fastify({
  logger: true,
  pluginTimeout: 10000
})

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

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

Unhandled rejections

fastify-cli uses make-promises-safe to avoid memory leaks in case of a 'unhandledRejection'.

generate

fastify-cli can 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 four npm tasks:

• npm start - starts the application
• npm run dev - starts the application with pino-colada pretty logging (not suitable for production)
• npm test - runs the tests

You will find three different folders:

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

Finally there will be an app.js file, which is your entry point. It is a standard Fastify plugin and you will not need to add the listen method to run the server, just run it with one of the scripts above.

Normally if the target directory exists 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 a package.json file, generate will normally fail. This can be overidden with the --integrate flag:

fastify generate . --integrate

This will add or alter the main, scripts, dependencies and devDependencies fields on the package.json. In cases of file name collisions for any files being added, the file will be overwritten with the new file added by generate. So if there is an existing app.js in this scenario, it will be overwritten. Use the --integrate flag with care.

Options

generate-plugin

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

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

Your boilerplate will provide you 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-cli can also help with generating a concise and informative readme for your plugin. If no package.json was 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 new README.md file, which provides internal informations about your plugin e.g:

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

linting

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

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

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

docs

fastify-cli allows you to view the documentation for fastify in your terminal. By default, fastify-cli attempts to render the documentation for the fastify version installed in the current working directory node_modules folder, however, if none are found, it should fall back to rendering the documentation for the version that fastify-cli depends on.

The documentation is rendered using an interactive terminal session that you can navigate with your arrow keys by pressing the enter key to select documentation to view.

run fastify docs to get started.

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.

The code follows the Standard code style.

License

MIT

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non infringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

Copyright © 2016-2018 Fastify Team