Repository files navigation

This repository contains all the front end code for the currentustwo.comwebsite and the toolset required to build and deploy it.

In order to be able to have full control over all aspects of the website –including transitions between pages – and to make navigation super fast by nothaving to reload the browser, we decided to build the site as asingle-page application. We choseReact.js as a main JavaScripttechnology enabling us to do this, since it has built in support to renderpages on the server side too (called isomorphic rendering). This way we couldkeep the initial rendering performance snappy on mobile and let visitorssee content without an extra data loading step which usually happens with mostclient side JavaScript framework. To enable server side rendering and to haveproper URLs, we put a small Node backend server behind our app.

Our content management system behind this is a Wordpress instance which doesn'tactually render the pages itself, but instead serves content up viaWP APIthrough a mixture of standard and customised JSON REST API endpoints, making thevast majority of the content editable.

With the current set of challenges and available browser features we foundReact.js to be a great solution to templating and events on the UI. Thecomposability of components with the one way binding and "queryless" eventhandling offered by JSX templates is solving the right problems, without tryingto do too much and become a framework. The easy to implement server siderendering combined with the ability to prevent rerendering on client side (byinternally doing a comparison to the virtual DOM) is also a great feature tomake it a viable solution on mobile.

To make it a single-page application we put Flux Routes and Store behind theReact front end, so that it can take over the navigation from the browser andload data from Wordpress by itself.

Since we need to precompile JSX anyway, in our quest to minimise the number oflibraries (like Underscore, etc) and push a future-proof way of working withJavaScript, we adopted a lot of ES6 features by transpiling the code with Babel.

As for the CSS, we're using Sass to be able to split our styles and store themtogether with the components. But in general we're trying to minimise thereliance on Sass language specific features and instead write as much pure CSSas possible, getting ready for a CSS Next / PostCSS world just as we did withES6.

For the animated illustrations on the site we use SVG sequences, controlled by asmall React component. This is unfortunately only possible with inlining SVGs,but all the static vector symbols are stored in one, external SVG sprite,polyfilled for old Internet Explorers withSVG for Everybody.

Since all the heavy content work is done for is in Wordpress, our Node / Expressapp is kept as light as possible. The only two main responsibilities aredelivering fully baked HTML files through running React rendering on theprefetched content and responding to the same routes as the front end app does.

As we had quite a lot of components (or microservices if you will) to tietogether – multiplied by production + staging + dev environments – we didn'twant to overburden our Node server and decided to put an Nginx proxy in place.

While we started out using Gulp for our frontend builds which was a veryconvenient start point for quickly iterating different combination of tools,in the end we settled on shell scripts using the fastest command line builds oflibraries.

For JavaScript we're using Browserify (plus Persistify caching) to process ourcode with Babel and resolve dependencies using Aliasify. Our Sass code iscompiled using SassC with PostCSS's Autoprefixer taking care of vendorprefixing. All this happens in a dedicated compiler Docker image, so that we cankeep the production application as lean as possible.

To get the Docker environment up and running and to tie all of the abovetogether, we created a fleet of Makefiles to get some extra flexibility withshared variables and task composition on top of shell scripting.

We haveeverything served up from a CDN, and by that we mean that ustwo.com ispointed at the CDN URL on a DNS level! Needless to say this guarantees greatload speeds across the globe and at very little cost. Call it the "CDN first"approach if you will – check out ourblog post about this here.

Unless you have a lot of user dependent dynamic content (and it's not feasiblemoving these areas to subdomains) the trick is to remove caching from all layersof the stack, while keeping the client side cache / expiry short (we're usingonly 1 hour or effectively one session).

This way the only place you need to worry about and manage cache is the CDN. Ofcourse for this you need to have a decent CDN which has an API to purge andprefetch content. At this point all the servers and applications behind can bescaled down to no cache and minimum resources as they'll only be accessed by theCDN network for an occasional update.

So here's how all this fits together and creates a working setup with ourWordPress backend and CDN.

We're aiming to support all evergreen browsers (Chrome, Firefox, Edge and Operaon all platforms), Safari on Mac and iOS, Internet Explorer 10-11 and AndroidBrowser 4.2-4.4.4.

In case you were wondering, we've chosen these as we wanted to be able to useFlexbox, and they also happened to conveniently overlap our historicalvisitor profiles from Google Analytics.

If you see any misbehaviour with one of these browsers please open an issue!

Being a studio which is passionate about delivering a great user experienceeverywhere and early champions of mobile, we kept performance in the front ofour minds throughout the process of building the websites.

This means that we are continuously reviewing both hard metrics and perceptualperformance. To get reports and keep an eye on things, we foundGTmetrixto be a great tool with a generous free tier. It calculates both PageSpeed andYSlow scores, generates a network waterfall, renders a filmstrip view and sendsan automated report of all these regularly.

There are too many things to list here, but we mentioned a lot of optimisationsthroughout this README and might cover some of them specifically in blog postslater.

