Website building

Illustrative output #

Fictional records, to show the shape of what comes back.

PR #12  Website: home, about and pricing from the brand guide        merged after review

app:website   deployed
  https://website-1a2b3c4d.app.getcargo.run/pricing/    Pricing | Fabrikam
  www.fabrikam.example                                  pending: _cargo-verify not resolved

DNS is hosted elsewhere, so infra/domains/website.ts was deleted. Add at the provider:
  TXT    _cargo-verify.www   cargo-verify=9c1e4a…
  CNAME  _3f2a91.www         _7b0c44.acm-validations.aws
  CNAME  www                 d1x2y3z4.cloudfront.net
  apex   fabrikam.example  → https://www.fabrikam.example   (provider redirect)

Once the TXT resolves, www.fabrikam.example serves the reviewed pages with their own canonical URLs, and the next change to the site is another pull request.

Done when #

• node --import tsx evals/contract.mjs passes: one app in the website_building_apps folder with a www hostname and a static-export build, and either no domain or an adopted domain whose dnsRecords holds the app’s domainRecords and whose apex forwards to www
• npm ci && npm run check && npm run build in the app writes dist/index.html, dist/about/index.html, dist/robots.txt and dist/sitemap.xml, each page with its own title, description and canonical in the initial HTML
• the operator reviewed the local preview: every changed page at 1440 and 390 pixels wide with no horizontal scroll, reachable by keyboard with visible focus, readable in both themes, with no console errors or failed requests
• the plan’s DNS diff is recorded and every ~ or - in it was approved, or the domain file was deleted
• cargo-ai project plan shows the folder, the app and the domain (or no domain) as an adopt, not a create, and the operator approved it
• the Cargo URL serves /about and /about/ directly, and a missing page returns the site’s not-found page with status 404
• https://www.<domain>/ serves the site in an anonymous session with a valid certificate, the apex redirects to it, and pages carry it as their canonical URL; a pending TXT is reported as pending
• site.json is ready only for approved content, and a content change reaches the site through one reviewed pull request whose plan shows the same app with a new content hash

What it costs #

Each merge is one deployment of a static app; read the workspace’s current hosting usage before the first deploy, and say what you found. Adopting a domain the workspace owns adds no charge. Registering one (register-domain) charges workspace credits once and is not refundable: read the current price and the credit balance before proposing it, and quote both with the plan. A working form adds whatever its backend costs. Nothing in the workspace runs on a schedule; your coding agent’s usage is the rest.

To run the company website as code, build it as a statically exported Next.js app, host it on Cargo and serve it on your own domain, with every change made through a reviewed pull request. This cookbook declares one defineApp with its www hostname and one defineDomain that publishes the DNS records and forwards the apex; nothing else is deployed.

cargo-ai project add cookbook/website-building

What it does #

• Hosts the site. defineApp uploads the Next.js package; Cargo runs its build and serves every page as prerendered HTML at its own URL.
• Serves it on the company’s name. domains: ["www.…"] attaches the hostname. Cargo’s own URL stays noindex; the company domain is the one search engines index.
• Publishes the records, or tells you what to add. With Cargo holding the DNS, defineDomain publishes the app’s domainRecords and forwards the apex to www. With the DNS at another provider, the domain file is deleted and the records are added there.
• Stays reviewable. Content lives in site.json and the pages in app/. A change is a diff, a preview and a plan before it is a deploy.

How it works #

flowchart TD
    pr["pull request<br/>site.json, app/"] --> plan["cargo-ai project plan"]
    plan --> app["defineApp website<br/>next build → dist/"]
    app --> host["www hostname<br/>_cargo-verify TXT"]
    app -->|"domainRecords"| domain["defineDomain<br/>records merged, apex → www"]
    app -.->|"DNS elsewhere"| provider["records added<br/>at the provider"]

1. A pull request changes the content or the pages; the app builds locally to dist/.
2. The plan shows the app’s new content hash; the deploy uploads the package and Cargo builds it and serves each page from the file it exported, <route>/index.html.
3. The hostname is attached on deploy and verified once its _cargo-verify TXT resolves.
4. The domain publishes the TXT, the certificate-validation CNAME and the www CNAME, and forwards the apex to www.

Adds 2 resource kinds plus the folder they file into.

Why a static export #

Cargo Hosting serves files. A static export gives every page real HTML, its own metadata and a URL that works when entered directly, with no server to run. Cargo serves a path from the file the export wrote for it (about/index.html, else about.html), a missing page from 404.html with status 404, and only then the root index.html. trailingSlash: true keeps every link, canonical and sitemap URL on one form, /about/. What needs a server (route handlers, middleware, image optimization, a form that delivers) lives somewhere else and is called from the page.

Why a domain file you might delete #

When Cargo holds the DNS, the file lets one deploy publish everything the hostname needs: dnsRecords is merged into the live zone, so mail and every other record the deploy did not write stay put, and the plan prints the diff record by record. Most existing company domains keep their DNS at a provider, so for them the file goes and the three records are added by hand.

Placeholders (edit before deploy) #

1. Hostname: infra/apps/website.ts: domains, always the www host.
2. Domain: infra/domains/website.ts: the name and the redirect, or delete the file.
3. Content: infra/apps/website/site.json: approved company facts, canonicalUrl set to https://www.<domain>/, status: "ready" only after review.

What it does not do #

It does not deploy without a reviewed plan, buy a domain without an approved plan line, touch a zone that carries mail, connect a form to a backend nobody chose, or publish a draft.