Building & Launching a Client Website with Claude Code

Five principles this whole guide rests on

Read these once. Every phase below is an application of one of them.

Find the real brief

Written briefs go stale. The decisions that actually govern the build are usually in a meeting recording that nobody re-read.

Gather every source, then rank them

Audit the existing site before you replace it

Do this while you still have it. Once DNS moves, it's gone.

# every page the old site links to
curl -s -L "https://CLIENT.com/" | grep -oE 'href="[^"]+"' | sort -u

# pull each page so you have the real copy offline
for p in about services contact; do
  curl -s -L "https://CLIENT.com/$p" -o "live/$p.html"; done

# how does their booking / phone / form actually work?
grep -rioE 'href="[^"]*(book|appoint|schedule)[^"]*"' live/

Write down the scope before building

Produce an explicit keep / rebuild / drop list and get it confirmed. Ambiguity here becomes rework later. Note anything the client said they want to be able to maintain themselves — that's a design constraint, not a nice-to-have.

Get access — and learn what it can't do

What to request, in priority order

Create your own admin user — never work inside the client's personal login. When the previous contractor leaves, their access is revoked without touching yours.

# verify the application password works
curl -u "USER:APP PASSWORD" \
  "https://SITE/wp-json/wp/v2/users/me?context=edit"

Store credentials outside the repo

d:\.CLIENT.env   # never inside a git working tree

SSH_HOST=...
SSH_PORT=65002
SSH_USER=...
SSH_PASS=...
WP_URL=https://...
WP_USER=...
WP_APP_PASSWORD=...

Sanity-check the environment immediately

# versions and what's installed - shapes every later decision
GET /wp-json/wp/v2/plugins
GET /wp-json/wp/v2/themes
GET /wp-json/wp/v2/pages?per_page=100&status=any&context=edit
GET /wp-json/                # every available namespace

That last call is worth reading properly. Plugins expose their own namespaces, and they're often the only writable route to a setting — the theme switch and the redirect engine in this guide were both found that way.

Back up before you touch anything

You're usually inheriting a live client site mid-project. Establish a rollback point first — every time, no exceptions.

1. Host-level backup — hPanel → Files → Backups → Create new. Ask the client to do this if you lack panel access.
2. Page data — save each page's builder JSON to disk (_elementor_data via context=edit).
3. Rendered HTML — save the front end of every page, so you can compare design later.
4. Record the DNS — current A records and TTLs. This is your launch-day undo.

Assets: extract, optimise, name, upload

If images are embedded in the page, get them out

Base64 images inside page markup are the single worst thing you can inherit: the page can't be cached, the client can't swap a photo, and the file balloons. On this project Home was 5.2 MB of HTML because 18 photos were welded into it.

# pull every embedded image out to real files
re.finditer(r'data:image/([a-z]+);base64,([A-Za-z0-9+/=]{500,})', html)
# de-duplicate on an md5 of the decoded bytes

Optimise, then upload with real names and alt text

• Resize to ~1800 px on the long edge; quality 82, progressive.
• Name by what it is — burns-house-reception.jpg, never IMG_4471.jpg. The client browses this library.
• Set alt text on every image — accessibility and image search.
• Keep a local media-map.json of slug → id + URL, and build pages from it.

POST /wp-json/wp/v2/media
  Content-Type: image/jpeg
  Content-Disposition: attachment; filename="reception.jpg"
POST /wp-json/wp/v2/media/<id>   { "alt_text": "...", "title": "..." }

Result on this project: 5.11 MB → 3.88 MB, and every photo became swappable by the client in two clicks.

Build pages as code

Elementor stores a page as a JSON tree in post meta. Generate that tree from small composable functions and you get consistency for free — plus the ability to restyle every page at once.

File layout that works

The element shape

{ "id": "<7 hex>",
  "elType": "container" | "widget",
  "widgetType": "heading",        // widgets only
  "settings": { ... },
  "elements": [ ... ] }

Publishing

POST /wp-json/wp/v2/pages
{
  "title": "Home", "slug": "home", "status": "publish",
  "template": "elementor_canvas",
  "meta": {
    "_elementor_edit_mode": "builder",
    "_elementor_template_type": "wp-post",
    "_elementor_data": "<the JSON tree, stringified>"
  }
}

Use only widgets the client can edit