Officially supporting only modern browsers doesn't mean that we ignore people(and browsers) with special needs.

• We're delivering prerendered HTML, so content is delivered to and rendered onclients without Javascript (or with overzealous ad blockers)
• Clean, standards compliant markup
• WAI-ARIA tags (TODO: test more comprehensively and with real users)

In order to get up and running you need Docker. The best way to installDocker is to follow the currentDocker documentation

Then add the following aliases to your/etc/hosts file:

127.0.0.1 local.ustwo.com127.0.0.1 staging.ustwo.com

Note: For setup without the native docker client, skip this step and seeDOCKER-SOURCE.md.

• Open a Terminal window and go to the project folder.

The easiest way is to load the vault image from a tar. If you receive the imagetar from someone in the team just do:

    $ make vault-load VAULT_PATH=path/to/vault-2015.tar

If you do not have access to this tar then you can proceed by generating yourown self-signed certificates.

    $ make vault-generate-cert    $ make vault-build

Note: If you use self-signed certificates you probably want to use yourdocker IP (e.g.docker-machine ip dev) instead of a customustwo.comdomain.

Note: Check theMAKE.md for an explanation of how the Maketasks are structured.

• Open a Terminal window and go to the project folder.

Prepare a new environment:

    $ make compiler-build build

Compile the assets (you can use only this when you're only recompiling on frontend stuff):

    $ make stuff

Or target specific subtasks:

    $ make css             # compiles SASS files    $ make spa             # compiles the React app    $ make vendors         # compiles app dependencies

Note:css andspa combined withVERBOSE=true will create sourcemaps.

Note:spa andvendors combined withFLUSH_CACHE=true will skip anycache created by browserify. Ex:

    $ make spa VERBOSE=true FLUSH_CACHE=true

Deploy app (when you need to restart services):

    $ make -i love LOCAL_FS=true VERBOSE=true

Note: Add the flagLOCAL_FS=true if you want to use your local files insteadof the ones inside the containers.Note: Add the flagVERBOSE=true if you want the JS and CSS expanded and morelog output on the services.

As long asLOCAL_FS=true is set a convenient way to refresh the environmentis:

    $ make -i love stuff LOCAL_FS=true

As it will rebuild the assets (stuff) and recreate the containers (love)remounting all necessary files from the host environment.

Clean the environment:

    $ make clean

See Node app logs with:

    $ make app-log

And Nginx logs with:

    $ make proxy-log

• Open a Terminal window and go to the project folder.

CSS has extra tasks to speed up the development cycle.css-watch starts afswatch process inthe host machine watching any scss or css file underscr/app.

    $ make css-watch

Note:brew install fswatch to installfswatch in your machine.

sync starts a dockerisedbrowser-sync proxy listening by default to port3000. So you can combine the two:

    $ make -i sync css-watch

Openhttp://192.168.99.100:3000 in your browser and start editing scss andlet the toolchain compile and push changes to the browser.

Note:browser-sync uses a self-signed certificate so usinglocal.ustwo.comor the raw IP will make the browser complain. If you need to overcome thisplease add a forward rule to Virtualbox so you can usehttp://localhost:3000.

• Open a Terminal window and go to the project folder.

Run all tests:

    $ make test

We believe that every component should hold a single responsibity, and whichfunctionality must be working independently from the context the component isinstantiated in.

To enforce best practices – like storing functionality and styles in thecomponent they belong to – we created a sandbox to test components in anisolated environment.

To prepare the sandbox run:

    $ make sandbox-build

And start the sandbox server with:

    $ make -i sandbox LOCAL_FS=true

The sandbox will be available athttps://local.ustwo.com:9443/sandbox

We're using Mocha + Chai + Sinon to run unit tests against JSDOM as this setupworks well with React and executes fast.

Run the unit tests:

    $ make assets-unit-test

To keep setup simple and still be able to test Internet Explorer and mobilebrowsers running on real devices, we're running integrations tests using SauceLabs with a Sauce Connect tunnel. This unfortunately means that if you want tobe able to run these tests, you'll need to create an account and set upSAUCE_USERNAME andSAUCE_ACCESS_KEY as environment variables.

Also to minimise context switching, we're running our simple sanity testingsuite using Mocha + Chai + Chai Promises + WD.js.

Run the integration tests:

    $ make assets-integration-test

If you need more info on what's happening with the tests, you can either log into the Sauce web UI to see the Selenium logs to understand more details aboutthe browser interactions or run verbose mode locally for more info on the APIrequests and their results:

    $ make assets-integration-test VERBOSE=true

TODO: add flow diagram about git branches -> CI, etc

We're using Docker Hub and Docker Machine to tag and deploy Docker images, formore info seeRELEASE.md.

To read up on our coding style and general contribution guide, have a look atCONTRIBUTING.md.

ustwo.com website front end and toolsCopyright (C) 2015-2017 ustwo fampany limited.

This program is free software: you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with this program. If not, seehttp://www.gnu.org/licenses/.