diff options
author | isaacs <i@izs.me> | 2010-09-03 23:10:00 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2010-09-03 23:10:00 +0400 |
commit | ca2571df855672662e3299ab690ecd46baf39093 (patch) | |
tree | 8f711ad9f2730a75305ee315d029df318f46fd22 /man | |
parent | b1ff39024ac9545be450fd49e7aea29e8e16d7bc (diff) |
Document hook scripts and best practices
Diffstat (limited to 'man')
-rw-r--r-- | man/scripts.1 | 43 |
1 files changed, 42 insertions, 1 deletions
diff --git a/man/scripts.1 b/man/scripts.1 index 1966c9b28..0af597d9a 100644 --- a/man/scripts.1 +++ b/man/scripts.1 @@ -1,7 +1,7 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-SCRIPTS" "1" "August 2010" "" "" +.TH "NPM\-SCRIPTS" "1" "September 2010" "" "" . .SH "NAME" \fBnpm-scripts\fR \-\- How npm handles the "scripts" field @@ -148,3 +148,44 @@ process\. .P Note that these script files don\'t have to be nodejs or even javascript programs\. They just have to be some kind of executable file\. +. +.SH "HOOK SCRIPTS" +If you want to run a specific script at a specific lifecycle event for ALL +packages, then you can use a hook script\. +. +.P +Place an executable file at \fB{root}/\.npm/\.hooks/{eventname}\fR, and it\'ll get +run for all packages when they are going through that point in the package +lifecycle\. +. +.P +Hook scripts are run exactly the same way as package\.json scripts\. That is, +they are in a separate child process, with the env described above\. +. +.SH "BEST PRACTICES" +. +.IP "\(bu" 4 +Don\'t exit with a non\-zero error code unless you \fIreally\fR mean it\. +Except for uninstall/deactivate scripts, this will cause the npm action +to fail, and potentially be rolled back\. If the failure is minor or +only will prevent some optional features, then it\'s better to just +print a warning and exit successfully\. +. +.IP "\(bu" 4 +Try not to use scripts to do what npm can do for you\. Read through \fBnpm help json\fR to see all the things that you can specify and enable +by simply describing your package appropriately\. In general, this will +lead to a more robust and consistent state\. +. +.IP "\(bu" 4 +Inspect the env to determine where to put things\. For instance, if +the \fBnpm_config_binroot\fR environ is set to \fB/home/user/bin\fR, then don\'t +try to install executables into \fB/usr/local/bin\fR\|\. The user probably +set it up that way for a reason\. +. +.IP "\(bu" 4 +Don\'t prefix your script commands with "sudo"\. If root permissions are +required for some reason, then it\'ll fail with that error, and the user +will sudo the npm command in question\. +. +.IP "" 0 + |