Folder Structure for SPA Applications (Angular, React, Vue ...)

When starting a new Single Page Application (SPA) project, one of the most crucial decisions is the organization of the project's folders. A well-defined structure can simplify development, maintenance, and collaboration with other team members.

In this article, I will explore a folder structure for starting an application, aiming to make it flexible and scalable throughout development.

It is important to note that this approach is especially useful for frameworks that do not offer a highly opinionated folder structure by default.

Directory Architecture

Below, I present a visualization of the directory architecture that I recommend for organizing SPA projects:

/src
│
├── /core
│   ├── (**Essential functionalities to initialize the application**)
│
├── /components 
│   ├── (**Presentation components**)
│
├── /widgets
│   ├── (**Independent components**)
│
├── /services
│   ├── (**Services to communicate with the API**)
│
├── /domain
│   ├── (**Application-specific types and utilities**)
│
└── /routes
    ├── (**Application pages**)

This structure provides a clear separation of responsibilities, facilitating development, maintenance, and scalability of the project.

In the continuation of this article, I will explain the responsibility of each folder.

/core

This folder is used to store the necessary code to initialize your application and load essential functionalities. Here reside essential services, components, and other functionalities that are used in various parts of the application.

/components

Here lie the reusable components of your application focused on presenting data to the user.

/services

In this folder, you should place the services responsible for communicating with your backend API. These services may include authentication logic, HTTP calls, and data manipulation.

/widgets

The components in this folder are designed to be incorporated into pages independently. They use services to fetch the necessary data and make use of markup and other components to display them.

Ideally, these components should be customizable only in basic styling aspects, such as colors, fonts, and sizes. They should not receive data directly, as they should be able to fetch it on their own.

/domain

This folder houses types and utilities specific to the application. Here you will find data type definitions, functions, classes, and business logic that are specific to the application domain.

/routes

The components in this folder combine other components to create complete pages that are displayed when the user accesses certain URLs.

Additional Tip:

In addition to the folder structure, a valuable complementary practice is to have one or more (in each directory) README.md files containing information about the purpose of each folder, usage guidelines, and any other relevant information for developers interacting with the code in the future.

Conclusion

Remember that there is no one-size-fits-all approach that works for all projects. The structure presented in this article is just a suggestion and can be adapted according to the specific needs of your project.

Try out this structure in your next project and adjust it as needed to meet your requirements.

I hope this article has been helpful in getting you off to a good start with your SPA projects!