Guided journey

Build and Ship Your First Web App With AI

A project-based journey for AI builders: scope a small app, write a spec, build one feature end to end, and deploy it to a public URL in two weekends.

Beginner2 weekends8 milestones16 min read
You walk away with

A small web app running at a public URL that a friend can open on their phone, plus the repo it lives in.

Assume you have

A computer you can install software on, Node.js or Python, and an AI coding assistant (Claude, Copilot, Cursor, Codex). No prior programming experience.

Stack used

Node.js + SQLite, deployed to a free host. Swap in Python and Postgres if your agent prefers them — the checkpoints are identical.

The project

You are building one small tool you personally want to use. The worked example is a link saver — paste a URL, give it a title, see the list, click through. It is deliberately boring: one page, one form, one list, one table. Boring is the point. The goal of this journey is to finish something real, not to start something impressive.

By the end you will have: a public URL you can send to a friend, a Git repository you understand well enough to change next week, and the loop — spec, generate, run, check, repeat — that every later project reuses.

Before you start

Set up four things so you spend your time building, not installing:

  1. Your AI coding assistant, open in the project folder. If you have not picked one, start with the comparison in How to Choose an AI Coding Tool.
  2. The runtime for the stack you will use — Node.js from nodejs.org or Python from python.org.
  3. Git, plus a free account on GitHub. You will push on day two.
  4. A free hosting account. Cloudflare, Render, Railway, and Fly.io all have usable free tiers; see How to Launch Free Infrastructure on AWS, GCP, or Azure for the trade-offs.

One rule before you prompt a single line: do not skip the checkpoints. A vibe coder’s only defence against a demo that quietly does not work is running the thing and looking at it. That is what What Is Vibe Coding (and Where Does It Break Down)? calls the failure mode this journey is designed around.

If the first hour feels exciting and the second day feels harder, that is normal. Use How to Stay Motivated When AI Coding Makes Everything Feel Easy to keep progress tied to verified checkpoints, and How to Build a Productive AI Coding Routine to end each session with evidence and a clean next step. As you learn, use How to Build Confidence as a Beginner Using AI Coding Assistants and How to Learn Software Engineering While Building With AI to turn the project into a deliberate learning loop.

Milestone — Scope the project down to one weekend

Build: a one-sentence description of your app and an explicit list of what it will not do.

The single most common reason first projects die is scope. “A social network for runners” is not a weekend; “a page that lists my saved links” is. Write the sentence, then write the non-goals.

Do it

  1. Finish this sentence: “A user can ______, and then ______.” For the link saver: “A user can paste a URL with a title, and then see every saved link in a list.”
  2. Write three non-goals: no accounts, no search, no editing or deleting. Those are the next journey, not this one.
  3. Save both to a file called NOTES.md in your project folder. Your agent will read it.

Done when you can say the app’s job in one breath and you have not added a fourth bullet.

Go deeper: Avoiding AI Tech Debt Before It Starts — why an explicit non-goal list keeps generated code from sprawling.

Milestone — Write a spec your agent can follow

Build: a short spec document that states the goal, the data, and the acceptance criteria.

A prompt is a request; a spec is a contract. With a spec, your assistant generates the same app every session instead of drifting as the conversation grows. This is the difference between spec-driven development and re-explaining your app for the tenth time.

Prompt your agent

Write a spec for the app described in NOTES.md.

Include:
- Goal: one paragraph.
- Data: the Link record and its fields.
- User stories: add a link, view all links.
- Non-goals: the three items in NOTES.md.
- Acceptance criteria: a numbered checklist covering
  adding a valid link, showing it in the list, and reloading
  the page without losing it.
- Out of scope: anything about accounts, editing, or deleting.

Save it as SPEC.md. Do not write application code yet.

Done when SPEC.md exists, lists acceptance criteria you could check by hand, and does not mention login. For the full method, read How to Write a Spec an AI Coding Agent Can Actually Follow.

Milestone — Get a skeleton running on your machine

Build: a local server that returns a page saying hello.

You cannot review code you cannot run. Get to “it starts” before adding features, so every later failure has one obvious cause.

Do it

  1. Ask your agent to scaffold a minimal server from SPEC.md — one route, one HTML page.
  2. Ask it for the exact run commands and add them to NOTES.md.
  3. Run them yourself in a terminal.

