Meteor is “a complete open source platform for building web and mobile apps in pure Javascript”. It’s really quite compelling and new. I wont go into all its virtues here, and only one of my pet peeves.

Meteor.js 1.0 was released yesterday, without a standard boilerplate or directory structure.

Contrast this with Rails, the popular web development framework which comes with a standard tree-like folder hierarchy for new projects. This is one of the many ways Rails is “opinionated”. Every Rails project has a similar structure, which means that I can look at and even start working on an existing unfamiliar project and basically know where to find stuff, and where to put stuff, and where to hunt for certain types of problems. This is great, and one of the reasons for Rails success from the get-go about eight years ago.

Meteor has the potential to be as great as Rails. And like Rails, Meteor claims to be opinionated. But Meteor lacks a standard directory structure or boilerplate for source files.

Yes, there are a few paragraphs in the Meteor docs addressing file structure, but it’s cursory and only top-level. Some see this as an advantage — developers have the flexibility to organize their project source files the way that suits each project best. But I think its a hinderance, making me think about extraneous implementation details when I should be thinking about my project’s features (and my customers’ experience). And it’s a hinderance to on-boarding new developers to adopt this cool platform.

This violates the principal of Convention Over Configuration. The Wikipedia article even uses project directory structure as the example to illustrate this principle!

“a software design paradigm which seeks to decrease the number of decisions that developers need to make, gaining simplicity, but not necessarily losing flexibility”

Ok, off my soap box.

Varied Solutions

Others have addressed this problem for themselves, for their organizations, and for others in the open source community to use. I have reviewed nine of these, and built a simple comparison spreadsheet. I’m sure there’s others, please leave a comment or message me if you have a favorite you’d like to add to the list.

As a disclaimer, I have not installed and used most of these. But I have read through their docs and code on github. There’s a good chance many of them are not 1.0 ready at this point.

Synopsis

Most of the projects are active, have been updated within the past month.

INSTALL

Some projects are simple github repositories. To install, just do a git clone, and then modify to your desire.

Others are Yeoman scripts (or other tool) that you can run from the command line. They also provide additional commands for generating new files as you add resources (collections or views) to your project.

TESTS

Only two come with tests (Pent and EventedMind). This is somewhat disappointing. And these are tests for the generator scripts themselves.

None of the projects provide boilerplates for your project’s tests. All modern web applications should be built with tests.

PACKAGES

A number of them come with packages pre-installed. Sometimes the included packages are really required (e.g. Cmalven’s generator-meteor generates coffeescript files) but most of the time these reflect the author’s preference for their starting configuration of a new Meteor project. The problem here is unless the package choices are maintained by the authors, they can fall out of date since the Meteor ecosystem is moving quickly.

DIRECTORIES

All of these boilerplates provide the top level directories: client/, server/, and public/ . EM has a both/ directory where you put code shared by client and server; makes sense.

Most provide a top level lib/.

One discrepancy is where to put collections. Some have a collections/ folder at the top level, while others put it into lib/ . One called it models instead of collections.

Inside the client/ folder is the most inconsistent. There’s usually a subdirectory for helpers/ and stylesheets/ (or styles/). And of course, views/ (the DiscoverMeteor book is the only one that names it templates/).

The client/views/ is organized with a place to put the layouts and templates. Apparently no one can agree how to set it up, e.g. subdirectories named application/ , includes/, common/, pages/, layouts/, and shared/.

Beyond that, the client/ folder might have accounts/, collections/, compatibility/, config/, controllers/, lib/, methods/, modules/, router/, startup/ or subscriptions/ . Yikes! When there’s not a directory there’s might be a single file.

A public/ folder can include fonts/ and images/ subfolders.

The server/ folder includes your fixtures, publications, server-side views, and security code. There’s no consistency how its organized either.

Lastly, only one provides a tests/ folder for your application tests. Bravo to Matteodem for that!

You can find my comparison spreadsheet here.

Conclusion

These various solutions provide a good study, and highlight the need for better conventions.

Although it can be argued the merits of one file structure over another, I really doubt there’s such a great advantage either way, and we just need to shit or get off the pot. Who can take the lead on this? I think it should be the Meteor core team, I mean who else is in a position?

For the time being, I’ll just make up my own preferences and establish my own conventions for my own projects like everyone else. Not quite what they mean by “convention over configuration” though.

Addendum

Since first publishing this article I’ve learned about other and newer boilerplate projects, including

Meteor Kitchen a Meteor application generator (includes the kitchen sink so-to-speak)

MeteorSkeleton git clone this starter project

Meteoris appears to be a new powerful open code generator and boilerplate for Meteor. I haven’t tried it yet but looks pretty awesome.

(last update Nov 18, 2014)