Skip to content

samrith-s/nodehawk

Repository files navigation

Nodehawk

🗣 This project is actively looking for contributors like you!

Nodehawk is a watcher for your Node server, without a lot of overheads. It observes your directories and files for changes, and triggers rebuilds to make Node application developments hassle-free. Supports every NodeJS framework.

To check the progress, do check out our weekly digest!

This project is inspired by the fantastic Nodemon and uses Chokidar under the hood. Thanks to Freepik for the icon.

npm Build Coverage Status All Contributors

Table of contents

Why Nodehawk?

During the development of a Node server, there is a need for a very versatile watcher than can keep track of your changes and rebuild your application to reflect the same. Of course, there is Nodemon which is the inspiration of this tool, but there are some shortcomings to it.

One of the major differentiator of Nodehawk, is that it is built specifically to make development of Node servers less cumbersome. It primarily focuses on providing a watcher that addresses issues around watching and restarting.

Installation

There are two ways to use this. Either install it globally or add it as a development dependency.

  • Installing globally:
# with npm
npm i -g nodehawk

# with yarn
yarn global add global nodehawk
  • Adding the package as a dev dependency to your project:
# with npm
npm i -D nodehawk

# with yarn
yarn add -D nodehawk

Usage

For using the watcher, simple add a script to your package.json:

{
    "scripts": {
        "start": "nodehawk"
    }
}

IMPORTANT: Nodehawk will by default pass a process.env.PORT to your process. Use it to run your app on that port. All you need to do is:

- app.listen(<your-existing-port>);
+ app.listen(process.env.PORT);

This will help Nodehawk kill the process running on the port to prevent any EADDRINUSE errors. You can customize the port in the configurations below.

You need to provide an exec command in a .nodehawkrc file. The simplest one for your server can be:

{
    "exec": "node src/server"
}

The watcher will run with the default configurations, and automatically start watching your src directory. If you want to customize it further, you can read the whole list of configurations, which can be specified in a .nodehawkrc file in the root of your project alongside package.json.

Configurations

Nodehawk allows a rich variety of configuration options, to suit your needs. All of these configurations are provided through a .nodehawkrc file.

Basic

Key Type Default Description
paths string|string[] "./src" The path or array of paths or globs to watch for changes.
root string "." The root folder from where all paths are resolved.
exec string "" The command to execute when a restart is triggered.
port number 4000 The port number where your process will run.
logLevel number 3 The verbosity of logs to be displayed. 1:fatal, 2:error, 3:warn, 4:info, 5:debug

Performance

Key Type Default Description
buffer number 1500 Buffer to wait for events after which the exec command should be trigger.
bufferPoll number 100 Poll to check the stability of the buffer.
ignored string|regexp "" A path or glob of files or folders to be ignored.

Display

Key Type Default Description
display.onBeforeStart string "Starting..." Message to display while starting the process.
display.onStart string "Started" Message to display after the process has started.
display.onBeforeRestart string "Restarting..." Message to display while restarting the process.
display.onRestart string "Restarting..". Message to display after the process has restarted.
display.onBeforeStop string "Stopping..." Message to display while stopping the process.
clearScreen boolean true Whether to clear the console on start/restart event or not.

Process

Key Type Default Description
env object {} Key value pairs to be assigned to process.env.

The complete API documentation is available on the website.

Examples

There are quite a few real-world examples of Nodehawk. You can the in the examples directory.

Roadmap

  • Integrate ability to add watcher listeners while using the package as an API.
  • Integrate actions for automatic publishing.

Contributors

Thanks goes to these wonderful people (emoji key):


Samrith Shankar

💻 📖 🚧 👀

This project follows the all-contributors specification. Contributions of any kind welcome!