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.

$3

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

$3

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

`json
{
"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
`

$3

##### 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.

$3

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 -- , 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.

$3

© 2016 – 2018, _The Dallas Morning News_.