docs(site): document lint-staged workflows

[kopach]

Description

I'm using syncpack fix in a monorepo with lint-staged and ran into a limitation when multiple package.json files are staged.

lint-staged passes all matched files as positional arguments to the configured command. With a config like:

"lint-staged": {
  "package.json": [
    "pnpm syncpack fix --source"
  ]
}

and two package.json files staged, lint-staged ends up running something like:

pnpm syncpack fix --source path/1/package.json path/2/package.json

This fails with:

error: unexpected argument 'path/2/package.json' found

because syncpack fix does not accept positional file arguments after the options - it only accepts single --source value.

Suggested Solution

Instead of erroring on package.json as an unexpected argument, syncpack could treat all trailing positional file paths as additional sources

Optional comments

No response

Code of Conduct

• I agree to follow the Code of Conduct

[JamieMason]

Thanks @kopach, I'll have a think how best to handle this.

One thing to note, for the format command you might want to only run that command on files you just touched, but for fix you might potentially be better using this:

"lint-staged": {
  "package.json": [
    "pnpm syncpack fix"
  ]
}

The reason being that version mismatches are something that need to take into account all of the packages in your monorepo, for example if you touch one package.json file, it would probably find no mismatches because it would only be looking at one file.

Let me know if there are some other use cases I'm not thinking about, thanks.

[kopach]

Thanks @JamieMason, yes, that makes sense.
For anyone interested, here is the working solution with lint-staged

/** @type {import('lint-staged').Configuration} */
export default {
  // lint-staged will auto-add all staged files to the command unless we use a function-style config
  'package.json': (stagedFiles) => [
    'syncpack fix',
    // sync lockfile with modified `package.json` files (if any)
    'pnpm install --lockfile-only',
    // explicitly stage lockfile and modified package.json files
    'git add pnpm-lock.yaml package.json **/package.json',
  ],
};

[JamieMason]

Thanks a lot for that snippet @kopach, I'll reopen this issue to track adding a new page to the website to document this.

[JamieMason]

Quick question @kopach:

1. You edit packages/foo/package.json to bump a dependency version
2. You commit it
3. lint-staged calls syncpack fix
4. syncpack fix bumps the same dependency in packages/bar/package.json

Will packages/bar/package.json get staged and committed with that snippet?

[kopach]

You are right, @JamieMason, it won't be committed automatically. Thanks for pointing it out. I have changed the last line to something like this:

    // explicitly stage lockfile and modified package.json files
    'git add pnpm-lock.yaml package.json **/package.json',

This addresses this specific use case. However, I think that with a tool like syncpack, which produces side effects, there is currently no proper solution for lint-staged. For instance, I might want to commit only one package.json (or just a portion of it), but this approach forces me to commit all of them.

On the other hand, I believe this is an acceptable trade-off if we want to keep our dependencies in sync automatically.