1. Setting up Newsky
2. Application Architecture
3. Pages & Previews
4. Todos

Setting up Newsky

Prerequisites

You will need the following things properly installed on your computer.

• Homebrew  (or compatible Node installing package manager, mac-ports?)

• Node.js (with Yarn or NPM)

Step 1: Check your node version & upgrade if needed.

$ node -v
v8.0.0 # if you see this or higher, you're good!

If not:

$ brew update
$ brew upgrade node

Step 2: Clone the "MyTodos" (todo-app-giant) repo & cd into the directory.

$ git clone [email protected]:nypinstripes/todo-app-giant.git
$ cd stash-search

Step 3: Install App Dependencies with yarn or npm.

The app was initialized & built using Yarn, however it has been tested & confirmed to work with npm.

$ yarn install

or

$ npm install

Step 4: Build & Start the App (in Production Mode)

Individual build (dev/prod), test & server start commands can be found in the scripts hash in package.json.

$ yarn launch

or

$ npm start

Step 5: Running Tests

There are a few ways to run the MyTodos test suite. Presently, only tests for renderring routes & persistant layout elements.

• yarn/npm test to execute the test suite in single run mode & generate Jest snapshots.
• yarn/npm test:update to execute the test suite in single run mode & update Jest snapshots that have changed.
• yarn/npm test:watch to execute the test suite in constant watch mode & update Jest snapshots as they're changed.
• yarn/npm test:coverage to view code coverage (lcov) & render performance reports using the built-in react tool (formerly Istanbul).

Application Architecture

Web Backend

NodeJS

The runtime environment (rte) is NodeJS and was written on v11.2.0, however it should be able to run without issue on any NodeJS version higher than 8.0.0.

Express

The webserver is ExpressJS as it continues to be the more popular of the choices for running web backends on Node, Hapi would be a suitable alternative.

Pug

The server-side markup is renderred using the PUG templating engine, which has a high degree of reliability with build tools like Webpack.

UAParser

As a simple alternative to polyfilling with a library like modernizr, there's also a JS library I used called UAParserJS, which detects & extracts loads of useful info about the client machine upon the first request. With this info we can look at things like the client's user-agent to determine if their browser is among the ones that are supported.

The list of supported browsers can be found in the server helper utils file under agents.

In addition to helper functions, UAParserJS also offers fine-grain access to:

ua,
browser: { name, version },
engine: { name, version },
os: { name, version },
device: { model, type, vendor },
cpu: { architecture }

Build & Transpiler Tools

• Webpack 4

• Babel 7

Frontend Application

React/Redux

Component Architecture

Sass (SCSS syntax)

The 7-1 Pattern

• The 7-1 Pattern
• Aesthetic Sass 1: Architecture and Style Organization

App Styles

Folder	Description
/base/..	Styles applicable globally, throughout the app, like browser resets/normalize files.
/common/..	Styles for visual elements with specific classes, but do not have components attached to them (e.g., .overlays, .animations). Files should be separated by their purpose.
/components/..	Styles applicable to individual components (these files are appended near the end and are overridden only by vendor styles).
/layout/..	Styles for standard elements that are persistent throughout the experience & on every page. Files should be separated by elements.
/vendor/..	Styles for elements that are particular to 3rd party plugin libraries and secondary browser type & version support. These styles load last and have the highest precedence.

Shared Sass Helpers /shared/data /shared/scss

Folder	Description
_breakpoints	Definition of app wide media query breakpoint rules, logic & utility.
_colors	All colors should be html named colors which can be found at Color Names or predefined named variables sourced from the sip or swatches OSX apps, or similar interface (based on Chirag Mehta's famous "name that color" tool), or from formal design guides except those inherent to browsers W3 Color Names, which will not appear in this list. Please keep them alpha sorted, use all lower-case dasherized variable names.
_functions	Sass helper functions - Things like custom short hand utilities for fonts, colors, borders etc.
_mixins	Sass mixins

Vendor Libraries

• Bourbon Sass

• Breakpoint Sass

Naming Colors Resources

• Swatches

• Sip

• Colblindor

• Name That Color

Testing with Jest

Snapshots are generated using the jest testing library, at present there are only basic Route/Layout load & render tests in the suite.

Pages & Previews

Newsky Search

404

Landing

Search Results

Note: Searches submit as you type, there's a 6 second debounce delay as not to make too many network requests.

Article Detail Overlay

Unsupported Browsers

(Filler) Docs Pages

(Open) License

(faux) Privacy

(faux) Terms/Conditions

TODOs

• On List/Grid views, remove custom pagination & add Infinite (Fetch &) Scroll, with React-Virtualized.
• Complete adding < Prev & Next > navigation controls on Article detail (ArticleOverlay) view.
• Improve truncation display method for ListItem view descriptions.
• Make navigating between articles in Article detail (ArticleOverlay) views "perma-linkable" & update url on navigating.
• Add sort & page # to results url history.
• Reduce search network requests.
• Add tap, touch & swipe controls for mobile devices.
• Add more tests & increase coverage & reliability.
• Performance (loading, updating & painting) audit, with network optimized media sizes.
• More inline Documentation!!
• Perform more x-browser/device/OS UI/UX sanity/QA checking (currently only verified with Chrome).
• Make use of some of the deeper webpack optimization features like Tree-Shaking, CommonsChunking.
• Attempt lazy component loading with System.import();