npm & git：提交时生成构建产物的方式及规范问询

Great question! Let’s break this down step by step based on common practices in npm module development.

1. Manual Builds (The Common, Traditional Approach) #

Many authors—especially for smaller, personal projects—do run builds manually before committing. They’ll execute a command like npm run build locally, verify the dist/ folder has updated files, then stage and commit everything including the built assets.

This is exactly what you’ll find in many of the repos you mentioned: it’s straightforward, requires no extra tooling setup, and works well when the maintainer is the only one (or a small team) contributing. The downside? It’s easy to forget to run the build before a commit, which leaves outdated code in the dist/ folder—leading to users installing stale versions if they pull directly from the repo.

2. Automated Builds: How It’s Done #

If authors want to avoid manual errors, there are a few reliable ways to automate the build step:

a. Git Hooks (Most Popular for Pre-Commit Automation) #

Tools like husky paired with lint-staged let you trigger scripts right before a commit or push. Here’s a typical setup:

• Install dependencies: npm install husky lint-staged --save-dev
• Add this configuration to your package.json:

  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*": ["npm run build", "git add dist/"]
  }
  

Now every time you run git commit, the build script runs automatically, updates the dist/ folder, and stages the new files before the commit completes. No more forgetting the build step!

b. CI/CD Pipelines #

For larger projects or teams, CI tools (like GitHub Actions, GitLab CI) can handle builds after code is pushed. Some setups will run the build, then automatically push the updated dist/ files back to the repo—though this can clutter commit history, so it’s often paired with release workflows instead of every commit. Others use CI to validate that the dist/ folder matches the latest source code (failing the pipeline if it doesn’t).

c. prepublishOnly npm Script #

Adding "prepublishOnly": "npm run build" to your package.json ensures the build runs automatically right before you publish the package to npm. Note: This only triggers on npm publish, not on git commits—so your repo’s dist/ folder still needs manual or hook-based updates if you want it to stay in sync with source code.

3. Is Manual Building a Common Practice? #

Absolutely! For individual maintainers or small projects, manual builds are the norm. The tradeoff between setup time for automation and the minor hassle of running npm run build before committing is often worth it for simplicity. That said, as projects grow or teams get larger, automated builds become more necessary to prevent human error.

4. Enforcing Build Standards #

If you’re working in a team and need to ensure everyone follows the build rule, here are a few ways to enforce it:

• Git Hooks: Use husky + lint-staged as described earlier—this blocks commits if the build hasn’t run, forcing contributors to update the dist/ folder.
• CI Validation: Add a step in your CI pipeline that runs npm run build and checks if the dist/ folder has uncommitted changes (using git diff --quiet dist/). If there are changes, the pipeline fails, preventing PRs from being merged until the issue is fixed.
• Branch Protection: On platforms like GitHub, enable branch protection rules that require CI checks to pass before merging. This ensures no one can merge code with an outdated dist/ folder.

内容的提问来源于stack exchange，提问作者user3690467