e-jigsaw/denon

👀 Monitor any changes in your Deno application and automatically restart.

---

denon is the deno replacement for nodemon providing a feature packed, highly configurable and easy to use experience.

denon does not require any additional changes to your code or method of development. denon is a replacement wrapper for deno. To use denon,replace the word deno on the command line when executing your script.

Features

Denon provides most of the features you would expect of a file watcher and more.

• Automatically restart your deno projects
• Drop-in replacement for deno executable
• Extensive configuration options with script support
• Configurable file watcher with support for filesystem events and directory walking
• Ignoring specific files or directories with glob patterns
• Not limited to deno projects with a powerful script configuration

Install

To install denon simply enter the following into a terminal:

deno.land

deno install -qAf --unstable https://deno.land/x/denon/denon.ts

nest.land

deno install -qAf --unstable https://x.nest.land/denon/denon.ts

⚠️ Make sure you are using deno version ^1.6.0 to install this executable. You can upgrade running deno upgrade.

Usage

denon wraps your application, so you can pass all the arguments you would normally pass to your app:

denon run app.ts

you can pass arguments to deno:

denon run --allow-env app.ts

and even to your application:

denon run --allow-env app.ts --arg-for-my-app

you can run scripts declared in config:

denon [script name]

and you can see which scripts are available in your config:

denon

to see what else you can do with deno CLI use the help flag:

denon --help

Configuration

denon is designed to be simple but also extremely configurable to fit your project needs. It supports both json and yaml for the configuration file. The configuration options in yaml is the same as json making it compatible.

to create a basic configuration in the root directory of your project file you can run:

denon --init

this will create a basic scripts.json file:

{
  "scripts": {
    "start": "app.js"
  }
}

you can also initialize from a custom template (see src/templates.ts file for all the available templates)

denon --init typescript

JSON config (scripts.json template)

Denon configuration can be provided as a JSON file:

{
  // optional but highly recommended
  "$schema": "https://deno.land/x/denon/schema.json",

  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "run my app.ts file"
    }
  }
}

JSON Schema

You can use a JSON schema to have type checking on your configuration. Simply add:

{
  "$schema": "https://deno.land/x/denon/schema.json",
  "scripts": {
    /* */
  }
}

YAML Configuration (scripts.yml template)

Denon configuration can be provided as a YAML file:

scripts:
  start:
    cmd: "deno run app.ts"
    desc: "run my app.ts file"

Typescript config (scripts.config.ts template)

Denon configuration can be provided as a .config.ts file:

import type { DenonConfig } from "https://deno.land/x/denon/mod.ts";

const config: DenonConfig = {
  scripts: {
    start: {
      cmd: "deno run app.ts",
      desc: "run my app.ts file",
    },
  },
};

export default config;

You can use a typescript configuration file to have programmable configuration based on your environment (for example loading a .env file):

import { DenonConfig } from "https://deno.land/x/denon/mod.ts";
import { config as env } from "https://deno.land/x/dotenv/mod.ts";

const config: DenonConfig = {
  scripts: {
    // same as json configuration
    start: {
      cmd: "app.js",
      desc: "Run my webserver",
      env: env(),
    },
  },
};

export default config;

Available options

denon takes inspiration from the awesome velociraptor module in the way it handles scripts.

Scripts

Scripts are declared inside the scripts object and are identified by a name:

{
  "scripts": {
    // they all resolve to `deno run app.ts` when you run `denon start`
    "start": "app.ts",
    // OR
    "start": "run app.ts",
    // OR
    "start": "deno run app.ts"
  }
}

Scripts can also be defined by a complex object:

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      // with an optional description that
      // is shown when you run `denon` to list
      // all the scripts
      "desc": "Run the main server.",

      // available options...
      // they are described in the next paragraph
      "allow": ["env", "write"],
      "unstable": true
      // running `denon start` will resolve in
      // deno run --allow-env --allow-write --unstable app.ts
    }
  }
}

Script Options

Options can be script specific or be declared as global in the root of the config file.

Environment variables

Environment variables can be provided as an object and are passed directly to the child process.

{
  // globally applied to all scripts
  "env": {
    "TOKEN": "SUPER SECRET TOKEN"
  },

  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "env": {
        "PORT": 3000
      }
    }
  }
}

Permissions

Permission can be granted to child processes. You can provide specific permissions for each script, but you can also declare permissions globally, following the same format.

{
  // globally applied to all scripts
  // as object ...
  "allow": {
    "read": "/etc,/tmp", // --allow-read=/etc,/tmp
    "env": true // --allow-env
  },
  // ... or as array
  "allow": [
    "run", // --allow-run
    "net" // --allow-net
  ],

  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      // specific for a single script
      // as object ...
      "allow": {
        "read": "/etc,/tmp", // --allow-read=/etc,/tmp
        "env": true // --allow-env
      },
      // ... or as array
      "allow": [
        "run", // --allow-run
        "net" // --allow-net
      ]
    }
  }
}

File watching

While file watching is a core feature of denon you always have the option of disabling file watching and run a script only once:

{
  // globally applied to all scripts
  // now denon will essentialy be a script runner
  "watch": false,

  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      // you can still enable watch on a script-by-script basis
      "watch": true
    }
  }
}

Import Map

Load import map file. Take a look a at the official docs for additional info.

⚠️ This feature in unstable in the current version of the deno executable.

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "importMap": "importmap.json"
    }
  }
}

TS config

Load tsconfig.json configuration file:

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "tsconfig": "tsconfig.json"
    }
  }
}

Unstable

Enable if the script is using unstable features of deno stdlib:

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "unstable": true
    }
  }
}

Inspect and InspectBrk

Activate inspector on host:port. If inspectBrk is used the executions breaks at the start of the user script:

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "inspect": "127.0.0.1:9229",
      // OR
      "inspectBrk": "127.0.0.1:9229"
    }
  }
}

Lockfile

Check the specified lock file:

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "lock": "lock.json"
    }
  }
}

Cert

Load certificate authority from PEM encoded file:

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "cert": "cert.pem"
    }
  }
}

Log

Set log level: (possible values: debug, info)

{
  "scripts": {
    "start": {
      "cmd": "deno run app.ts",
      "desc": "Run the main server.",

      "log": "debug" // or "info"
    }
  }
}

Watcher

File watcher options:

{
  "scripts": {
    /* */
  },

  "watcher": {
    // The number of milliseconds after the last change.
    "interval": 350,
    // The file extensions that it will scan for.
    "exts": ["js", "jsx", "ts", "tsx", "json"],
    // The globs that it will scan for.
    "match": ["**/*.*"],
    // The globs that it will not scan for.
    "skip": ["*/.git/*"],
    // Use the legacy file monitoring algorithm. (walking)
    "legacy": false
  }
}

Logger

Internal logger options:

{
  "scripts": {
    /* */
  },

  "logger": {
    // Clear screen after every restart.
    "fullscreen": false,
    // Output only errors
    "quiet": false,
    // Output debug messages
    "debug": true
  }
}

Supporters

Huge thanks to all our amazing supporters ❤️

Luca Casonato

Denoland

Other

FAQ / Troubleshooting

• Command not found error

  This probably means that the executable path of your os does not include the .deno/bin directory, where denon will be installed.

  To fix this you must update your $PATH:

  echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc

  as mentioned in the deno manual.

Contribution

Pull request, issues and feedback are very welcome. Code style is formatted with deno fmt and commit messages are done following Conventional Commits spec.

Licence

Copyright 2020-2021, the denosaurs team. All rights reserved. MIT license.