Project Structure

Basic Conventions

Folder and file structure options with naming conventions when creating software projects

Motivations

• Clear feature ownership
• Module usage predictability (refactoring, maintenance, you know what's shared, what's not, prevents accidental regressions, avoids huge directories of not-actually-reusable modules, etc) CI runs only the tests that matter (future)
• Code splitting (future)

Typical top-level directory layout

.
├── build                   # Compiled files (alternatively `dist`)
├── docs                    # Documentation files (alternatively `doc`)
├── src                     # Source files (alternatively `lib` or `app`)
├── test                    # Automated tests (alternatively `spec` or `tests`)
├── tools                   # Tools and utilities
├── LICENSE
└── README.md

Use short lowercase names at least for the top-level files and folders except LICENSE, README.md

Source files

The actual source files of a software project are usually stored inside the src folder. Alternatively, you can put them into the lib (if you're developing a library), or into the app folder (if your application's source files are not supposed to be compiled).

Samples: jQuery src, Node.js lib and src, D3.js src, AngularJS src, Adobe Brackets src, three.js src, Express lib, Socket.IO lib, Less.js lib, Redis src, Ace lib, Semantic UI src, Zepto.js src, Emscripten src, RethinkDB src, Bitcoin src, MongoDB src, Facebook React src, Rust src, ASP.NET src, SignalR src, libgit2 src

Automated tests

Automated tests are usually placed into the test or, less commonly, into the spec or tests folder.

Q: Why tests are placed into a separate folder, as opposed to having them closer to the code under test?

A: Because you don't want to test the code, you want to test the program.

.
├── ...
├── test                    # Test files (alternatively `spec` or `tests`)
│   ├── benchmarks          # Load and stress tests
│   ├── integration         # End-to-end, integration tests (alternatively `e2e`)
│   └── unit                # Unit tests
└── ...

Samples: jQuery, Node.js, D3.js, AngularJS, Adobe Brackets, three.js, Express, Socket.IO, Less.js, Bower, Mozilla PDF.js, Grunt, Gulp, Semantic UI, Zepto.js, Jade, RethinkDB, Vagrant, Sails.js, GitHub Hubot, Facebook React, Ansible, ASP.NET, browserify, Paper.js, Julia, Karma

Documentation files

Often it is beneficial to include some reference data into the project, such as Rich Text Format (RTF) documentation, which is usually stored into the docs or, less commonly, into the doc folder.

.
├── ...
├── docs                    # Documentation files (alternatively `doc`)
│   ├── TOC.md              # Table of contents
│   ├── faq.md              # Frequently asked questions
│   ├── misc.md             # Miscellaneous information
│   ├── usage.md            # Getting started guide
│   └── ...                 # etc.
└── ...

Samples: HTML5 Boilerplate doc, Backbone docs, three.js docs, GitLab doc, Underscore.js docs, Discourse docs, Grunt docs, Emscripten docs, RethinkDB docs, RequireJS docs, GitHub Hubot docs, Twitter Flight doc, Video.js docs, Bitcoin doc, MongoDB docs, Facebook React docs, libgit2 docs, Stylus docs, Gulp docs, Brunch docs

Scripts

...

Tools and utilities

...

Compiled files

...

3rd party libraries

...

Citations

Kriasoft, Konstantin Tarkus, Joshua Mabina, aaaxx, et al., Folder Structure Conventions, Nov 2016, Folder-Structure-Conventions, GitHub repository, https://github.com/kriasoft/Folder-Structure-Conventions, commit 3ee91d1319818f731dcc15f1318b5bbe80283c15

Ryan Florence, et al. Folder Structure, Feb 6, 2015, GitHub Gist, https://gist.github.com/ryanflorence/daafb1e3cb8ad740b346#file-folder-structure-md, commit 0f27176c59046d534476353679ffcb248bbac4c1

Pending Citations

TechEmpower, Nate Brady, et al., Codebase File Structure, Mar 2019, FrameworkBenchmarks, GitHub repository wiki, https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Codebase-File-Structure, commit c48f1ee

Julian Builes, et al., My iOS Project File Structure, Nov 2017, file-structure, GitHub repository, https://github.com/jlnbuiles/file-structure, commit 67f5380a04132440ee714c8ff35ed979cf03d02e

Paŭlo Ebermann, Alan Haggai Alavi, Peter Coulton, et al., How should I structure the files/directories in my Git repository?, Nov 2010, Stack Overflow, https://stackoverflow.com/questions/4172516/how-should-i-structure-the-files-directories-in-my-git-repository

Keywords

project conventions, folder structure, file structure, folder directories, repository structure, project structure, project architecture