Native widgets — Heading, Text Editor, Image, Button, Icon List, Video, Star Rating. Never an HTML widget for content. The one defensible exception is a small stylesheet for markup a plugin renders that the builder cannot reach (a contact form). Comment it clearly and keep content out of it.

Traps that cost hours

Every one of these failed silently — the publish returned 200 and the page looked broken for a reason that wasn't visible in the response.

1. Containers need an explicit type

Omit it and the builder emits a truncated CSS class, every flex custom property is dropped, and your rows stack vertically with no error anywhere.

settings["container_type"] = "flex"   # set this on EVERY container

2. Widget styles use different keys to container styles

This one bit twice. On a widget, background, padding, border and width only apply under underscore-prefixed keys. The unprefixed versions are container-only and are ignored without warning.

_background_background, _background_color, _padding,
_border_border, _border_width, _border_color,
_element_width, _element_custom_width

Symptom: white label text on a background that never rendered — present in the DOM, invisible on screen.

3. Percentage widths need a full-width parent

A "boxed" container is always 100% wide with a centred inner wrapper, so child width percentages are silently ignored. Set content_width: "full" on any row whose children carry widths — and leave room for the gap (4-up ≈ 23.5%, 3-up ≈ 32%, 2-up ≈ 49%) or the row wraps.

4. Background overlays are multiplied by a separate opacity

Overlay colour alpha is multiplied by an overlay opacity that defaults to 0.5, so your 70% scrim renders at 35% and text over photos is unreadable. Pin it:

background_overlay_opacity = 1

5. Pages are effectively write-once over the API

After a page renders once, the builder serves a cached element render. There is no REST route to clear it, and Application Passwords can't reach the admin tool that would.

6. Not every plugin's settings are writable

Some plugins return 200 OK, echo your change back, and never persist it. Always read the value back in a separate request before believing it.

7. The host's theme can silently hide your entire site

On this project the pre-installed host theme injected a CSS rule setting opacity: 0 on ~73 containers, awaiting a scroll-animation library that was never loaded. Every section below the hero was permanently invisible to real visitors, while looking fine in the editor.

8. Page template controls the theme chrome

If your design includes its own header and footer, set the page template to the builder's Canvas option. Otherwise the theme's own header and footer render as well and you get a duplicate.

9. Cache is rarely the cause — check before blaming it

Read the response headers. If the CDN or page cache reports a miss and you're still seeing stale content, the problem is upstream in the application, not the cache. Chasing the cache wastes hours.

curl -sI "https://SITE/?cb=$(date +%s)" | grep -iE 'cache|age'

10. Beware the shared object in a page-generator

A module-level element reused across pages gives every page identical element ids. Make repeated blocks functions, so each call mints fresh ids.

11. Plugins with a setup wizard need it running first

Some plugins create their database tables in an admin wizard. Their API returns confusing errors until it's done. Look for a setup endpoint and drive it:

POST /wp-json/redirection/v1/plugin/data   { }   # repeat until done
POST /wp-json/redirection/v1/plugin/finish { }

Quick reference — symptom → cause

Verify like you don't trust yourself

You cannot see the site you're building. Build a harness that looks at it for you, and make it report facts rather than impressions.

Screenshot properly, or you'll chase ghosts

await p.evaluate(() =>
  document.querySelectorAll('img').forEach(i => i.removeAttribute('loading')));
const H = await p.evaluate(() => document.documentElement.scrollHeight);
await p.setViewportSize({ width: 1440, height: Math.min(H, 12000) });
await p.screenshot({ path: out });   // no fullPage

Assert numbers, not vibes

Every page, at 390 px and 1440 px:

• Horizontal overflow — scrollWidth > innerWidth means broken mobile
• Images loaded — count naturalWidth > 0 against total
• Dead links — count a[href="#"] and a[href=""]
• Widget mix — confirms the page is editable, not one code block
• Page weight — sum the transfer sizes

When something looks wrong, measure it

Don't guess at CSS. Read the computed style of the actual element:

getComputedStyle(el).flexDirection   // is the row actually a row?
getComputedStyle(el).opacity         // is it hidden rather than missing?
el.getBoundingClientRect()           // is it sized as expected?

This is how the invisible-label and hidden-section bugs were both found in minutes after guessing had failed for far longer.

Check every link, every time

