Ryan Burnette

Project Directory Structure: Scripts

I have gone back and forth on the right way to organize the predefined processes that I record during the process of developing a project.

npm run

Most of my projects are Node.js, or use it for building front-end assets. NPM provides a mechanism for running scripts. We might use something like this.

In package.json…

  "name": "@ryanburnette/my-project",
  "scripts": {
    "build": "webpack --config webpack.production.js -p"

Now we can…

npm run build

Sometimes you are forced use one of these. For example, if your project is being deployed to a platform that expects to fire an npm run on a hook, like on Heroku.

But that case aside, npm run starts to get disorganized when you need to write a bash scripts, or start combining multiple steps into one. You might end up with this…

In package.json…

  "scripts": {
    "build": "scripts/build"

So you can…

npm run build

When you could just have…


So what was the point?


You could argue that the bin directory is the right place for this type of stuff, and you might be right. I just personally find bin to be nondescript in the context of a web development project, so I don’t use it for this.

If my project needed a specific node binary for example, that’s when I would use bin.


To summarize, I use a scripts directory in lieu of npm run or bin. I break my build steps up into small, manually testable components with individual concerns, so freqeuntly a build scripts will look something like this.

#!/usr/bin/env bash

These might be a mix of bash and node scripts as well.


I also tend to segregate scripts that are specific to a certain portion of the project to their own subdirectory. Front-end assets is a good example. The build step for these can be located in a scripts directory that is a direct descendent. If the assets directory could be completely removed after the build step, this makes sense, for example.



  • Build steps are executable files under a scripts directory.
  • They are separated into little scripts with individual concerns.
  • They are separated into scripts directories that are descendents of other separate groups, like assets.