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

• 💨 Dependency-free
• 🤏 Small: 48kB (142x+ lighter than lint-staged).
• ☯️ Support multiple file states like staged, unstaged, last-commit, changed etc
• 💪 Multi configuration (useful for monorepos)

Benchmarks

Benchmarks running time for 10 file:

$ node bench/running-time/index.js
- lint-staged 0.439 ms
+ nano-staged 0.257 ms

The space in node_modules including sub-dependencies:

$ node bench/size/index.js
Data from packagephobia.com
- lint-staged   6707 kB
+ nano-staged     48 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.

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.

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.

Change Log

This project adheres to Semantic Versioning.

0.8

• Support .nanostagedrc config files (by Azat S.)

0.7

• Suppor git config dir location if .git is a file

0.6

• Add JS API
• Add multispinner output
• Support CI terminal
• Support run script for diff files

0.5

• Support run script for unstaged files
• Added allowing empty git commit
• Update docs
• Replace yarn to pnpm
• Add logo

0.4.5

• Fix publish npm

0.4.4

• Added support no-color flags

0.4.3

• Added run task output status

0.4.2

• Better output on script error
• Updated dependencies
• Add support are no-colors output

0.4.1

• Postpublish npm

0.4

• Support windows platform

0.3.1

• Fix glob parse
• Added globstar to glob parse
• Updated docs

0.3

• Added config load from file

0.2.1

• Fixed test

0.2

• Added external configs (nano-staged.json, .nano-staged.json)
• Update tests and doc

0.1.5

• Update docs.

0.1.4

• Fixed to run ./node_modules/.bin/nano-staged.

0.1.3

• Removed globstart.

0.1.2

• Update docs.

0.1.1

• Added size benchmarks.

0.1

• Initial release.