How to structure a Tabris.js project

“How do I structure the project?” is a common big question that comes to mind when we start a new project. While the Tabris.js CLI provides basic templates for certain architectural patterns, Tabris.js doesn’t prescribe any specific project structure. This is favorable because it allows you to make up a structure that suits your needs best. But even experienced developers may sometimes find it difficult to structure the complex ones.

There is no ideal structure that will work for every Tabris.js project as each project has a different purpose and therefore requires its own specific structure and rules.
The goal of this blog post is to present a file structure with the best practices, which performs well in particular scenarios and is easy to work with.

Our example project uses the MVVM (Model-View-ViewModel) architectural pattern and follows the separation of concerns design principle. You can also use it as a template for your future projects. I highly recommend checking out the example along with reading this blog post.

First, let’s start a new Tabris.js project to see how the structure looks like. When we run tabris init using the Tabris.js CLI command-line tool, then answer the questions and select the Model-View-ViewModel (TypeScript/JSX) template, we will end up with the following structure:

As you see, all of the source files are placed directly in the src folder. You can keep all the files there, and Tabris.js will not complain about it. However, as your project becomes larger, it will become very difficult for you to maintain your files and keep your src folder neat.

After getting some experience with various Tabris.js projects, I found the folder structure in this example project best for me. The structure is a recommendation only, and you are welcome to update it for your own use case. Here is how I organized the example project:

Most of the folders are self-explanatory. But let’s take a look at them one by one to understand their purposes and the type of files you would put in them:

1. assets: A top-level folder in the root directory and contains raw files, such as images, fonts, audios, videos, etc. We grouped the files by type and placed them in the relevant folder.
2. src/actions: Contains files that are functions wrapped as classes which allow for better integration with the dependency injection and provides better testability. These are functions with side-effects, meaning they modify the application state, while helper functions in common do not.
3. src/common: Contains common reusable helper files, such as converter, formatter, decorator, etc.
4. src/model: Contains model classes. These classes are data/domain models, not view models.
5. src/repositories: Contains repository files that isolate data sources from the rest of the app. A repository file mediates between data sources (such as runtime storage, web services, and caches) and the rest of the app.
6. src/resources: Contains resource dictionary files for Tabris.js Resources and its subclasses in order to select values based on criteria such as platform and language.
7. src/services: Contains singleton classes marked with @shared decorator.
8. src/views: Contains one subdirectory per view. Each directory contains a view, a ViewModel, and other relevant related UI code. The folder additionally contains a shared directory that contains reusable view components.
9. tests: Another top-level folder for unit tests in the root directory. It contains almost the same file structure with src and additional configuration files. The test files in each subfolder are arranged according to the corresponding files in the src folder.

I hope I have provided useful information that can help you set up a well-organized and easy-to-scale structure for your project. If you have a question or recommendation, feel free to leave a comment below.