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…

scripts/build

So what was the point?

bin

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.

scripts

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
scripts/prepare
scripts/install-dependencies
scripts/webpack-production
scripts/clean-up

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

assets

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.

assets/scripts/build

Summary

  • 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.