Source code for www.Thomas-Anderson.net

This repo contains the end-to-end source code for www.thomas-anderson.net and is published entirely free and under the MIT License - Hopefully the code and below description explains the architecture well!

If you do end up using this for any commercial purpose, or found the code useful please consider buying me a coffee:

Architecture

(Click image to view full size. Made with Excalidraw - raw file: architecture.excalidraw)

Source folder : source Output folder : _build

To build, test and deploy:

npm install
npm run build
npm run test
vercel --prod

Please note, for jest-puppeteer automated testing, you will need a browser installed on your environment. For Debian-based systems, (I use Google Cloud Shell) I would suggest installing Chromium and it's associated dependencies:

sudo apt-get install chromium
sudo apt-get install ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils

HTML Build

For HTML, we use Liquid templates and eleventy. We also manually copy across the /source/img/ folder and the /source/css/bundle.css file.

To build the HTML:

npx @11ty/eleventy

To watch for file changes:

npx @11ty/eleventy --serve

CSS Build

We use TailwindCSS, with the raw CSS file in source/css/tailwind.css. This is then processed using PostCSS as per the documentation into source/css/bundle.css.

The two configuration files (tailwind.config.js and postcss.config.js) are set up to check for two environment variables:

PURGE and MINIMISE

When set, PURGE will look through any .html and .liquid files in /source/ and will purge any unused CSS classes from Tailwind.

When set, MINIMISE enables the cssnano PostCSS plugin to minify the resulting bundle.css file.

To build the CSS (without purge and minimise):

npx postcss source/css/tailwind.css -o source/css/bundle.css --verbose

To build the CSS (with purge and minimise):

PURGE=true MINIMISE=true npx postcss source/css/tailwind.css -o source/css/bundle.css --verbose

Testing

We use Puppeteer, Jest and jest-puppeteer to run tests in headless chromium.

On Debian-based systems, run the following to ensure dependencies are available:

sudo apt-get install chromium
sudo apt-get install ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils

All tests are available in source/_tests. A screenshot of each test run is saved to _build/_testresult.png and a report is saved to _build/_testresult.html.

To run Jest tests:

npx jest --verbose

Deploy (Vercel)

We use Vercel for our site. First, install the Vercel CLI and run:

vercel login

Then once configured, run:

vercel

To deploy a preview deployment.

Then run:

vercel --prod

To deploy to production.

Content Security Policy Headers

To ensure better security, we apply Content-Security-Policy (CSP) headers in Vercel, using the vercel.json file as described here. Since we use some inline code (both Javascript and CSS) we need to include the SHA hashes that match the following pieces of code:

this.media='all' (Google Fonts load) = 'sha256-MhtPZXr7+LpJUY5qtMutB+qWfQtMaPccfe7QXtCcEYc='

(Inline CSS in test result HTML page) = 'sha256-Vv5TW3/Rmik7SBeZlrkFStK4ozYD3t6SlHE6tlWhW8Y='

Note: We also fallback to unsafe-inline for script-src for browsers that don't support hashes.