illustration by Adrien Griveau

I have been working on Meteor projects for more than 2 years now. I already shared the reasons of this choice in a previous post. Today I want to address the question of file structure.

Unlike frameworks such as Ruby on Rails, which has clear instructions on how files should be organized, Meteor lets you decide how you want to structure them. It only sets a handful of rules on files priorities.

For instance, files inside a directory called lib are always added above all other files. Also, Meteor sorts all files in alphabetic order.

But this autonomy leaves first-time users with a lot of questions, as you can see on StackOverflow

or on Meteor’s forum.

Obviously, the topic is hot.

Abigail Watson, a well-known developer in the Meteor family, wrote an article about it. In her awesome Meteor cookbook, she dedicated a section to describe the different file structures, depending on your project. As you can see, there’s more than one solution.

So, how do you set up the right structure for your project? Here are my thoughts and return on experience based on the different projects I run at eFounders.

Why I decided not to follow the Ruby on Rails file structure

Meteor evangelist Josh Owens (if you don’t know him, he’s the guy behind Meteor news site crater.io, The Meteor podcast, and The Meteor club) reuses part of the directory structure used in Ruby on Rails. But as he explained in this article, his main reason for doing so being “having spent 9+ years working with that framework”, it didn’t convince me (no offense Josh).

Going a step further, here are my reasons not to use the Ruby on Rails file structures.

First, it generates too many small files and directories. You end up with tenths of open tabs, and switching between tabs can very quickly become annoying.

Second, I almost always work on a specific task on a specific part of the app (let say the comment system of a blog). Therefore, I like to have all files related to this task close to each other so that I can easily find and edit them. And the Ruby on Rails structure doesn’t let me do that.

For instance, let’s take a blog. Imagine you have a commenting module and you want to display the date on which each comment was posted. To do so, you have to update 3 different files:

add the date on the comments collection — client and server

update the template related to the comment to display the date — client side

update the method to insert the date on which a new comment is posted — server side

In a typical Ruby on Rails structure, you will have to dig through 3 different paths spread across the project to find those 3 files. I prefer opting for the easy way.

Let me share with you 3 optimal structures on Meteor.

Three file structures I use and recommend, based on the size of your project

Flat organization

For a small project, Meteor lets you use a pretty simple file structure. When you create a new empty project, it will generate:

one single .js file with your entire code (client and server)

one .html with all html

one .css with all the styles

Here’s how it looks:

While it’s often enough when you create simple packages, I strongly recommend splitting files in a more structured way for more complex projects.

Package Oriented

For big or open source projects such as Telescope, the ultimate solution is to use packages to split functionalities. This method gives you the flexibility to decide to use some features or not and to manage dependencies between packages.

As Meteor says in its documentation:

This is the ultimate in code separation, modularity, and reusability. If you put the code for each feature in a separate package, the code for one feature won’t be able to access the code for the other feature except through exports, making every dependency explicit. This also allows for the easiest independent testing of features. You can also publish the packages and use them in multiple apps with meteor add.

Indeed, it is the ultimate solution, but it also takes more a time to create, update and manage those packages. For instance, each time you want to add a file, you will need to update package.js to include this new file. Same goes for file editing, removing, etc.

As you can see, maintenance can be pretty heavy and time-consuming. Therefore, for my latest big project for eFounders, I implemented an intermediary approach, splitting files by features or module.

Module Oriented

Keeping the same example as above, all files linked to the ‘comments’ module of my blog will be stored close to each other. You can find them and access to the code in a heartbeat, as in the ‘package oriented’ approach.

However, this method gets rid of the package.js file, thus it becomes as simple as the “flat organization” of files as described above.

Here is how it looks like:

As you can see, all files related to the module banq are now together. Each file contains the code for a specific Meteor system, one for events, one for helpers, one for collection, one for publish, ...

A “module oriented” file structure balances easy maintenance and file separation.

I’d love to know how other Meteor users structure their files: feel free to share it in the comment section.

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.