Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An opinionated project template for client-side apps.
Pull request Compare This branch is 646 commits behind nprapps:master.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

nprapps' Project Template

About this template

This template provides a a project skeleton suitable for any project that is to be served entirely as flat files. Facilities are provided for rendering html from data, compiling LESS into CSS, deploying to S3, etc. (It actually supports deploying to servers too, but that's less well-tested.)

What's in here?

The project contains the following folders and important files:

  • data -- Data files, such as those used to generate HTML.
  • etc -- Miscellaneous scripts and metadata for project bootstrapping.
  • jst -- Javascript (Underscore.js) templates.
  • less -- LESS files, will be compiled to CSS and concatenated for deployment.
  • templates -- HTML (Jinja2) templates, to be compiled locally.
  • www -- Static and compiled assets to be deployed. (a.k.a. "the output")
  • www/live-data -- "Live" data deployed to S3 via cron jobs or other mechanisms. (Not deployed with the rest of the project.)
  • www/test -- Javascript tests and supporting files.
  • -- A Flask app for rendering the project locally.
  • -- Global project configuration for scripts, deployment, etc.
  • crontab -- Cron jobs to be installed as part of the project.
  • -- Fabric commands automating setup and deployment.

Copy the template


# Optional: checkout an initial project branch
# git checkout [init-map|init-table|init-chat]

rm -rf .git
git init
git add * .gitignore
git commit -am "Initial import from app-template."
git remote add origin$NEW_PROJECT_NAME.git
git push -u origin master

Configure the project

Edit and update PROJECT_NAME, DEPLOYED_NAME, REPOSITORY_NAME any other relevant configuration details.

Install requirements

Node.js is required for the static asset pipeline. If you don't already have it, get it like this:

brew install node
curl | sh

Then install the project requirements:

npm install less universal-jst
mkvirtualenv $NEW_PROJECT_NAME
pip install -r requirements.txt

Project secrets

Project secrets should never be stored in or anywhere else in the repository. They will be leaked to the client if you do. Instead, always store passwords, keys, etc. in environment variables and document that they are needed here in the README.

Bootstrap issues

The app-template can automatically setup your Github repo with our default labels and tickets by running fab bootstrap_issues. You will be prompted for your Github username and password.

Adding a template/view

A site can have any number of rendered templates (i.e. pages). Each will need a corresponding view. To create a new one:

  • Add a template to the templates directory. Ensure it extends _base.html.
  • Add a corresponding view function to Decorate it with a route to the page name, i.e. @app.route('/filename.html')
  • By convention only views that end with .html and do not start with _ will automatically be rendered when you call fab render.

Run the project locally

A flask app is used to run the project locally. It will automatically recompile templates and assets on demand.


Visit localhost:8000 in your browser.

Run Javascript tests

With the project running, visit localhost:8000/test/SpecRunner.html.

Compile static assets

Compile LESS to CSS, compile javascript templates to Javascript and minify all assets:

fab render 

(This is done automatically whenever you deploy to S3.)

Test the rendered app

If you want to test the app once you've rendered it out, just use the Python webserver:

cd www
python -m SimpleHTTPServer

Deploy to S3

fab staging master deploy

Deploy to EC2

The current configuration is for running cron jobs only. Web server configuration is not included.

  • In set env.deploy_to_servers to True.
  • Optionally, set env.install_crontab to True.
  • Run fab staging master setup to configure the server.
  • Run fab staging master deploy to deploy the app.
Something went wrong with that request. Please try again.