├── LICENSE.md └── README.md /LICENSE.md: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2016 Terkel 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # NPM Scripts 2 | > Nuggets on why & how to use NPM Scripts as your primary build tool. 3 | 4 | The Node Package Manager and the package.json file in combination makes a great option for build automation. 5 | Using NPM and package.json is simpler and has no extra dependencies such as Gulp and Grunt for example. Often Gulp and Grunt are unnecessary abstractions. NPM scripts are plenty powerful and often easier to live with. 6 | 7 | Use this as a quick reference or cheat sheet. 8 | 9 | # Why NPM Scripts 10 | * JavaScript all the things. 11 | * Cut down on dependencies. 12 | * Use any NPM script (Remember to ```—save-dev```). 13 | * Always up to date. 14 | * Remove dependence on plugin authors. 15 | * Less code to debug. 16 | * No need to lean plugins 17 | * Avoid frustrating debugging 18 | 19 | # Common misconceptions 20 | * NPM scripts require strong command line skills. 21 | * NPM scripts aren’t powerful enough. 22 | * Gulp’s streams are necessary for fast builds. 23 | * NPM scripts don’t run cross platform. 24 | 25 | # Package.json 26 | You define all your scripts in the ```package.json``` file. 27 | If you don’t already have it, read below. 28 | 29 | ### Get Started 30 | ```bash 31 | $ npm init 32 | ``` 33 | 34 | ### Example 35 | The following is an example of a fill package.json file. You define scripts as children in the ```scripts``` object. 36 | ```json 37 | { 38 | "name": "npm-scripts-as-build-tool", 39 | "version": "1.0.0", 40 | "description": "Example package.json file", 41 | "main": "index.js", 42 | "scripts": { 43 | "test": "echo \"Running test script\"", 44 | "start": "echo \"Running start script\"", 45 | "stop": "echo \"Running stop script\"", 46 | "restart": "echo \"Running restart script\"", 47 | 48 | "start:dev": "echo \"My dev script\"" 49 | }, 50 | "author": "Terkel Gjervig", 51 | "license": "MIT", 52 | "keywords": [ 53 | "npm", 54 | "scripting" 55 | ] 56 | } 57 | ``` 58 | 59 | # Invoke commands 60 | NPM provides a couple of shorthands for invoking commands. 61 | To list all commands in package.json run ```npm run``` 62 | ```bash 63 | # Start shorthand 64 | $ npm start 65 | 66 | # Test shorthands 67 | $ npm test 68 | $ npm tst 69 | $ npm t 70 | 71 | # Start and restart 72 | $ npm stop 73 | $ npm restart 74 | 75 | # Everything else 76 | $ npm run myscript 77 | ``` 78 | If you haven't defined ```npm restart```, NPM will run stop and then start. 79 | 80 | # Pre- and Post hooks 81 | You can run pre and post hooks before and after a script. 82 | A hook is just another script, prefixed with *pre* or *post*. 83 | Hooks are just like any other scripts, and you can run them directly with ```npm run premyscript```. 84 | The order in which you define hooks doesn't matter. 85 | ```json 86 | "scripts": { 87 | "premyscript": "echo \"Pre script\"", 88 | "myscript": "echo \"Running script\"", 89 | "postmyscript": "echo \"Running post script\"" 90 | }, 91 | ``` 92 | 93 | You can’t override the behaviours for the internal commands, like ```npm publish```, but you can affect their behaviour with pre- and post- scripts. This means you can do stuff like: 94 | ```json 95 | "scripts": { 96 | "prepublish": "echo \"I run before npm publish\"" 97 | } 98 | ``` 99 | 100 | # Passing Arguments 101 | WIP 102 | 103 | # NPM Config Variables 104 | WIP 105 | 106 | # Chaning 107 | With NPM scripts it’s possible to chain commands, just as you do with Gulp and Grunt. NPM scripts is basically just shell commands you invoke through ```NPM run```, which means you can use all your favourite shell operators. 108 | 109 | ### Ampersand Operator: Parallel commands 110 | You can also use the ```&``` operator to run two commands at the same time on Unix 111 | ```bash 112 | npm run script1.js & npm run script2.js 113 | ``` 114 | 115 | You can also use [Parallelshell](https://github.com/keithamus/parallelshell) to run commands in parallel - cross platform. 116 | 117 | ### The Logical AND Operator *(&&)* 118 | ```A && B –– Run B only if A succeeded``` 119 | 120 | Chaining commands (*Waits for each command to finish successfully before starting the next*) is possible with the ```&&``` operator. This is very similar to ```pre-``` or ```post-``` hooks. 121 | 122 | The AND Operator would execute the second command only, if the execution of first command succeeds. 123 | 124 | ### The Logical OR Operator *(||)* 125 | ```A || B –– Run B only if A failed``` 126 | 127 | Execute a second command only if the first command does not succeed. 128 | 129 | ### The Semicolon Operator *(;)* 130 | ```A ; B –– Run A and then B, regardless of the success or failure of A``` 131 | 132 | The semicolon operator allows you to execute multiple commands in succession, regardless of whether each previous command succeeds. 133 | 134 | ### Pipe Operator *(|)* 135 | This ```|``` operator is very useful where the output of first command acts as an input to the second command. 136 | 137 | ### Output Operator 138 | ```>``` Output to file 139 | ```bash 140 | grep 'John Doe' bigFileWithNames.txt > linesWithJohnDoe.txt 141 | ``` 142 | 143 | # Complex Scripts 144 | Decompose big problems by calling one script from another. 145 | Use ```&&``` to call multiple scripts serially on a single line. 146 | ```json 147 | { 148 | "scripts": { 149 | "clean": "rimraf ./dist && mkdir dist", 150 | "prebuild": "npm run clean", 151 | "build": "cross-env NODE_ENV=production webpack" 152 | } 153 | } 154 | ``` 155 | 156 | If a command gets too complicated, you can always call a separate file 157 | ```json 158 | { 159 | "scripts": { 160 | "build": "node build.js" 161 | } 162 | } 163 | ``` 164 | 165 | # Streams 166 | You don’t need Gulp for streams. Streaming has always been built into both Unix and Windows command lines. The pipe ```|``` operator streams the output of one command to the input of another command. And the redirection ```>``` operator redirects output to a file. 167 | 168 | # Cross-platform 169 | Here’s some of the cross-platform commands: 170 | ```bash 171 | && # chain tasks (Run one task after another) 172 | < # input file contents to a command 173 | > # redirect command output to a file 174 | | # redirect command output to another command 175 | ``` 176 | 177 | You can also use node packages instead of shell commands. 178 | For example use the package ```rimraf``` instead of ```rm -rf``` or use ```cross-env``` to set environment variables in a cross-platform way. 179 | Find modules by searching Google, NPM or take a look at libraries.io. 180 | 181 | Last but not least, you can use [shelljs](https://www.npmjs.com/package/shelljs) for portable Unix shell commands. 182 | 183 | # NPM Config Variables 184 | https://docs.npmjs.com/misc/config#environment-variables 185 | [coming] 186 | 187 | # Version Bumping 188 | npm version - shows current version 189 | ```json 190 | { 191 | "scripts": { 192 | "version:major": "npm version major", 193 | "version:minor": "npm version minor", 194 | "version:patch": "npm version patch" 195 | } 196 | } 197 | ``` 198 | 199 | #### Notes 200 | Use the ```npm -s``` flag to silence npm's output from the subtasks, which makes the log output a little tidier (it is a shortcut for --loglevel=silent: 201 | https://docs.npmjs.com/misc/config#default-configs). 202 | 203 | # Tools 204 | * Auto restart node scripts with [Nodemon](https://github.com/remy/nodemon) 205 | * Watch files for changes with [onchange](https://github.com/Qard/onchange) 206 | * Run Unix commands on Windows with [cross-env](https://www.npmjs.com/package/cross-env) 207 | * Great list of useful Unix commands: 208 | http://www.tutorialspoint.com/unix/unix-useful-commands.htm 209 | 210 | # Resources 211 | * https://nodesource.com/blog/eleven-npm-tricks-that-will-knock-your-wombat-socks-off 212 | * http://substack.net/task_automation_with_npm_run 213 | * https://medium.com/@dabit3/introduction-to-using-npm-as-a-build-tool-b41076f488b0 214 | * https://css-tricks.com/why-npm-scripts 215 | * https://medium.freecodecamp.com/why-i-left-gulp-and-grunt-for-npm-scripts-3d6853dd22b8 216 | * https://www.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/ 217 | * https://nodesource.com/blog/eleven-npm-tricks-that-will-knock-your-wombat-socks-off/ 218 | * https://github.com/sindresorhus/awesome-npm 219 | 220 | # Help 221 | This is work in progress, 222 | feel free to contribute. 223 | --------------------------------------------------------------------------------