Skip to content
This repository has been archived by the owner on Mar 9, 2023. It is now read-only.

Latest commit

 

History

History
92 lines (57 loc) · 5.21 KB

DEVELOPMENT.md

File metadata and controls

92 lines (57 loc) · 5.21 KB

Security Planner: Development

Structure

Styles

LESS is used for stylesheets. The stysheet sources can be found inside the /src/less folder.

The current stylesheet structure uses app.less as the main entry point for all styles, with imports used depending on context. These follow the following name conventions:

  • page-*: styles for "Pages" of the website. "Pages" are normal sections like the Home page, the Action Plan, etc.
  • overlay-*: styles for "Overlays" used. "Overlays" are sections that pop up from some pages, like the "Tool" information overlay, the Bio overlays in "Who We are", etc.
  • vars-*: global variables to configure design-specific aspects of the styles such as colors, fonts, etc.
  • ui-*: styles used by global UI elements.
  • alt-platforms: additional style tweaks for specific platforms.
  • animations: animations referenced globally.
  • mixins: LESS mixins for more complex CSS compositions.

Image assets

PNG and SVG images are used. Those are automatically re-compressed when building with imagemin. Existing PNGs were also first optimized with OptiPNG.

Scripts

All JavaScript source code is located inside the /src/js folder.

This project uses ECMAScript 2015 (ES6), so our code is split around different classes and modules and combined into a single JS bundle.

The main files found inside /src/js are:

  • app.js: the main entry point for the application's execution. This loads all the dependencies needed for the application.
  • content.js: the content loading entry point for the application. Rather than waiting for the whole application to load first, content is loaded in parallel by this minimal bundle. This ensures the application's starting time is as low as possible.
  • ga-*.js: all Google Analytics scripts used, as separate files to avoid inline scripting as required by CSP.

Once inside /src/js, these are the folders used, and their purpose:

  • /actions: Flux actions used by the application.
  • /components: React components, used as views for the application.
  • /constants: Global constants, including some configuration flags.
  • /dispatcher: Main Flux dispatcher.
  • /routing: Code responsible for configuring the possible internal URI routes.
  • /stores: Code related to loading, parsing, validating, and maintaining the main state of the application through a data store, as well as its data models.
  • /vendor: Context-less code, used to maintain generic pieces of the application's functionality.

After compilation (see more below), JavaScript code is minified with UglifyJS prior to publishing.

Technologies

The project uses the following technologies:

  • React and Flux are used as the main application architecture.
  • Babel (with Browserify) is used to compile the code and transform the ES6 code into its (more widely supported) ES5 equivalent.
  • Core-js is used to provide shims for compatibility with older browsers that lack certain JavaScript APIs.

Third-party libraries

The application uses Google Analytics for (anonymous) user tracking. It is currently using a testing ID which should be replaced with a final ID at a later point (see the the deployment document for a full checklist of similar items that need to be updated prior to deployment).

For more information on other libraries used (such as NPM modules), check the LICENSES file.

External endpoints

The application uses Contentful's Delivery API to get its read-only content statically.

It also uses Google Forms as a means to save Feedback data.

Building

The application uses webpack as a manager for its development and build workflow. This build system compiles all LESS files into CSS files, copies all needed assets into their specific folders (including minifying images), and compiles, merges and minifies all JavaScript files.

To start development, download and install all dependencies using npm:

    npm install

Then use the dev task. This task builds the app, serves it as a local server, and then watches the src folder for changes.

    npm run dev

When that task is running, the current build version of the app is served at http://localhost:8080/index.html. On every source change, the build is recompiled and reloaded.

Once ready, a final, compressed, production quality version of the website can be built into the dist folder:

    npm run build

Check the testing methods for information on how to test the validity of the site's code and data, and the the deployment document for instructions on how to deploy the application.