for l in / /about/ /contact/ ...; do
  printf "%-24s %s\n" "$l" "$(curl -s -o /dev/null -w '%{http_code}' -L "$U$l")"
done

Forms, and the email problem nobody checks

A contact form that says "message sent" while delivering nothing is the worst defect a small-business site can ship. For a practice or trade, every lost enquiry is lost revenue — and nobody finds out for weeks.

Always do both of these

Test delivery properly

1. Point the recipient at your own inbox first — never test into the client's.
2. Submit a real message through the form.
3. Confirm it arrived, including spam and trash. A "sent" status proves nothing.
4. Only then set the client's address and submit one final confirming test.

Check the domain's mail policy before choosing a From address

nslookup -type=TXT _dmarc.CLIENT.com
nslookup -type=TXT CLIENT.com          # SPF

A DMARC policy of p=reject means any mail claiming to be from that domain without proper authentication is discarded outright. This client had exactly that. Send from an address you can authenticate, and set Reply-To to the enquirer so replies still work.

Protect the rankings you inherited

A rebuild can wipe out years of search visibility in a single afternoon. For a local business, that traffic is most of their new customers. These steps are not optional extras.

1. Redirect every old URL — before cutover

Consolidating twenty thin service pages into three is good for users. Letting those twenty URLs 404 is not. Map every old path to its closest new page and serve a 301, which passes the accumulated ranking value across.

POST /wp-json/redirection/v1/redirect
{ "url": "/old-page", "match_type": "url", "action_type": "url",
  "action_code": 301, "group_id": 1,
  "action_data": { "url": "/new-page/" } }

Then test every single one — a redirect that exists in the database but doesn't fire is worth nothing.

2. Structured data for local businesses

An SEO plugin gives you Open Graph, canonicals and page schema for free, but usually not a business entity. Hand-write one JSON-LD block and inject it site-wide: exact name, address and phone, opening hours, services, areas served, and a booking action. This is the main on-page lever for the local map results.

3. Titles and descriptions

Default titles are weak and descriptions are usually empty. If the SEO plugin's fields aren't API-writable, write the text yourself and hand it over as a paste-in list — ten pages is twenty minutes of someone's time and worth doing before launch.

4. Analytics and Search Console

• Check what's on the old site — legacy analytics properties are often long dead.
• Install a current analytics tag on the new site.
• After launch: verify the domain in Search Console and submit /wp-sitemap.xml.
• Confirm the business listing points at the new site.

Go live without killing their email

Audit DNS first

nslookup -type=NS  CLIENT.com     # who controls DNS
nslookup -type=A   CLIENT.com     # current web host (your rollback)
nslookup -type=MX  CLIENT.com     # their email provider
nslookup -type=TXT CLIENT.com     # SPF + verification
nslookup -type=TXT _dmarc.CLIENT.com
nslookup -type=ANY autodiscover.CLIENT.com

Write the current A record down. That's your undo.

Change exactly two records

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Host: CLIENT.com" "http://<candidate-ip>/"

Immediately after the change

1. Confirm the domain resolves to the new IP.
2. Check robots.txt — the staging block must be gone.
3. Update the site URL in WordPress from the temporary domain to the real one.
4. Confirm SSL has issued and http → https redirects. Allow up to an hour; a certificate warning in the first few minutes is normal — don't revert.
5. Re-test every redirect on the live domain.
6. Re-check MX and autodiscover, and have the client send and receive a test email.
7. Submit the sitemap to Search Console.

Launch day checklist

Tick each box as you go — your progress is saved on this device. Every line is something that has gone wrong on a real project.

Quick reference

Endpoints used most

Commands worth memorising

# status + final URL after redirects
curl -s -o /dev/null -w '%{http_code} %{url_effective}\n' -L "$URL"

# is a cache serving this?
curl -sI "$URL?cb=$(date +%s)" | grep -iE 'cache|age'

# what does the page actually contain?
curl -s -L "$URL" | grep -o 'data-widget_type="[^"]*"' | sort | uniq -c

# does this IP serve the domain?
curl -s -o /dev/null -w '%{http_code}\n' -H "Host: CLIENT.com" "http://IP/"

Time allocation that reflects reality

If verification looks disproportionate, note that on this project it caught: a permanently invisible site, a form that silently discarded every enquiry, a search-engine block that would have prevented indexing, and a DNS change that would have taken down the client's email.