Your First Web App with Claude Code
Build, understand, modify, and deploy a complete web application using only Claude Code and plain English. No prior coding experience required.
Choosing your first project
Your first web app should be simple enough to build in one sitting but useful enough to be worth deploying. Here are three proven first projects: a personal bookmark manager where you save, tag, and search links; a daily journal app where you write entries and browse by date; or a recipe collection where you store recipes and filter by ingredient. We will build a bookmark manager because it covers all the fundamentals: storing data, displaying a list, adding new items, searching, and basic styling. Before you start, decide on your tech stack. For beginners, we recommend Next.js because it handles both the frontend (what users see) and the backend (where data is stored) in a single project. Create your project: `mkdir ~/projects/bookmark-manager && cd ~/projects/bookmark-manager && git init`. Start Claude Code: `claude`. Now give Claude Code a clear brief: Create a bookmark manager web app using Next.js and TypeScript. Users should be able to add bookmarks with a title, URL, and tags. Display all bookmarks in a grid. Include a search bar that filters by title or tag. Use Tailwind CSS for styling. Store data in a JSON file for now. Make it look professional with a dark theme. This single prompt gives Claude Code everything it needs: the project type, tech stack, features, styling preference, and data strategy.
Scaffolding with Claude Code
After your prompt, Claude Code will start creating files. Watch what it does. It will likely run `npx create-next-app@latest . --typescript --tailwind --app` to scaffold a Next.js project with TypeScript and Tailwind CSS pre-configured. It will modify files to add your bookmark features: a data file for storing bookmarks, a page component for the UI, and API routes for adding and retrieving bookmarks. This process takes a few minutes. Claude Code will ask permission to run commands and create files — approve them. When it finishes, you should see a project structure with files like src/app/page.tsx for the main page, src/app/api/bookmarks/route.ts for the API, src/lib/bookmarks.json for the data store, and various configuration files. Run `npm run dev` to start the development server. Open http://localhost:3000 in your browser. You should see your bookmark manager with an input form and an empty bookmark grid. If you see errors instead, copy the error message and tell Claude Code: I see this error when running the app followed by the pasted error. Claude Code will diagnose and fix it. This debug-and-fix cycle is normal — even experienced developers rarely get everything right on the first try. The difference is that Claude Code can fix most issues in seconds rather than hours.
Understanding the code Claude Code wrote
Before modifying anything, understand what you have. Ask Claude Code: Walk me through every file you created and explain what each one does in plain English. I am a beginner. Claude Code will explain the key files: package.json lists your project dependencies and scripts. tsconfig.json configures TypeScript. tailwind.config.ts configures the CSS framework. src/app/layout.tsx is the root layout that wraps every page. src/app/page.tsx is your main page with the bookmark grid and search bar. src/app/api/bookmarks/route.ts handles adding and retrieving bookmarks. Go deeper on the main page: ask Claude Code to explain page.tsx line by line, what each import does, what useState means, and how the fetch call works. You do not need to memorise this, but understanding the structure helps you direct future changes. Key concepts to grasp: components are reusable pieces of UI like a BookmarkCard. State using useState holds data that can change like the search query. API routes handle data operations for reading and writing. Props pass data from parent components to child components. These four concepts are the foundation of React development. With them, you can understand any React application — and more importantly, you can give Claude Code specific instructions about what to change and where.
Modifying and adding features
Now make the app yours. Start with visual changes: tell Claude Code to change the color scheme to use blue as the primary color instead of the default, and make the bookmark cards have rounded corners and a subtle shadow. Claude Code edits the Tailwind classes across your components. Refresh the browser to see the changes. Next, add a feature: tell Claude Code to add the ability to mark bookmarks as favorites, show a star icon that toggles on click, and make favorites appear at the top of the list. Claude Code will modify the data model by adding a favorite field, update the UI by adding a star icon, and update the API to handle the toggle. Each change is small and verifiable. After Claude Code makes changes, refresh your browser and test. Click the star. Does it toggle? Do favorites sort to the top? If something is not right, tell Claude Code specifically what is wrong: The star toggles visually but the favorite status does not persist when I refresh the page. Specific bug reports get specific fixes. Continue adding features iteratively: Add a confirmation dialog before deleting a bookmark. Add keyboard shortcuts with Ctrl+K to focus the search bar. Add an import and export feature so I can backup my bookmarks as JSON. Each feature request is a conversation turn. Claude Code builds on the existing code, maintaining consistency across the project.
Styling and responsive design
Good styling is the difference between a project that looks like a homework assignment and one that looks like a real product. Ask Claude Code: Redesign the UI to look like a modern SaaS application. Use a sidebar for navigation, a header with the app name and a user avatar placeholder, and a main content area with the bookmark grid. Add hover effects on cards, transitions on the search bar, and proper spacing throughout. Claude Code will restructure the layout and apply professional styling patterns. For the bookmark cards, ask Claude Code to show the site favicon using a favicon service, the title in bold, the URL in grey, tags as colored pills, and the date it was added. Add a subtle hover effect that lifts the card. For the empty state when there are no bookmarks, show a friendly message and a prominent Add Bookmark button. For responsive design: tell Claude Code to make the layout work on mobile with the sidebar collapsing to a bottom navigation bar on screens under 768px, the bookmark grid becoming single column on mobile, two columns on tablet, and three columns on desktop. Test on different screen sizes using your browser developer tools by pressing F12 and clicking the device toggle icon. Good styling is iterative so do not try to get everything perfect in one prompt. Make small adjustments: increase the spacing between cards, make the search bar wider, use a slightly lighter shade for the card background.
Testing and fixing bugs
Before deploying, test everything systematically. Open your app and work through each feature. Add a bookmark — does it appear in the grid? Search for it — does the filter work? Star it — does it move to the top? Delete it — does the confirmation dialog appear? Refresh the page — does everything persist? Now try edge cases: add a bookmark with a very long title that might break the layout. Add one with no tags. Search for something that does not exist. Paste a URL without https:// prefix. Add the same URL twice. These edge cases reveal bugs that normal testing misses. When you find a bug, report it to Claude Code with exact reproduction steps: When I add a bookmark without https:// in the URL, just entering google.com, clicking the bookmark opens a broken link to localhost:3000/google.com instead of the actual site. Claude Code will add URL validation and normalization. Check the browser console for JavaScript errors: press F12 and click the Console tab. Red errors indicate problems. Copy the error text and share it with Claude Code. Check the terminal where npm run dev is running — server-side errors appear there. Common issues and fixes: ECONNREFUSED means the API cannot connect to a service. Hydration mismatch means the server-rendered HTML differs from the client, usually caused by dates or random values. A 404 on an API route means the route file is in the wrong location or named incorrectly.
Adding a database
A JSON file works for development but is not suitable for production deployment. Let us add a real database. Ask Claude Code: Replace the JSON file storage with SQLite using the better-sqlite3 package. Create a bookmarks table with columns for id, title, url, tags stored as a comma-separated string, favorite as a boolean, and createdAt. Migrate the existing JSON data to the database. Keep the API routes working the same way. Claude Code will install better-sqlite3, create a database initialization script, rewrite the API routes to use SQL queries, and add a migration step. SQLite is perfect for small to medium applications — it is a file-based database that requires no separate server process. Your data is stored in a single .sqlite file in your project directory. After Claude Code makes the changes, test everything again. Add a bookmark, refresh, verify it persists. The behavior should be identical to before, but now you have a proper database backing the application. For production applications, you would eventually move to PostgreSQL or another server-based database. But SQLite is excellent for learning and for applications with modest traffic. Commit this milestone: `git add . && git commit -m 'Add SQLite database for bookmark persistence'`. Having Git checkpoints at major changes means you can always go back to the JSON version if the database migration introduced unexpected issues.
Deploying to the internet
Your app works locally. Now put it on the internet for anyone to use. We will use Vercel because it is free for personal projects and deploys Next.js apps with zero configuration. First, push your code to GitHub: create a new repository on github.com, then run `git remote add origin https://github.com/yourusername/bookmark-manager.git && git push -u origin main`. Go to vercel.com and sign in with your GitHub account. Click New Project, select your bookmark-manager repository, and click Deploy. Vercel detects that it is a Next.js project and configures everything automatically. In about 60 seconds, your app is live at a URL like bookmark-manager-abc123.vercel.app. There is one important consideration: SQLite writes to the filesystem, and Vercel serverless functions have a read-only filesystem. For deployment, you have two options. The simpler option: ask Claude Code to switch the storage to use localStorage in the browser so the app works as a client-side only application on Vercel. This eliminates the database entirely — bookmarks are stored in the user's browser. The more advanced option: switch to a cloud database like Turso, which is SQLite-compatible but hosted remotely. Ask Claude Code to handle either migration. Share your deployed URL with friends and colleagues. You just built and deployed a web application using Claude Code and plain English.
What to build next
You have the fundamental workflow: describe, build, understand, modify, test, deploy. Now apply it to progressively more ambitious projects. A personal blog with markdown support teaches you file-based content, markdown rendering, and static site generation. A task management app with drag-and-drop teaches you complex state management and interactive UI libraries. A weather dashboard that pulls from an API teaches you external API integration and data fetching. A URL shortener teaches you database design, unique ID generation, redirects, and analytics. Each project should follow the same workflow: create a folder, init git, start Claude Code, describe what you want, build iteratively, understand what was created, test thoroughly, and deploy. The key insight from this guide: you do not need to learn programming syntax to build web applications. You need to learn how to describe what you want clearly, understand the code at a conceptual level, test thoroughly, and iterate on feedback. Claude Code handles the syntax while you handle the vision. As you build more projects, you will naturally start understanding the code. You will recognise patterns, anticipate how changes should be structured, and give increasingly precise instructions to Claude Code. This is how many successful developers started — by building first and understanding second, letting curiosity drive deeper learning over time.
AI Automation Fundamentals
This guide is hands-on and practical. The full curriculum covers the conceptual foundations in depth with structured lessons and quizzes.
Go to lesson