Detect New Files Webpack Plugin

Description

Plugin which hooks into Webpack's lifecycle and detects new added files by running a set of shell commands. The result, an array of paths of the newly added files, will be written in the root of the project in a file called "new-files.js".

You can pass a set of custom options through which you can decide when and where to run the detection logic and callbacks.

Why this plugin?

I was looking for a tool which would give me the possibility to enforce a new set of eslint rules only for new files added to a project. Through this approach, the transition will be done gradually without risking of breaking something in the legacy code or introducing new errors. Although there are a few options out there, most of them have a high complexity and add a lot of unnecessary functionality. A pre-commit/pre-push hook is a convenient workaround, but I wanted something to output any lint violation on the go, not only when doing a commit or a push to the repo.

Installation

Install the package using npm.

  npm install detect-new-files-webpack-plugin

Usage

1. In your webpack.config.js or file of choice where the webpack config resides, import the plugin.

  const DetectNewFilesPlugin = require('detect-new-files-webpack-plugin');

2. Instantiate the plugin inside the plugins section of the webpack config. The following example uses the default configuration so you can either pass it or not, your call.

  plugins: [
    new DetectNewFilesPlugin({
      root: 'your path to the root of the project',
      newFiles: {
        hook: 'watchRun',
        onDetection: null,
      },
      shellCommand: {
        hook: 'done',
        onExecute: null
      }
    }),
    ...
  ]

Depending on how many options you need to change, this will also work:

  plugins: [
    new DetectNewFilesPlugin({
      shellCommand: {
        onExecute: 'npm run eslint:watch' // or whatever command you need to run
      }
    }),
    ...
  ]

or

  plugins: [
    new DetectNewFilesPlugin({
      newFiles: {
        onDetection: (newFiles) => { /* run additional logic if needed */ },
      },
      shellCommand: {
        onExecute: 'your desired shell command'
      }
    }),
    ...
  ]

If you intend to use this package for linting new files, please follow the next steps:

3. Make sure you have eslint installed.

4. In your package.json file, add the eslint:watch command and eslintIgnore rules. More details about eslint CLI here.

  ...
  "scripts": {
    ...
    "eslint:watch": "eslint --color ./src ./setup || true"
  },
  "eslintIgnore": [
    "new-files.js"
  ]

By default the eslint command throws an error exiting with code 1 and disrupting the build process, so we need to bypass this by using || true. You can replace ./src and ./setup with your folders of choice.

5. Convert your .estlintrc file to .eslintrc.js.

6. At the beginning of .eslintrc.js file import new-file.js. Make sure it's wrapped in a try/catch to avoid unwanted errors, since it will be created only when the build starts.

  let newFiles = "";

  try {
      newFiles = require('./new-files');
  } catch (error) {
      console.log('Failed to retrieve new-files.js', error);
  }

7. In your .eslintrc.js configuration, add a new overrides section in which you can add the desired additional rules.

  "overrides": [
        {
            "files": newFiles,
            "rules": {
                "max-lines": ["error", { "max": 180 }],
                "react-hooks/rules-of-hooks": "error",
                "react-hooks/exhaustive-deps": "error"
            }
        }
    ],

8. You're all set! Now when you start the project and add new files, after each build you should see a report in the terminal with possible lint errors.

API Reference

| Parameter | Type | Default | Description | | :--------------| :--------- | :--------- | :-------------------------------------------------------------------------------------------------| | root | string | | Optional. The root of the project. If no value is provided, will be automatically determined. | | newFiles | object | {} | Required. Contains 2 keys: hook and onDetection. | | hook | string | watchRun | Required. The webpack lifecycle step to hook into and run the detection logic. | | onDetection | function | null | Optional. Callback called only when new files are detected. | | shellCommand | object | {} | Required. Contains 2 keys: hook and onExecute. | | hook | string | done | Required. The webpack lifecycle step to hook into and run the shell command. | | onExecute | string | null | Optional. Shell command called on a certain moment. |

Other notes

You may wonder why run the eslint command if we already have a mechanism that detects new files and passes them into the eslint config. As for now, the eslint server does not pick up any dynamic changes to the .eslintrc.js file in order to reload the configuration and apply the overrides to the new files.

Depending on the size of your project and how many files you are linting, it might take a few seconds to see the output in the terminal.

Some of the above configurations may need changes as they were designed to work for older versions of eslint(5.16.0) and webpack(4.46.0).