nodemon.json

Overview

The `nodemon.json` file is a configuration file for **Nodemon**, a utility that monitors for any changes in your source files and automatically restarts your Node.js application. This file defines specific options to control which files Nodemon will watch or ignore, the file extensions to monitor, and the command to execute when changes are detected.

In this project, `nodemon.json` is tailored to a TypeScript-based Node.js application that uses a build step before starting the server. It ensures that the development environment efficiently rebuilds and restarts the application whenever relevant source files or build artifacts change, improving the developer experience and productivity.

Configuration Properties

The file contains a JSON object with the following properties:

Detailed Explanation

Properties and Their Usage

{
  "ignore": ["src/routes.ts"],
  "watch": [
    "../../../packages/*/dist/tsconfig.tsbuildinfo",
    "../../common/api/dist/tsconfig.tsbuildinfo",
    "src"
  ],
  "ext": "ts",
  "exec": "yarn build && node dist/optimism/api/src/app.js"
}

• ignore:

  • "src/routes.ts" — This specific TypeScript file is ignored by Nodemon. Changes in this file will not trigger a restart.

  • Use case: Sometimes certain files are either stable or managed separately and do not require the app to restart on every change, reducing unnecessary rebuilds.

• watch:

  • "../../../packages/*/dist/tsconfig.tsbuildinfo" and "../../common/api/dist/tsconfig.tsbuildinfo" — These are paths to TypeScript incremental build info files generated by the TypeScript compiler. Watching these helps Nodemon detect when a build has completed or changed, especially in a multi-package monorepo setup.

  • "src" — The main source directory watched for changes. Any changes in this folder (except ignored files) will trigger a restart.

• ext:

  • "ts" — Nodemon watches files with the .ts extension only. This is appropriate for TypeScript projects to avoid unnecessary restarts from unrelated file changes.

• exec:

  • "yarn build && node dist/optimism/api/src/app.js" — This command runs two steps sequentially:

    1. yarn build: Invokes the build process (usually compiles TypeScript to JavaScript).

    2. node dist/optimism/api/src/app.js: Starts the Node.js application using the compiled JavaScript output.

Usage Example

Assuming you have Nodemon installed globally or as a development dependency, starting Nodemon with this configuration is as simple as:

nodemon

Nodemon automatically reads `nodemon.json` in the current directory and applies the defined configuration. It watches `.ts` files in the `src` folder and the specified build info files, ignoring changes in `src/routes.ts`. When a relevant change is detected, it runs the build command and restarts the app.

Implementation Details and Considerations

• Watching TypeScript Incremental Build Info Files:
  The watch configuration includes .tsbuildinfo files, which are special files created by TypeScript's incremental compilation. Monitoring these files helps Nodemon detect when the build process finishes, ensuring the app restarts only after a successful build.

• Ignoring Specific Files:
  Ignoring src/routes.ts might be due to this file being frequently updated but not needing a full app restart, or because route updates are handled differently (e.g., hot reloading). This optimization reduces unnecessary restarts and improves developer efficiency.

• Build Before Execution:
  Running yarn build before starting the app guarantees that the latest compiled JavaScript is executed. This two-step process is essential in TypeScript projects where the source .ts files must be compiled to .js files before running.

Interaction with Other Parts of the System

• Build System (Yarn and TypeScript Compiler):
  The exec command depends on yarn build which must be defined in package.json scripts. This build process compiles the TypeScript source code into JavaScript in the dist folder.

• Application Entry Point:
  The executed file dist/optimism/api/src/app.js is the compiled server application entry point. Changes triggering Nodemon cause rebuilding and restarting this server.

• Monorepo Structure:
  The watch paths suggest a monorepo setup with packages located at ../../../packages/* and shared code in ../../common/api. Watching tsconfig.tsbuildinfo files across packages ensures synchronization and consistent rebuild detection.

Visual Diagram

The following flowchart illustrates the workflow of Nodemon with this configuration file:

flowchart TD
    A[File Change Detected] --> B{Is file ignored?}
    B -- Yes --> C[No Restart]
    B -- No --> D{Is file extension "ts"?}
    D -- No --> C
    D -- Yes --> E{Is file in watch list or src?}
    E -- No --> C
    E -- Yes --> F[Trigger Restart]
    F --> G[Run "yarn build"]
    G --> H[Build Completes]
    H --> I[Run "node dist/optimism/api/src/app.js"]
    I --> J[App Running with Updated Code]

Summary

• Purpose: Configure Nodemon to efficiently watch and restart a TypeScript Node.js application.

• Key Features:

  • Watches .ts files and build info files in a monorepo setup.

  • Ignores specific files to reduce unnecessary restarts.

  • Executes a build step before starting the server.

• Best Practices:

  • Use ignore to exclude stable or non-critical files.

  • Watch build artifact files for accurate restart timing.

  • Ensure the build step completes successfully before starting the app.

This configuration file plays a crucial role in the development workflow by automating rebuilds and restarts, thus improving productivity and ensuring the running application reflects the latest changes.