Organizing Browser Application Files

If you are building a large, one-page browser application with the usual suspects of HTML, CSS, JavaScript, images, etc, you’ll have many files and staying organized is important. Here is a way to organize your files.

General Structure

MyApp/
    Makefile
    README
    etc/
    lib/
    src/
    tst/

Perhaps the first thing you will do when starting the project is fill the lib directory with all the third-party libraries you know you’ll be using. These libraries are dropped into the lib directory without modification. Just plop them there in the same form they are distributed. You aren’t allowed to edit these files. This directory is the only directory where you put files created by a third party.

The src directory contains all of the files that you create and write that will become part of the files downloaded by the browser of a user of your application. These are the files we are excited about writing.

The tst directory contains all the files that test the files in the src directory. These are the files we are not excited about writing.

The Makefile has a default build target that generates the directory called bld which is filled with production-ready files that can be copied to the production web servers. The files in the lib and src directories are combined, minified, compressed, and otherwise mutated to become the files in the bld directory. This target can possibly generate a MyApp.tar.gz file if that is how the distribution to production will be done.

The build process may be guided by data in files in the etc directory. For example, there may be manifest files that state which files are concatenated together during the build and the name of the resulting files. Exactly which files with which data are in your etc directory depend on which tools you are using in your build process.

The Makefile should have a clean target that deletes the bld directory.

The Makefile might have a test target that runs the tests in the tst directory.

The README should at least explain what the targets in the Makefile do and how to run the tests.

You should not need to run make build in order to test your application either with the files in the tst directory or in the browser while developing. You may have files in your etc directory that control how the development environment is configured.

An MVC-style Application

You might be using an MVC framework like Maria to help structure your JavaScript. In this case, there is a natural way to divide your application at a finer scale.

MyApp/
    Makefile
    README
    etc/
    lib/
        maria.js
    src/
        css/
        html/
            index.html
            templates/
        img/
        js/
            bootstrap.js
            controllers/
            models/
            views/
            util/
    tst/

The index.html files is the page that the user loads into their browser to start the one-page application. This may be named something different like myapp.html. This file loads the necessary CSS, image, template, and JavaScript files needed to run the application.

The templates directory contains any HTML templates used by your JavaScript views. These can be compiled to JavaScript and concatenated into one or a few JavaScript files during the build process.

The bootstrap.js file is the one with the call to window.onload that fires up the whole application. It will start the loading of the data from the server, create the model layer, build the views, and add those views to the page so the user can begin interacting with the application.

The controllers, models, and views directories contain the obvious.

The util directory contains utility code that is not specific to any of the model, view, or controller layers. There may be pure functions that make computations with no side effects. You might have some obscure DOM related utilities that you wish were written by a third party for your lib directory but that you have to write yourself for your unique browser scripting requirements.

Comments

Have something to write? Comment on this article.

jamesl October 14, 2012

Nice suggestions.

Is there a “default” Makefile you can share, or should we look at the Maria one for starters?

I’m also wondering, does the src/html/templates contain HTML or JavaScript? Do you make a distinction? If it contains js, shouldn’t these files be under src/js?

- James.

Peter Michaux October 15, 2012

Hi James,

I don’t have a default Makefile but the Maria Makefile would be a good place to start.

The files in the src/html/templates directory contain HTML. This HTML is compiled to JavaScript before serving it to the browser.

prinz October 17, 2012
You should not need to run make build in order to test your application either with the files in the tst directory or in the browser while developing

This may not be achievable when working with languages that are compiled to Javascript, like Dart or CoffeeScript.

Peter Michaux October 17, 2012

Hi prinz,

Even with languages like Dart and CoffeeScript there is no need to run make build during development as the source files can be compiled on-the-fly when served.

Jonathan October 19, 2012

Hi,

I'm wondering: where would you keep server-side scripts & libs? Should there be 2 folders under src clients/ and server/ ?

Peter Michaux October 19, 2012

Hi Jonathan,

The files in the directory tree I’ve described are only related to the client-side. Files for a server-side application should be in a completely separate directory. Possibly they should even be in a completely separate repository.

Mohit Seth November 28, 2012

There are some other new tools available for build process. I like Grunt a lot but there are some more tools like Yeoman as well. I like Grunt over Yeoman because Grunt is very customizable. I can easily create my own grunt task.

bumblehead November 30, 2012

I share files between server and browser client environments.

I use two directories for this, app and appSrc. Files in appSrc are used by the server. During the deployment process files from appSrc are combined, minified and copied to app where they’re accessible to the client.

Have something to write? Comment on this article.