Node.js Project Structure

If you are first getting started in Node.js, you might wonder how you should structure your project. Unlike Visual Studio for .NET, there is no one winning tool for working with Node.js and therefore no perfect project template either.

There are also many different packages out there, that do things in a slightly different way and organisations that have their own way of doing things too. If you browse through GitHub you are going to come across some similarities, but also a lot of differences, which can make it hard to know the best approach.

The power of JavaScript is its flexibility, but it can be confusing at times!

I have listed out how I personally structure my Node.js projects for small to medium sized solutions. Given my preferred architectural approach is to use packages and microservices, it works well for me 90% of the time.

Reserved Folders


The place for your entry point into the application; usually ‘index.js’ or ‘app.js’. I tend to use app for full applications and index for libraries and packages.

The package.json and .gitignore also go at this level, with any root level configurations for supporting dev tools, such as linting and testing. If you are working with a build tool like Travis, you will probably need a file for that at the root level too.


All source code for the component should go within this folder. The index.js or app.js should as much as possible just call into these files and not have any code of its own.

This is also the folder where pre transpiled code should sit before being output to the folder through a tool like Babel or using a module bundler like Webpack.


The root directory for websites and for anything else that is exposed publically. Contains static resource files, such as images and transpiled files such as js.


Reserved for the distribution of files, which does not leverage npm. For example, this may be a transpiled and minimised script to be uploaded to a CDN.


Integration tests. Folder name based on the convention for unit test folders in Jest and extended to have int_ at the start.


Jest mocks for node_modules


Unit tests. Folder name based on the convention for unit test folders in Jest.


For coverage results of unit tests.


For repo documentation, which has usually been manually created. Contains gifs and other files that might be needed for the documentation.


For documentation that is automatically generated by jsdoc or other tools.


Contains all supporting scripts for the component, such as shell scripts for CI and AWS CloudFormation scripts for CD. Folder contains child folders for different types of scripts. For example ‘/scripts/deployments’ for deployment scripts.

Please share with all your friends on social media and hit that clap button below to spread the word. Leave a response of your favourite structure. 👏

If you liked this post, then please follow me and check out some of my other articles.


Matthew Bill is a passionate technical leader and agile enthusiast from the UK. He enjoys disrupting the status quo to bring about transformational change and technical excellence. With a strong technical background (Node.js/.NET), he solves complex problems by using innovative solutions and excels in implementing strong DevOps cultures.

He is an active member of the tech community, writing articles, presenting talks, contributing to open source and co-founding the Norwich Node User Group. If you would like him to speak at one of your conferences or write a piece for your publication, then please get in touch.

Find out more about Matthew and his projects at

Thanks for reading!

Other Node.js posts you might ❤️




Technical Leader | Agile Coach | Polyglot Software Engineer | Solution Architect | DevOps Enthusiast | Speaker & Writer

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Matthew Bill

Matthew Bill

Technical Leader | Agile Coach | Polyglot Software Engineer | Solution Architect | DevOps Enthusiast | Speaker & Writer

More from Medium

Push Strapi to Heroku Using Github Repository

Containerize React.js Application With Node.js

How to Deploy Several React Apps in One Node.js server, Without the Tears 😭

Playing with Nodejs :( First Step to Node ✔💻