Done when http://localhost:#### shows a page in your browser and you started it from a command you typed. If it fails, paste the full error back to your agent — including the command — rather than describing it.

Go deeper: How to Structure a Python or Node.js Project From Scratch — pick a layout now and avoid a rewrite later.

Milestone — Build one feature end to end

Build: the add-a-link form, wired all the way through.

One feature, working end to end, teaches more than five half-features. Build the form, the submit handler, and the redirect — nothing else.

Prompt your agent

Implement the "add a link" user story from SPEC.md.

- A form with a URL field and a title field on the index page.
- A POST handler that validates both fields are non-empty.
- For now, log each accepted link to the console.
- Do not add a database yet.

Show me the files you changed and explain the request
flow from form submit to the console log.

Done when you submit the form, the page comes back, and your terminal shows the parsed link. Open your browser’s developer tools once and confirm the POST request actually left — if the form silently does nothing, that is the bug to fix now.

Go deeper: How to Review AI-Generated Code Like a Senior Engineer — the five-minute review habit to run after every generated diff.

Milestone — Save data so it survives a refresh

Build: persistence. Links still there after a restart.

Right now the app forgets everything when it stops. This milestone adds the storage layer and is where most generated apps quietly break.

Do it

  1. Ask your agent to add the simplest database that fits your stack — SQLite is ideal for this stage.
  2. Have it write the table creation and the insert and select queries.
  3. Restart the server, reload the page, and check the links are still listed.

Done when links survive a full stop and start. Read What Is an ORM (and Should You Use One)? if the generated data-access code looks unfamiliar, and Common Database Mistakes in AI-Generated Apps before you trust it with anything you care about.

Milestone — Put it under version control

Build: a Git repository with a readable history and a README.

Version control is your undo button and the thing you will deploy from. It is not optional, and it takes ten minutes.

Do it

  1. Ask your agent to initialise a repo, add a .gitignore for your stack, and make the first commit.
  2. Ask it to write a README.md with the run instructions from NOTES.md.
  3. Push the repo to GitHub.

Done when your GitHub page shows the code, the README explains how to run it, and no secrets or database files are committed. Follow How to Write a README Your Future Self Will Thank You For and How to Write a Good Git Commit Message.

Milestone — Deploy it to a public URL

Build: the app running on a host, reachable at an https:// address.

A localhost project is a hobby; a URL is a product. Deployment also forces every hidden assumption — ports, environment variables, file paths — into the open.

Do it

  1. Ask your agent which free host matches your stack and what files that host needs.
  2. Move any configuration into environment variables and add an .env.example with dummy values.
  3. Deploy. Open the URL on your phone, on mobile data, not your home Wi-Fi.

Done when the public URL loads, you can add a link from your phone, and reloading shows it. If the deploy fails, the error is almost always a missing environment variable or a wrong start command.

Go deeper: How to Deploy Your First App on Cloudflare for Free, or Deploying AI-Generated Apps to Production for the wider checklist.

Milestone — Hand it to one real user

Build: the feedback that tells you what to fix next.

The final checkpoint is not technical. Watch one person use it. Do not explain anything — just send the link.

Done when someone else successfully adds a link without your help. Whatever they fumble is your next project; whatever they ignore stays a non-goal.

Ship checklist

  • The app runs from a command in your README.md, on a clean start.
  • Data survives a restart, not just a refresh.
  • Nothing secret is in the repository — check with How to Scan Your Codebase for Hardcoded Secrets.
  • The public URL works on a device that is not your laptop.
  • You can name the file that handles the form submit without searching.
  • One person who is not you has used it.

Where this journey goes wrong

  • Skipping the spec. The app works, then stops working two prompts later because the assistant lost track of the goal.
  • Building five features at once. Nothing is finished, so nothing can be trusted.
  • Never running it. A green chat window is not a working app.
  • Committing .env. The most common way a first project leaks its keys.
  • Treating deployment as the last step. It is a checkpoint that exposes assumptions, so reach it early.

FAQ

Do I need to learn to code first?

No — but you do need to read the parts that touch data and secrets, and to run every checkpoint. The goal is not reading every line; it is being able to tell working from merely-running. What Is Vibe Coding (and Where Does It Break Down)? explains where that distinction bites.

How do I know when the project is actually done?

When a stranger can use it without you talking. That is the last milestone, and it is deliberately not a feature. Everything else — auth, search, a nicer UI — belongs to a later journey.

Share: