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.