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   Routing: static
  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 mailbox check is recorded, or the domain file was deleted
• cargo-ai cdk plan shows the folder, the app and the domain (or no domain) as an adopt, not a create, and the operator approved it
• the deploy log says Routing: static, and the Cargo URL serves /about and /about/ directly
• 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.

The company website, hosted by Cargo and served on the company’s own domain. A statically exported Next.js app, the www hostname on it, and a domain that publishes its records and forwards the apex. Every change is a pull request your coding agent writes and someone reviews; nothing else is deployed.

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 cdk plan"]
    plan --> app["defineApp website<br/>next build → dist/"]
    app --> host["www hostname<br/>_cargo-verify TXT"]
    app -->|"domainRecords"| domain["defineDomain<br/>whole zone, 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, routing statically because pages are exported as <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. trailingSlash: true writes each page as <route>/index.html, which is what Cargo’s build detects to route statically; without it, /about serves the home page. 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 #

dnsRecords is the whole zone. That is what lets one deploy publish everything the hostname needs, and it is also why the file is dangerous on the wrong domain: a zone Cargo mailboxes send from loses its mail records. Most existing company domains keep their DNS at a provider, so for them the file goes and the three records are added by hand. A dedicated domain held by Cargo keeps the file.

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.