Webbo3 Level 2 · JavaScript Development · Day 18 of 20

Shipping It

Getting your project off your laptop and onto a URL you can send to somebody who has never met you.

"It works on my laptop" is not a finished project.

Until somebody else can open it on their own phone, on their own connection, you do not know that it works. You know that it works in the one place where every file is local, every path is right and the network is perfect.

1. Development and Production Are Different Places

Definition

Development is where you build: your own machine. Production is where real people use it: a server with a real address. Code that works in one can fail in the other, because the two places are not the same.

Real-Life Example

A dish you cook perfectly in your own kitchen, with your own pot, your own gas and your own spices. Cook it for a wedding in a hall kitchen you have never seen and something will be different: the pot, the heat, the missing seasoning.

Types: How They Differ

The Bugs That Only Appear in Production, Most Common First

1. A path that works locally and not when served: /css/style.css against css/style.css.
2. A file name whose capitalisation differs, which your laptop forgives and a Linux server does not.
3. A mixed-content block: one asset loaded over http on an https page, which the browser refuses.
4. An API that allowed localhost but not your new domain (CORS, Day 8).

2. Deploying a Static Site

Definition

A static site is files the server hands over exactly as they are: HTML, CSS, JavaScript and images, with no server code running. Deploying is copying those files to a server with a public address. Your projects are static, which is the easiest thing in the world to host.

Real-Life Example

Printing flyers is building. Pinning them on the notice board at the bus stop is deploying: the same paper, now where strangers can see it.

Types: Three Free Hosts

1
2
3
4
5
6
7
8
9

# Commit and push your finished project
git add .
git commit -m "Add README and deploy configuration"
git push

# Then on GitHub: Settings -> Pages -> Source: Deploy from a branch
#   Branch: main, folder: / (root) -> Save
# Within a minute or two the site is live at:
#   https://<your-username>.github.io/<repository-name>/

Replace <your-username> and <repository-name> with your own. Pages always serves over https.

The First Deploy Is Nearly Always Broken the Same Way

A blank page with 404 errors in the console means your paths are absolute. A path starting with / means "from the root of the domain". On GitHub Pages the root of the domain is not your project folder, because your project lives one folder down, under its repository name.

new URL(path, pageAddress) works out where a path points from a given page, using the same rules the browser uses when it reads your <link> and <script> tags.

1
2
3
4
5
6
7

// Your page, as GitHub Pages serves it
const page = 'https://chidinma.github.io/job-tracker/index.html';

// Where the browser will look for each way of writing the path
console.log('/css/style.css  ->', new URL('/css/style.css', page).href);
console.log('css/style.css   ->', new URL('css/style.css', page).href);
console.log('./js/app.js     ->', new URL('./js/app.js', page).href);

➜ webbo3 node app.js
/css/style.css  -> https://chidinma.github.io/css/style.css
css/style.css   -> https://chidinma.github.io/job-tracker/css/style.css
./js/app.js     -> https://chidinma.github.io/job-tracker/js/app.js

The absolute path lost /job-tracker and points at a file that does not exist. The relative paths stay inside your project. On localhost the two happen to point at the same place, which is why the bug hides until you deploy.

Capitalisation

Windows and macOS usually treat Logo.PNG and logo.png as the same file. The Linux servers that host your site do not. ls below asks a Linux filesystem for the file by the name your HTML uses.

1
2
3
4
5
6
7
8
9
10

mkdir -p site/images && cd site

# The file as it came off the camera
touch images/Logo.PNG

# The name your HTML asks for
ls images/logo.png

# The name that is really there
ls images/

ls: cannot access 'images/logo.png': No such file or directory
Logo.PNG

Before You Call the Deploy Done

• Check every path is relative, including images and imports.
• Check the capitalisation of every file name against the HTML that uses it.
• Open the deployed site on your phone, on mobile data, not on your wifi.
• Open the Console on the deployed site. It is not the same as your local one.

3. What a Build Step Is

Definition

A build step is a program that turns the files you write into the files you deploy. You have not needed one yet. It is worth knowing what it does before Level 3 hands you one.

Real-Life Example

A publisher takes an author's manuscript, with its notes and crossings-out, and prints a neat, compact book. The story is the same; the form is made for readers, not for the author.

Types: The Stages

The hash is a short fingerprint of the file's contents: change one character and it changes. sha256sum prints such a fingerprint, and cut -c1-6 keeps the first six characters.

1
2
3
4
5
6

echo "console.log('version 1');" > app.js
echo "app.$(sha256sum app.js | cut -c1-6).js"

# Change one character and build again
echo "console.log('version 2');" > app.js
echo "app.$(sha256sum app.js | cut -c1-6).js"

app.c42b99.js
app.f8e58e.js

4. Configuration That Changes Between Places

Definition

Configuration is the values that differ between development and production, such as the API address, or whether to print debug logs. They belong in one file, not scattered through the code.

Real-Life Example

A phone that switches to your home wifi at home and to mobile data outside. You do not re-set it every time you walk through the door; it looks at where it is and picks.

window.location.hostname is the domain the page was loaded from: 'localhost' on your machine, and your real domain once deployed. The config looks at it and picks.

1
2
3
4
5
6
7
8
9
10
11
12
13

// Pick settings from the domain the page is running on
function configFor(hostname) {
  const isLocal = hostname === 'localhost' || hostname === '127.0.0.1';

  if (isLocal) {
    return { apiBase: 'http://localhost:3000', pageSize: 10, debug: true };
  }
  return { apiBase: 'https://api.webbo3.com', pageSize: 10, debug: false };
}

// The same code, in both places
console.log('on your laptop:', configFor('localhost'));
console.log('deployed:      ', configFor('chidinma.github.io'));

➜ webbo3 node app.js
on your laptop: { apiBase: 'http://localhost:3000', pageSize: 10, debug: true }
deployed:       { apiBase: 'https://api.webbo3.com', pageSize: 10, debug: false }

In the real project this lives in config.js and exports the result for the current page. Nothing else in your codebase contains a URL: when the API moves you change one line.

1

<p id="api"></p>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// Pick settings from the domain the page is running on
function configFor(hostname) {
  const isLocal = hostname === 'localhost' || hostname === '127.0.0.1';

  if (isLocal) {
    return { apiBase: 'http://localhost:3000', pageSize: 10, debug: true };
  }
  return { apiBase: 'https://api.webbo3.com', pageSize: 10, debug: false };
}

const config = configFor(window.location.hostname);
document.querySelector('#api').textContent = `Talking to ${config.apiBase}`;

// Debug logs appear locally and never in production
if (config.debug) {
  console.log('debug: page loaded from', window.location.hostname);
}

debug: page loaded from localhost

5. The README

Definition

The README is the page GitHub shows under your code. It is the part students skip and employers read first, and often the only thing somebody looks at before deciding whether to open your code.

Real-Life Example

The back cover of a book in a bookshop. Nobody reads chapter one to decide whether to buy; they read the back.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# Job Application Tracker

Track job applications and see at a glance which ones need chasing.

**Live:** https://chidinma.github.io/job-tracker/

![Screenshot of the tracker](docs/screenshot.png)

## Why I built it
I was losing track of which applications I had heard back from. Everything
lived in my head and in a WhatsApp message to myself.

## Features
- Add, edit and delete applications
- Filter by status, search by company
- Flags anything still "applied" after 14 days
- Saves in the browser, so it survives a refresh
- Works with a keyboard only; Lighthouse accessibility 100

## Running it locally
    git clone https://github.com/chidinma/job-tracker.git
    cd job-tracker
    npx serve .

It needs a server rather than opening the file directly, because it uses
ES modules.

## Built with
Vanilla JavaScript, no frameworks. ES modules, localStorage, CSS Grid.

## What I would do next
- Move storage to a backend so it syncs between devices
- Export to CSV
- Email reminders, which need a server

## What is deliberately out of scope
No accounts, no backend, no file uploads. One person, one browser.

GitHub renders this as the front page of the repository. Lines indented by four spaces show as a code block.

• The live link goes at the top. Most readers will click it and never scroll.
• A screenshot. Somebody scrolling twenty repositories will look at a picture and not read a paragraph.
• "What I would do next" shows you know what is missing, which reads as judgement rather than as a gap.

6. Lighthouse Before You Call It Done

Definition

Lighthouse is a checker built into Chrome DevTools that scores a page on performance, accessibility, best practices and SEO, and lists what to fix. Open the Lighthouse tab, tick all four categories, and run it against your deployed URL, not localhost.

Real-Life Example

A roadworthiness test for a car. It does not tell you whether the car is beautiful; it tells you which specific things will fail on the road.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<head>
  <meta charset="utf-8">
  <!-- Fit the page to the phone's width -->
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- What search engines and browser tabs show -->
  <title>Job Application Tracker</title>
  <meta name="description" content="Track job applications and see which ones need chasing.">

  <!-- What WhatsApp, LinkedIn and Slack show when the link is pasted -->
  <meta property="og:title" content="Job Application Tracker">
  <meta property="og:description" content="See at a glance which applications need chasing.">
  <meta property="og:image" content="https://chidinma.github.io/job-tracker/docs/screenshot.png">
  <meta property="og:url" content="https://chidinma.github.io/job-tracker/">
</head>

og:image must be a full https address, not a relative path, because the app showing the card reads it from outside your site.

Do This Now

1. Deploy your Day 15 project and get a real https URL.
2. Fix the first deploy. Expect broken paths and at least one capitalisation problem.
3. Open it on your phone, on mobile data, and use it properly for two minutes.
4. Write the README to the shape above, screenshot included.
5. Run Lighthouse on the deployed URL. Get Accessibility above 95 and fix every console error.
6. Send the link to somebody who has never seen it and watch them use it without helping. Write down every moment they hesitate.

Checkpoint

Tomorrow, Day 19: turning four projects into something an employer can read in ninety seconds.