nano-staged

Nano Staged

Tiny tool to run commands for modified, staged, and committed files in a GIT repository.
It helps speed up running of the tests, linters, scripts, and more.

Features

• 📦 Small: 47kB (142x+ lighter than lint-staged).
• 🥇 Single dependency (picocolors).
• ☯️ Support multiple file states like staged, unstaged, last-commit, changed etc

Benchmarks

Benchmarks running time for 10 file:

$ node bench/running-time/index.js
- lint-staged 1.394 ms
+ nano-staged 0.968 ms

The space in node_modules including sub-dependencies:

$ node bench/size/index.js
Data from packagephobia.com
- lint-staged   6688 kB
+ nano-staged     47 kB

The performance results were generated on a MBP Late 2013, 2.3 GHz Intel Core i7 by running npm run bench in the library folder. See bench/running-time/index.js

Usage

Getting Started

1. Install nano-staged:

   npm install --save-dev nano-staged
   

   or

   yarn add nano-staged -D
   

2. Add the nano-staged section and the commands to your package.json:

   For example:

   "nano-staged": {
      "*.{js,ts}": "prettier --write",
      "*.css": ["stylelint", "eslint --fix"]
   },
   

3. Run commands with Nano Staged:

   ./node_modules/.bin/nano-staged
   

   Nano Staged by default to run commands from the config for staged files.

Pre-commit Hook

You can use Nano Staged with a pre-commit tools to run it automatically before every commit.

Simple Git Hooks

1. Install `simple-git-hooks` as a dev dependency: ```terminal npm install simple-git-hooks --save-dev ``` 2. Add the `simple-git-hooks` section to your `package.json` and fill in the `pre-commit`: For example: ```json "simple-git-hooks": { "pre-commit": "./node_modules/.bin/nano-staged" } ``` 3. Run the CLI script to update the git hooks with the commands from the config: ```terminal npx simple-git-hooks ``` 4. To automatically have Git hooks enabled after install, edit `package.json`: ```json "scripts": { "postinstall": "npx simple-git-hooks" } ```

Husky

1. Install `husky` as a dev dependency: ```terminal npm install husky --save-dev ``` 2. Enable Git hooks: ```terminal npx husky install ``` 3. Add a command to a hook: ```terminal npx husky add .husky/pre-commit "./node_modules/.bin/nano-staged" ``` 4. To automatically have Git hooks enabled after install, edit `package.json`: ```json "scripts": { "postinstall": "npx husky install" } ```

Configuration

Nano Staged supports multiple ways to define config.

1. nano-staged section in package.json:

   "nano-staged": {
      "*": "your-cmd",
      "*.ext": ["your-cmd", "your-cmd"]
   }
   

2. or a separate .nano-staged.json, nano-staged.json or .nanostagedrc config file:

   {
     "*": "your-cmd",
     "*.ext": ["your-cmd", "your-cmd"]
   }
   

3. or a more flexible .nano-staged.cjs or nano-staged.cjs config file to CommonJS modules:

   module.exports = {
     '*': 'your-cmd',
     '*.ext': ['your-cmd', 'your-cmd'],
   }
   

4. or a more flexible .nano-staged.mjs or nano-staged.mjs config file to ECMAScript modules:

   export default {
     '*': 'your-cmd',
     '*.ext': ['your-cmd', 'your-cmd'],
   }
   

5. or a more flexible .nano-staged.js or nano-staged.js config file:

   // package.json => "type": "module"
   export default {
     '*': 'your-cmd',
     '*.ext': ['your-cmd', 'your-cmd'],
   }
   
   // package.json => "type": "commonjs"
   module.exports = {
     '*': 'your-cmd',
     '*.ext': ['your-cmd', 'your-cmd'],
   }
   

Format priorities:

If there are multiple configuration files in the same directory, Nano Staged will only use one. The priority order is as follows:

1. .nano-staged.js
2. nano-staged.js
3. .nano-staged.cjs
4. nano-staged.cjs
5. .nano-staged.mjs
6. nano-staged.mjs
7. .nano-staged.json
8. nano-staged.json
9. .nanostagedrc
10. package.json

Config Function API:

JS config files may export export either a single function or an object:

export default (api) => {
  const jsFiles = api.filenames.filter((file) => path.extname(file) === '.js')

  return [`eslint --fix ${jsFiles.join(' ')}`, `prettier --write ${jsFiles.join(' ')}`]
}

export default {
  '*.js': (api) => `eslint --fix ${api.filenames.join(' ')}`,
}

The api object exposes:

api.filenames - working filenames

api.type - run type: staged, unstaged, diff

Command Line Interface

--config [<path>] or -c [<path>]

Path to file that contains your configuration object. The path should be either absolute or relative to the directory that your process is running from.

--unstaged or -u

Run commands from the config only for git unstaged files. Nano Staged by default uses only staged git files.

--diff [<ref1> <ref2>]

Run commands on files changed between the working tree and the index or a tree, on files changed between the index and a tree, files changed between two trees, or on files changed between two indexes (commit hashes).

--allow-empty

Will allow creating an empty commit.

--quiet

Shows only that work is done and errors occured.

Thanks

Special thanks to lint-staged. Some codes was borrowed from it.

Community

The Nano Staged community can be found on GitHub Discussions, where you can ask questions, voice ideas, and share your projects.

This site is open source. Improve this page.