Docs suggestion: use "prepare" instead of "postinstall"

[nathansmith]

TL;DR = Suggestion for the documentation site

This is not a bug "issue," but I wanted to make a suggestion for the docs.

I think this could alleviate some confusion around postinstall and remove the necessity for pinst entirely.

Currently, the Husky v5 documentation reads like this.

To automatically have Git hooks enabled after install, edit package.json

// package.json
{
  "private": true,
  "scripts": {
    "postinstall": "husky install"
  }
}

Instead, that could be changed to this. Swap out posinstall for prepare.

Also, private does not matter because prepare runs the same regardless.

To automatically have Git hooks enabled after install, edit package.json

// package.json
{
  "scripts": {
    "prepare": "husky install"
  }
}

---

Longer explanation

I did a writeup for my coworkers, to explain our automated setup for configuring Husky v5.

Basically, this all runs via NPM with the prepare command and puts everything into place.

If this is helpful for the docs, feel free to repurpose it.

This prepare.js file runs after npm install, when pulling down dependencies.

{
  "scripts": {
    "prepare": "node ./scripts/prepare.js"
  }
}

Unlike postinstall, the prepare command does not run when a NPM package is installed as a dependency in another project.

Meaning, it will not run within a package when someone types this…

npm install your-npm-package

…to install it for their own project.

But it will run when working on your-npm-package and installing other dependencies locally. This replicates the behavior we had before with Husky v4.

Code within the prepare.js file looks like this.

// =======
// Import.
// =======

const { execSync } = require('child_process');
const { existsSync } = require('fs');

// ===========
// File paths.
// ===========

const FILE_COMMIT = './.husky/pre-commit';
const FILE_HUSKY = './.husky/_/husky.sh';

// =========
// Commands.
// =========

const CLI_COMMIT = 'npx husky add .husky/pre-commit "npx lint-staged"';
const CLI_HUSKY = 'npx husky install';

// ==============
// Husky install.
// ==============

if (!existsSync(FILE_HUSKY)) {
  global.console.log(CLI_HUSKY);
  execSync(CLI_HUSKY);
}

// ====================
// Add pre-commit hook.
// ====================

if (!existsSync(FILE_COMMIT)) {
  global.console.log(CLI_COMMIT);
  execSync(CLI_COMMIT);
}

Code within the conditional logic will create .husky/pre-commit if it does not yet exist.

That adds a snippet (instructions for Husky) at the top of the file, and then appends the actual text that we passed in.

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

[blimmer]

If this change is made to the docs, you'll probably also want to update the migration helper: https://github.com/typicode/husky-4-to-5/blob/30792c918d08c0ebb99e1ef8942d13be91b9dd3e/src/pkg.ts#L65

[typicode]

@nathansmith Looks great, thanks a lot for the suggestion and detailed explanation! 👍

[typicode]

I've updated docs, it's a better approach for npm/pnpm/yarn v1 👍
However it seems like Yarn v2 doesn't support prepare https://yarnpkg.com/advanced/lifecycle-scripts

[typicode]

I've added a dedicated section to the docs for Yarn v2.

Also husky init will detect Yarn v2 and use postinstall [+ pinst] instead of prepare.

[andresmatasuarez]

There's an important caveat to the use of prepare (or postinstall for that matter) that's worth mentioning:

If you have installed husky as a devDependency (as is my case and is suggested in the official docs) and are running npm publish as part of a CI or release process or whatever, then it'd simply not work due to husky not found error.

I wouldn't want to resort to simply installing husky in the regular dependencies and I know there's a whole official section explaining ways to disable husky for specific environments, but I wanted to make people coming across this issue in the future aware of this finding

[david10sing]

I have package A (components library) where I use husky with prepare and I have another repository (Package B) where I use package A (from private git repository) as well as husky with prepare.

During yarn install, it looks like yarn tries to install package A because it has a prepare script and also install other deps from package B. It appears both installs happen together and causes issues with overwritting cache.

[patoi]

I think the best solution to install deps for production, if you run npm ci --ignore-scripts --production
In this case, prepare will be ignored, and the husky devDeps doesn't break your build.

RTFM: https://docs.npmjs.com/cli/v7/commands/npm-ci#ignore-scripts

[haoadoreorange]

There's an important caveat to the use of prepare (or postinstall for that matter) that's worth mentioning:

If you have installed husky as a devDependency (as is my case and is suggested in the official docs) and are running npm publish as part of a CI or release process or whatever, then it'd simply not work due to husky not found error.

I wouldn't want to resort to simply installing husky in the regular dependencies and I know there's a whole official section explaining ways to disable husky for specific environments, but I wanted to make people coming across this issue in the future aware of this finding

I second this, the actual best approach even for yarn classic is to have it in postinstall and use pinst. You'll also save yourself some times if ever you move to yarn 2.

Maybe you should make this the recommended setup on the doc.

[nextglabs]

There's an important caveat to the use of prepare (or postinstall for that matter) that's worth mentioning:
If you have installed husky as a devDependency (as is my case and is suggested in the official docs) and are running npm publish as part of a CI or release process or whatever, then it'd simply not work due to husky not found error.
I wouldn't want to resort to simply installing husky in the regular dependencies and I know there's a whole official section explaining ways to disable husky for specific environments, but I wanted to make people coming across this issue in the future aware of this finding

I second this, the actual best approach even for yarn classic is to have it in postinstall and use pinst. You'll also save yourself some times if ever you move to yarn 2.

Maybe you should make this the recommended setup on the doc.

Running yarn publish --ignore-scripts seems to solve this issue.