Published originally in

This is post #1 of 3 to explain about fsstatic2. Beware: it may change forever how you approach web development. :-)

In the past two years I’ve been working a lot with web development and AngularJS.
FreedomSponsors is an open source web application that I made before that, so it doesn’t have in it all those cool new things that I have learned.

I’d like to change that, so I’m rebuilding FreedomSponsors as a AngularJS-based Single Page Application.
The primary reason I’m doing it is because I believe that if FS has a really friendly development environment, more people will be able to collaborate with it and this will help the project move forward.

There’s also a secondary reason: I want this new website to serve as example for people who want to learn more about good practices for web development – this is what this post is about.

The resulting webapp right now is still far from complete (feature-wise), but its architecure already has some good ideas that you may want to apply on your project. Or, if you’re starting a new project, you can just clone the project and go from there.

The main architectural features it has right now:

  • fshelp - A list of commands easy at hand so we don’t need to memorize anything
  • JsHint: Everyone loves their javascript style checked
  • DOCS (docs.html): A “playground” page that can be used both for 1) developing/testing new components, and 2) documenting how to use them
  • The app (index.html): A single page application that you can run locally (ui-router based)
  • Mock API: With this we can mock all of the backend JSON api. Focus on front-end development first; worry about the real backend api later.
  • Fast save/refresh cicle: Using devbuild/runserver, you end up with a development environment where you can save files and hit refresh, with no build steps in between (except for scss files, at least for now)
  • Javascript tests, with coverage report – Bonus: you can reuse the same mock api in the tests too
  • Production build: Build in production mode with all js and html concatenated in a single file. Bonus: it also works with file:// so it should be possible to port it to mobile with no (or maybe very little) modifications using Cordova (yes I intend to do this with FS in the future)
  • Generated CSS using Sass

Exciting, isn’t it? :-)

So, let’s dive into it with a little more detail…

Get it up and running

It should be really simple and fast, just follow the readme on github, or watch the video below.

Oh, can you please let me know in the comments below how long it took you? :-)

Now there’s a good practice worth noting here:
Good Practice #1: Have a project help like this.


People working in your project should not have to waste their time memorizing commands (if the predefined commands have autocomplete, even better)
When you have someone new in your team, this should save you some time

Folder structure: What is where, and how the build works.

Here’s a quick summary for you

src/                            # All your code is belong to me<br />src/pages/index.html            # The main application<br />src/pages/docs.html             # The DOCS application<br />src/**/*.{js|html|scss}         # The bits and pieces of the app<br />src/api/api.js                  # The real API that will talk to the backend<br />src/api/api_mock.js             # The fake API which is what we'll be using for a while<br />src/**/docs/**/*.{js|html}      # Documentation pages and unit tests (none of this will see production)<br />src/**/docs/**/test_*.js        # Unit tests<br />docs_src/                       # The docs framework<br />lib/**/*.{js|css}               # Third-party stuff<br />settings/*.js                   # Some settings that differentiate dev vs. prod environments<br />dist/                           # The result of our build goes here<br />dist/index.html                 # src/pages/index.html, after some find/replaces<br />dist/docs.html                  # Guess!<br />dist/css/fs.css                 # src/**/*.scss gets compile here<br />dist/css/lib{.min}.css          # Part of lib/**/*.css gets concatenated here<br />dist/css/lib{.min}.js           # Part of lib/**/*.js gets concatenated here<br />dist/js/fs.js {P}               # src/**/*.1 gets concatenated here (except for **/docs/**)<br />dist/js/fsdocs.js {P}           # src/**/docs/**/*.js gets concatenated here<br />dist/js/docs.js {P}             # docs_src/**/*.1 gets concatenated here<br />dist/js/fs.js                   # Part of lib/**/*.js gets concatenated here<br />testlib/**/*                    # Libraries used only in unit tests<br />gulpfile.js                     # THE build<br />                        # Handy commands

(Items marked with {P} are only relevant in the production build)

The video below will demonstrate a little more what the build can do.

There’s something I forgot to show in the video, which is, when you build the app using prodmock, it also works with file:// like this:


A good side effect of this is that in the future we are more likely to be able to make an IOS/Android app out of it using Cordova (yes I intend to to that in the future).

OK, this concludes the first post. In the next two posts I’ll talk about:

  • index.html - How the main application works
  • todo.js - A detailed exampled of how to make a component
  • docs.html – A component catalog AND a playground environment.
  • Tests: running and debugging
  • test_todo.js: how to write good tests

Stay tuned.