JavaScript Project Structure

JavaScript developers don’t have the benefit of frameworks with common structures like Ruby on Rails or Django. This can lead to inconsistent projects which reduces the ability of a team to onboard new members or find critical code. So if you’re looking for ideas and best practices for JavaScript projects look no further, the Big Nerd Ranch code wranglers are here to help!

Main Schools of Thought

Before we begin it helps to understand the main schools of thought seen in most major web frameworks.

Linear

Keep folder nesting to the minimum, and name folders in a general manner. Most notably seen in the Ruby on Rails web framework.

Pros:

1. Easy to understand.
2. Easy to onboard new team members.

Cons:

1. As the project scales it can be hard to find the file you need in a folder with 20 or 30+ files.
2. Naming conventions become paramount to avoid conflicts and navigate the project.

Checkout this example Rails application to see it in action.

Fractal

Group similar components or resources together in nested folders. Most notably seen in the Django web application framework.

Pros:

1. Once you understand how resources are related it becomes easy to find exactly what you need quickly.
2. Naming conventions are much more lax.

Cons:

1. Can easily become a series of Russian nesting dolls that make it difficult to navigate and understand from a holistic view.
2. More challenging to maintain.
3. Longer period to onboard new team members due to the unique nature of each project.

Here’s an example Django application if you want to learn more.

Adaptive Fractal

As linear styled projects grow in size and complexity group similar resources together in well-named folders that contain at least 3+ files.

Pros:

1. Brings the best of both linear and fractal structures.
2. Maintainable by default.
3. Mostly straightforward on-boarding for new team members.

Cons:

1. It takes a bit of an adjustment to start thinking this way.

Frontend

Frontends tend to lend themselves to an adaptive fractal structure depending on what framework you use. Because frontends usually involve React or Vue at the time of this writing we will focus on those. The recent release of Webpack v4 made the src and dist folders the defaults to run webpack without a configuration file so we’ll accept those as our starting point. Here is a general overview:

src/
    components/
    services/
    store/ 
    views/

Keep reusable components separate from components used a single time as a page with components and views folders. The store/ folder is used if your application needs a state management tool like Vuex or Redux. The services folder is less common but could help separate your request logic from your application.

React

In React projects, especially ones involving Redux, the src/components folder complements the fractal style. For each component you probably want a folder with the Redux container, React component and styling file. It should look something like this:

src/
    components/
        Navbar/
            Navbar.js
            NavbarContainer.js (more commonly index.js)
            Navbar.spec.js
            main.css
    services/
        user.js
        admin.js
    store/
        actions.js
        configureStore.js
        reducers/
            rootReducer.js
            user.js
            admin.js
    views/
        Home.js
        Admin.js
        Login.js
    App.js
    main.js

This style works well with React and Redux because it helps keep the container logic separate from the component. Even the store works well with fractal as it keeps complex configuration files and reducers separate from the rest of the application.

Vue

For Vue projects, a more adaptive fractal style is preferred. Because Vue’s single file components can easily take advantage of scoped styles and a Vuex store is easily mapped to a component our project structure should reflect this:

src/
    components/
        Navbar.vue
    mixins/
    plugins/
    services/
        user.js
        admin.js
        login.js
    store/
        user.js
        admin.js
    views/
        TheHome.vue
        TheAdmin.vue
        TheLogin.vue
    App.vue
    main.js

In Vue, components used only once are named with ‘The’ before it. Vue uniquely also has mixins and plugins so this structure reflects this, just as the React example had container files for reduxed components.

Backend

Backends are usually great candidates for linear project structures, especially JavaScript backends serving Single Page applications. Because there is no entanglement of controllers and views like in Ruby on Rails the backend is simply Models and Controllers that serve JSON data to be manipulated by the frontend.

The backend should be separated from the rest of the application similar to src/ on the frontend. The naming of this folder is debatable but most people settle on app/, backend/, or server/. Because modern JavaScript projects typically don’t use the MVC style I’d advise against naming it app as this conveys that the folder encapsulates both the front and back end. I personally choose server. Within this folder should be a file named either server.js or index.js as well as a routes.js file to keep all routes in one place. In a linear project the backend structure should look something like this:

server/
    models/
    controllers/
    helpers/
    routes.js
    server.js

A fractal backend structure tends to look like this:

server/
    user/
        model.js
        controller.js
        routes.js
    helpers/
    routes.js
    server.js

I find the fractal structure tends to lead to repetition in a backend context. As you can see in the above example for a large scale project there needs to be more than one routes file and within each resource, you have to repeat the few lines to configure the express.Router. And because it’s fractal you have to search extensively through the server to find routes and discover relationships they may have with other parts of the application. This is not ideal and forces developers to globally search for that route while guessing its name.

Misc. Folders

Additionally here are some pretty common folders. The assets/ folder is for stying assets like logos to be served via the backend. A scripts/ folder holds any automated build tasks or generators your team may have created. And finally, the test/ folder contains unit, integration, and end to end tests.

assets/ (or sometimes called public/)
scripts/
test/

Fullstack Project

A fullstack JavaScript application with an adaptive fractal style may look something like this:

assets/
dist/
scripts/
server/
	controllers/
	helpers/
	models/
	routes.js
	server.js
src/
	components/
	services/
	store/
	views/
test/
    backend/
        unit/
    frontend/
        unit/
        e2e/

Review

In summary, due to the complex nature of progressive web applications, you’ll likely find that starting with a linear structure for your frontend and slowly making it fractal will go a long way. For your backend stick with a linear structure until your application grows so massive that you have to start grouping files. Most importantly, go with what works best for your team. JavaScript changes, don’t get stuck with conventions that aren’t working and think carefully before using ideas from other languages or frameworks in your project.