To build a website with AI, you describe the site to a coding agent (Claude Code, Codex, Gemini CLI and the like) in a short, concrete brief; the agent sets up the project and writes the pages, you review it in the browser and ask for fixes, and finally you deploy it to Vercel, Netlify or Cloudflare Pages. For a marketing site or portfolio that can take an afternoon. What really makes the difference is the right stack, a good first prompt and a checklist before launch.
This guide walks through the whole path from an empty folder to a live site: which stack to pick and why, what to put in the first prompt, how to tighten the design with screenshots, mobile and accessibility checks, SEO basics, a contact form, a domain and deployment. At the end there’s a list of the mistakes AI tends to make and a few security rules.
First decision: AI site builder or coding agent?
There are two paths, and both count as “building a website with AI”.
AI website builders (the AI features in platforms like Wix, Framer or Webflow, or browser-based app generators) turn a sentence into a live page in minutes. They’re fast and hosting is included. The trade-off: the code mostly stays on the platform, you pay monthly, you can’t do what the platform doesn’t allow, and moving away is hard.
Coding agents run on your machine, in your folder. They write files, run npm install, read errors and fix them. It takes more steps; in return you end up with a normal code repository. You can host it on free tiers, hand it to any developer and add any library you like.
| Site builder | Coding agent | |
|---|---|---|
| Time to first result | Minutes | An hour or two |
| Who owns the code | Mostly the platform | You |
| Hosting | Theirs, on a paid plan | Anywhere, often a free tier |
| Custom needs | As far as the platform allows | As far as code can go |
| Learning curve | Very low | Some comfort with a terminal and git |
This guide covers the second path: vibe coding a site, where the agent writes the code and you steer the result. If you haven’t picked an agent yet, see the best AI coding CLI tools.
1. Install the basics
You need three things:
- Node.js (the LTS release). Astro and Next.js run on it.
- Git and a GitHub account. It’s your undo button and the easiest way to connect to hosting.
- A coding agent, for example:
npm install -g @anthropic-ai/claude-code # Claude Code
npm install -g @openai/codex # Codex
Then create an empty folder, initialise git and start the agent there:
mkdir cafe-site && cd cafe-site
git init
claude
Starting git first matters: when the agent breaks something, git diff shows what changed and git checkout . takes it back.
2. Pick a stack: Astro, Next.js or plain HTML
The agent can write anything, but without direction it may grab the heaviest option that comes to mind. Roughly:
- Plain HTML + CSS: a one-page invitation, a product teaser, a “coming soon” page. No build step, no dependencies, runs anywhere.
- Astro: marketing sites, company sites, blogs, portfolios. Pages render to plain HTML by default, so they’re fast and SEO-friendly, and blog posts live as Markdown files. This is my default for content sites.
- Next.js: app-heavy work such as user accounts, dashboards, a database or payments. Overkill for a brochure site on its own.
If you’re unsure, start with Astro. It can still handle a contact form or a small API later.
3. The first prompt, with design direction
The most common mistake is typing “make me a cafe website”. You get the template everyone has seen: purple gradient, centred headline, three cards. Put content, structure and design direction in the first message:
Build a marketing site with Astro for a neighbourhood cafe called "Piggy Bank Coffee".
Pages: Home, Menu, About, Contact.
Home: a large photo area (placeholder for now), a one-line tagline,
a "See the menu" button, opening hours, address and a map link.
Menu: a list grouped by category (coffee, pastries, breakfast), prices in USD.
Design direction: warm and simple. Cream background (#f6f0e6), dark brown text (#2b1d14),
terracotta accent (#c2603a). Serif for headings, a readable sans-serif for body text
(Google Fonts). Generous whitespace, small corner radius, no shadows, no gradients.
Mobile first.
Rules:
- No Tailwind; use plain CSS and CSS custom properties.
- html lang="en".
- Every page gets a unique <title> and meta description.
- When done, start `npm run dev` and list the files you created.
Why it works: you gave concrete colours and fonts, a “don’t” list (gradients, shadows), and the page structure and content. The less the agent has to guess, the more the result looks like what you had in mind. You can also attach a screenshot of a site you like: “Match the spacing and typography feel of this site; don’t copy its colours or content.”
4. Iterate on the design with screenshots
Once the agent runs npm run dev, the site usually opens at http://localhost:4321 (Astro) or http://localhost:3000 (Next.js). From here it’s a loop:
- Open the page, take a screenshot of what you don’t like.
- Give the image to the agent (most CLIs accept images by drag-and-drop or paste) and ask it to fix one thing.
- Check the result; if it’s good, commit.
The attached image is the home page on mobile. Three problems:
1. The tagline doesn't fit; the line breaks look bad.
2. The "See the menu" button touches the screen edge.
3. The opening-hours table overflows horizontally.
Fix only these. Don't change anything else.
“Don’t change anything else” is small but important: agents like to “improve” neighbouring components while fixing one. After each good step run git add -A && git commit -m "...", so if the next request breaks things you can go back to the last good state.
If you want the agent to drive a browser itself, add a Playwright MCP server; it can open the page, take its own screenshots and fix what it sees.
5. Mobile and accessibility checks
AI-built sites often look fine on desktop and fall apart on a phone. Before launch:
- Turn on device mode in your browser’s dev tools and check at least 375 px (phone), 768 px (tablet) and 1440 px (desktop). A horizontal scrollbar means something overflows.
- Run Lighthouse from Chrome DevTools. It scores Performance, Accessibility, Best Practices and SEO and lists concrete warnings.
- Navigate the page with only the keyboard (Tab, Enter). Can you reach every link and button, and can you see where the focus is?
Hand the warnings straight to the agent:
The Lighthouse accessibility report says: [paste the warnings].
Fix them. Also check that every image has meaningful alt text, every form field
has a label, text/background contrast meets WCAG AA and keyboard focus is visible.
6. SEO basics
The agent knows all of this but often leaves it half done unless you ask. Checklist:
- A unique
<title>per page (around 60 characters) and a meta description (around 150–160 characters). - One
<h1>per page with a sensible<h2>/<h3>order under it. - sitemap.xml and robots.txt. In Astro the
@astrojs/sitemapintegration generates the sitemap; it needs thesiteURL set inastro.config. - Open Graph tags (
og:title,og:description,og:image); link previews in chat apps and social media come from these. - A canonical URL and the right
langattribute. - For a local business, write address, phone and opening hours as text (not baked into an image) and optionally add
LocalBusinessstructured data.
Run an SEO audit: list every page's title and meta description and fix
any that are missing or too long. Add @astrojs/sitemap, create robots.txt,
put Open Graph tags in the shared layout. Summarise the changes.
7. A contact form
A static site has no server of its own, so form submissions need somewhere to go. Three reasonable options:
- A form service: something like Formspree, or Netlify Forms if you host on Netlify. The form posts to the service and you get an email. The easiest route.
- A serverless function: a small API route in Astro or Next.js receives the form and sends it through an email API. The API key lives only on the server, in an environment variable.
- Just a
mailto:link: no form, no problem. Often enough for a small business.
Whichever you choose, have the agent add server-side validation of required fields, a basic spam guard (a hidden honeypot field or the service’s captcha) and a clear “message received” state. Since you’re collecting personal data, add a short privacy notice too.
8. Domain and deployment
Push the site to GitHub first:
git remote add origin git@github.com:you/cafe-site.git
git push -u origin main
Then connect one of the three common hosts. All of them rebuild and deploy on every push once the repo is connected, and can give you preview URLs for branches or pull requests:
- Vercel: made by the Next.js team, handles Astro fine too. CLI:
npx vercelfor a preview,npx vercel --prodfor production. - Netlify: very established for static sites, with built-in forms. CLI:
npx netlify deploy --prod. - Cloudflare Pages: hosts on Cloudflare’s network; handy if your domain is already on Cloudflare. CLI:
npx wrangler pages deploy dist.
Build settings are usually detected automatically: for Astro the build command is npm run build and the output folder is dist. Add your domain in the host’s dashboard, then enter the DNS record it gives you (usually an A or CNAME record) at your registrar. HTTPS certificates are issued automatically.
After launch, add the site to Google Search Console and submit your sitemap URL so Google finds it sooner.
What the AI gets wrong
- Template look. Without design direction, everything gets the same gradient and the same card grid. Give colours, fonts and a “don’t” list.
- Made-up content. Agents happily write fake testimonials, invented numbers (“10,000+ happy customers”) and awards that don’t exist. Read every line and delete what isn’t true.
- Images with licensing risk. It may hotlink random images from the web. Use your own photos or properly licensed ones.
- Unneeded dependencies. A big animation or UI library for a simple menu. Add the rule “ask before adding a new package”.
- Broken links and empty hrefs. Search for buttons left as
href="#"and click every link before launch. - Desktop-only testing. The agent usually checks only the default window size; ask for mobile explicitly.
- Declaring victory. An agent may call it done while the build fails. Run
npm run buildyourself before deploying; it must finish without errors.
Security
Even a brochure site has a few rules:
- Keep secrets in a
.envfile and make sure.envis in.gitignore. On your host, enter the same values as environment variables in the dashboard. - Never paste API keys into the chat. Tell the agent “the key is in
.envasRESEND_API_KEY”, not the value itself. Chat history is stored somewhere too. - No secrets in client code. Any key shipped in browser JavaScript is a key anyone can read. Email and payment keys belong on the server only.
- Read what the agent runs. Don’t auto-approve commands like
rm -rf,curl ... | sh, global installs orgit push --force. - Look at the diff before you commit.
git diffis the easiest way to catch both bugs and a secret that slipped in.
Doing it with AgentVera
Everything above works with one terminal and one browser. A few things make it smoother in my own workflow, and I use them in AgentVera:
- Parallel agents in separate worktrees. For example, a Claude Code agent works on content and SEO while a Codex agent works on the UI; each sits in its own git worktree, so neither overwrites the other. All of them show up in one workspace grid.
- Preview environments. Each worktree’s dev server gets its own address; preview environments can capture pages at mobile, tablet and desktop sizes and compare them pixel by pixel with an earlier baseline.
- Agent browser. Agents use a separate-profile Chrome through Playwright, and you watch what they do live in the agent browser.
- Review and token tracking. When a turn ends, code review has a second model read what the agent wrote, and each agent’s token use is visible. You still read the diff before merging.
- Vercel. If the project is linked to Vercel, the Vercel tab shows deployments and build logs, and you can hand a failing build to an agent.
None of this is required; it just makes it easier to keep track once you work with more than one agent. For the method itself, see parallel coding agents.
Quick checklist
- Stack chosen (Astro for a content site)
- First prompt covers pages, content, colours, fonts and a “don’t” list
- A commit after every good step
- Checked at 375, 768 and 1440 px; Lighthouse warnings fixed
- Every page has a title, meta description and one h1; sitemap and robots.txt exist
- No invented testimonials, numbers or images left
- The form works, with a spam guard and a privacy notice
-
.envisn’t in git; secrets only on the server -
npm run buildpasses; the site is live with your domain and HTTPS
Wrapping up
Building a website with AI is now less about writing code and more about describing well and checking carefully. Pick the right stack, put design direction in the first prompt, move in small steps and commit each one, and run mobile, accessibility and SEO checks before launch. The agent writes fast; you’re still the one who decides what’s right.