elections.dallasnews.com

                 _ _.-'`-._ _                 
                ;.'________'.;                
     _________n.[____________].n_________     
    |""_""_""_""||==||==||==||""_""_""_""]    
    |"""""""""""||..||..||..||"""""""""""|    
    |LI LI LI LI||LI||LI||LI||LI LI LI LI|    
    |.. .. .. ..||..||..||..||.. .. .. ..|    
    |LI LI LI LI||LI||LI||LI||LI LI LI LI|    
 ,,;;,;;;,;;;,;;;,;;;,;;;,;;;,;;,;;;,;;;,;;,,
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Our system for election-night interactive features, containing election results and updates via a liveblog.

Requirements

• Node ~= 5.x.x (node -v)
• Webpack ~= 3.11.x (npx webpack -v)

Local development

1. npm install for client dependencies and dev tooling
2. Create an aws.json file in the project's root with:

{
  "accessKeyId": "",
  "secretAccessKey": ""
}

3. Add the below entry to your Hostfile to alias http://local-dev.dallasnews.com to localhost:

127.0.0.1    local-dev.dallasnews.com

Contents

Directories

• build: Build system (gulp) and related utilities.

• dist: Packaged, compiled and ready-for-production assets.

• src: Uncompiled/transpiled JavaScript and SCSS files, with JavaScript broken into ES2015 modules for Browserify

• src/shared: Shared modules such as live blog- and election-related data models, helper objects for loading and polling for data, etc. that can be shared across builds

• src/{{ interface type }}: Modules that are specific to an individual interface type (e.g., homepage or main app).

• src/main-{{ interface type }}.js: The main JS file for each interface type. Each of these files gets built and transpiled into a separate bundle.

Files

• election-metadata.json: Per-election settings, such as URL endpoints, liveblog IDs and page metadata.

• aws.json: AWS credentials used when publishing election pages. Never, ever commit this file to Github.

• .babelrc, .browserslistrc, .eslintrc.json: Configuration files for our build system (that handle ES6+ transpiling, CSS browser prefixing and JS linting, respectively).

• .gitignore: A list of files/paths that Git should ignore.

• package.json and package-lock.json: Files to specify NPM dependencies, build system script aliases and other common Node functions.

• README.md: This documentation.

Usage

The following build-system commands are available:

• npm run build: Compile ES6 into cross-browser compatible JavaScript, SCSS into CSS and nunjucks templates into HTML. A wrapper around the gulp build command used in earlier versions.
• npm run watch: Does all of the above functions, with file-watching and a local dev server using BrowserSync. A wrapper around the gulp command used in earlier versions.
• npm run deploy: Runs npm run build and then deploys the output to the S3 destination specified in election-metadata.json. A wrapper around the gulp publish command used in earlier versions.

Specifying an election

By default, each of these commands uses the election-metadata.json configuration for the default election. (This is the first listed configuration that has "isDefault": true, or the first configuration listed in the event .)

To specify a different election, call any of the above functions with the following appended to the end of the same line:

-- --election YYYY-MM-DD

(where YYYY-MM-DD is a correctly-formatted ISO 8601 date).

So, for example, to develop on an election that's happening on May 5, 2018 using file-watching and a local dev server, you would run:

npm run watch -- --election 2018-05-05

And to build and deploy the files for an election that happened on March 6 of the same year, you'd run:

npm run deploy -- --election 2018-03-06

Note the first set of hyphens after the NPM command — these are used to specify that we're passing the election argument (or the other arguments listed below) to the underlying build system, rather than to NPM/Node itself.

Other options

When specified, these also need to be called in the format <command> -- <options>, as mentioned above.

• --production: minifies compiled JavaScript and CSS.
• --purge-cloudfront: When used with the npm run deploy command, initiates a cache invalidation in AWS CloudFront for the files that have changed. This is often needed when deploying to S3, due to our CDN settings.

NOTE: We need to double-check that the invalidation flag is working correctly before the next election.

Copyright

© 2016 – 2018, The Dallas Morning News.