AI coding assistants are good at writing web pages. They're also good at quietly breaking things: a link to a page that doesn't exist, a missing description, a claim you never made, a deploy that overwrites something. This walkthrough builds a small business website with Claude Code and vagejs, a free, open-source static site generator that checks every page before it goes live.
It works the same with Cursor, Codex, Copilot or Gemini CLI. You need Node.js 22.12 or newer.
1. Create the site
npm create vagejs@latest my-site
It asks "Install and start the site now?". Press Enter, and your new site opens in the browser. Pages are Markdown files in src/pages/; src/pages/about.md becomes /about/.
The new folder also contains AGENTS.md. That file tells your AI assistant the commands, the folder layout and the rules: run npm run check after every change and fix every error, never add pages or links to other websites you didn't ask for, and only publish with your approval.
2. Ask for the pages
Open the folder in Claude Code and describe what you want, with the real facts. Don't have a prompt yet? The prompt builder writes one from a few answers. Here's a short version:
Read AGENTS.md. This site is for Rosa's Bakery, a bakery in Indiranagar,
Bengaluru, that bakes sourdough bread and pastries.
Create Home, About and Contact pages, and add them to the main menu.
Facts you can use: open Tuesday to Sunday, 8am to 6pm.
Don't invent prices, reviews or anything else: ask me.
Then run npm run check until it reports 0 errors.
The assistant writes plain text files you can read and edit yourself, like this:
---
title: "About Rosa's Bakery"
description: "A neighbourhood bakery in Indiranagar baking sourdough and pastries, Tuesday to Sunday."
---
# About us
We bake sourdough bread and pastries every morning...
3. Let the check catch the mistakes
Here's the part that matters. Say the assistant links the home page to /menu/, a page that doesn't exist. npm run check stops it:
error link-broken / (src/pages/index.md)
Link to "/menu/" does not match any page or file.
It names the file and the problem, so the assistant fixes it before you ever see the broken link. The same check covers missing titles and descriptions, structured data, image alt text, links to websites you haven't approved, and more. It ends with:
Checked 5 page(s): 0 error(s), 0 warning(s).
4. Review it yourself
npm run dev shows the site with live reload. It also prints an editor: address: a local editor with a form for each page and a live preview, for when you'd rather fix a sentence yourself than ask the assistant. It only runs on your computer and is never part of the published site.
5. Publish, after you say yes
npx vage deploy
It shows a plan first: what gets committed, where it gets pushed (never force-pushed), and how it checks the result. Then it publishes to GitHub Pages and reports success only when your site actually answers. Cloudflare and Netlify work the same way.
A free GitHub Pages address like you.github.io/my-site works too: set site: "https://you.github.io/my-site" in vage.config.ts, and vagejs adds the /my-site part to every link. Here's a live example.
What you end up with
- Plain HTML pages with no JavaScript, unless you add some
- A sitemap, robots.txt and llms.txt generated from the pages that actually exist
- Search titles, descriptions, social previews and structured data on every page
- Files you own, in your own git repository
Where it doesn't fit
vagejs builds static sites: company sites, docs, blogs, portfolios, landing pages. If you need user accounts, a shopping cart or data that changes per visitor, use an application framework instead.
vagejs is MIT licensed and free. The docs are at vagejs.com/docs and the code is on GitHub. It's young, so feedback on what breaks is very welcome.
Top comments (0)