Mastery Module 11 · Ship It

Deploy Your Project

Last reviewed

Intermediate

What you'll learn

~20 min
  • Understand what deployment means and why it matters
  • Deploy a project to Cloudflare Workers using the CLI
  • Deploy alternatives: Vercel, Netlify, GitHub Pages
  • Set up auto-deploy from GitHub pushes
  • Troubleshoot common deployment failures

You’ll deploy a project to the internet — often in 5-15 minutes for first-time setup, much faster after that — so anyone with the URL can see it.

Why this matters

Building is only half the job. Sharing your project multiplies its impact and makes your work easier to showcase. Deployment is how you ship. It is the difference between “I built a thing on my laptop” and “here is the link — try it yourself.” Every project you deploy becomes a real portfolio piece, a shareable proof of work, and something you can point to in a job interview, a class presentation, or a grant proposal.

Mental model: the copy shop

Your project is the original document sitting on your laptop. A hosting platform (Cloudflare, Vercel, Netlify, GitHub Pages) is a copy shop: you hand it the original, and it prints and distributes copies to anyone who asks for them. The URL is the address you hand out so people can pick up their copy.

The best part? Modern copy shops are smart. You can set them up to watch your GitHub repository. Every time you update the original (push to GitHub), they automatically print a fresh version. That is auto-deploy — and it means you never have to manually deploy again after the first time.

Before you start

Make sure you have the following ready before deploying:

  • Your project in a folder, either a plain HTML folder (like the ai-class or first-workflow folder from the early modules) or a framework app built with Astro or Vite
  • Git installed and configured, ask your agent to check, or run git --version
  • Code pushed to a GitHub repository (needed for auto-deploy, not for the first manual deploy), if you need a refresher, see Module 7 Lesson 4
  • A free account on your chosen hosting platform — Cloudflare, Vercel, Netlify, or GitHub Pages

Pre-deployment checklist

Before you deploy for the first time, run through this list:

  • Does the project look right? Ask your agent to start a local preview, open it in your browser, and click through the main pages and features.
  • No secrets in the code? Ask your agent to search the project for API keys, passwords, or tokens. They should be in .env, not hardcoded in source files. Remember: .env is for local development only. For production, set environment variables in your hosting platform’s dashboard. Never upload .env to a hosting platform.
  • Is .gitignore correct? In most Node/web workflows, node_modules/, .env, and build output like dist/ or build/ should all be excluded from git tracking.
  • Code pushed to GitHub? Your latest changes should be saved and pushed. If you need a refresher, see Module 7 Lesson 4: GitHub: Your Cloud Backup.
  • Framework apps only: does the build succeed? If the build fails on your machine, it will fail on the hosting platform too. A plain HTML folder has no build step, so skip this one.

If you have not completed Module 10 (Planning and Orchestration), you can still deploy, but Module 10 teaches you how to plan and iterate on projects effectively, which makes the deploy-fix-redeploy cycle much smoother.

💡Two kinds of project, one walkthrough

A plain HTML folder (an index.html and friends, no build step) deploys as it is: you publish the folder itself. A framework app (Astro, Vite) is built first, and you publish its dist/ folder. If you are using a server-rendered framework (Next.js with SSR, Nuxt, SvelteKit), deployment requires platform-specific configuration, so check your framework’s deployment docs. Create React App was deprecated in February 2025; new React projects start with Vite or a framework.

Primary walkthrough: Cloudflare Workers

Cloudflare is a great first choice. Its free plan serves static files with no request limit, and it works with any static site. Cloudflare now hosts new static sites on Workers (its Pages docs say “Start new projects with Workers”), so that is what this walkthrough uses.

The easy way: ask your agent

Open your agent in the project folder and ask:

Preview this project locally, then deploy it to Cloudflare Workers with Wrangler. Tell me before you run anything that publishes it.

The agent works out whether your folder is plain HTML or a framework app, builds it if needed, and runs the deploy. When Wrangler opens your browser to log in to Cloudflare (sign up for free if you do not have an account), you approve it there. The agent then gives you the live URL.

The rest of this section shows what the agent runs for you, so you can recognize it and fix things when they go wrong.

Step 1: Log in to Cloudflare

This opens your browser to authenticate with your Cloudflare account. We use npx to run the Wrangler CLI without a global install, which avoids permission errors (npx comes with Node.js; if you picked a Desktop App or native CLI on Day 1 and do not have Node.js installed yet, ask your agent to install Node.js LTS or run the deploy commands for you):

Terminal window
npx wrangler@latest login

Step 2: Build (framework apps only)

A plain HTML folder skips this step. For an Astro or Vite project, run the production build:

Terminal window
npm run build

This creates a dist/ folder containing the optimized files ready for deployment. If the build output folder is missing, the build may have failed or your framework uses a different folder (the build command’s last lines name it; use that folder in Step 3).

Step 3: Deploy

Tell Wrangler where your files are. Create a file named wrangler.jsonc in your project root. For a framework app, point it at dist:

{
"name": "my-project",
"compatibility_date": "2026-11-07",
"assets": { "directory": "./dist" }
}

For a plain HTML site (no framework build step), put your site files (index.html, style.css, images) inside a public/ subfolder so wrangler.jsonc, .env, and project notes at the root are not published, and point Wrangler at ./public:

{
"name": "my-project",
"compatibility_date": "2026-11-07",
"assets": { "directory": "./public" }
}

Then send the files to Cloudflare:

Terminal window
npx wrangler@latest deploy

Already have a Cloudflare Pages project? It still deploys the old way: npx wrangler@latest pages deploy dist --project-name my-project.

Replace my-project with a name for your site (lowercase, with hyphens between words), and use today’s date for compatibility_date. If your framework builds to a different folder, change ./dist to match.

Step 4: Visit your URL

Wrangler prints the URL when the deploy finishes. It looks like:

https://my-project.your-subdomain.workers.dev

your-subdomain is your account’s own workers.dev name, which Wrangler shows you.

Open it in your browser. Your project is live on the internet.

💡That's it -- four steps

Login, build (framework apps only), deploy (after a one-time wrangler.jsonc), visit. Every later deploy is just npx wrangler@latest deploy, preceded by npm run build for framework apps. Or ask your agent to do both.

Alternatives at a glance

Cloudflare is not the only option. Here is a quick comparison:

PlatformBest forFree tierCLI deploy command
Cloudflare WorkersAny static site, fast global CDNStatic-file requests free and unlimited; up to 20,000 files per site; 3,000 build minutes/month for Git builds (as of 2026-11-07)npx wrangler@latest deploy
VercelReact/Next.js appsHobby plan: free, personal non-commercial use onlynpx vercel --prod
NetlifyStatic sites, forms, serverlessFree plan: 300 credits/month, and each production deploy uses 15 (as of 2026-11-07)npx netlify-cli deploy --prod
GitHub PagesSimple static sites, portfoliosFree for public repos (private repos need a paid plan); sites up to 1 GB, 100 GB/month soft bandwidth limitgit push plus a GitHub Actions workflow (no separate CLI)

All four have a free plan that covers a personal or learning project (Vercel’s Hobby plan and GitHub Pages are not for commercial sites), and all are solid choices for getting started. Choose based on your framework and needs. Free tier limits change over time — check each platform’s pricing page for current details.

💡Vercel builds in the cloud; Netlify builds on your machine

Wrangler uploads the dist folder you already built. The Vercel CLI uploads your source and Vercel runs the build on its servers, so you can skip npm run build there (builds may take a bit longer because dependencies install from scratch). The Netlify CLI runs your build on your machine first, then uploads the result.

Quick setup: Vercel

Terminal window
npx vercel login
npx vercel # Follow the prompts
npx vercel --prod # Deploy to production

Quick setup: Netlify

Terminal window
npx netlify-cli login
npx netlify-cli init # First time: link to a Netlify site
npx netlify-cli deploy --prod

Quick setup: GitHub Pages

No CLI install needed. Go to your repository on github.com, click Settings, then Pages. Under “Build and deployment”, set Source to GitHub Actions for a site that needs a build step, or to Deploy from a branch (then pick main) for plain HTML files.

⚠GitHub Pages needs a build step for most frameworks

If your project uses Astro, React, Vite, or any framework that needs npm run build, selecting a branch alone will publish your raw source files — not the built site. You need a GitHub Actions workflow to build and deploy automatically. Open your AI CLI tool (such as Claude Code, Antigravity, or your preferred tool) and ask it to create a .github/workflows/deploy.yml file for your framework. Platform dashboard UIs change frequently, so verify the current steps in the GitHub Pages documentation.

Auto-deploy from GitHub

Manual CLI deploys work fine, but auto-deploy is the real goal. Here is the idea: connect your GitHub repository to a hosting platform once, and every git push automatically triggers a rebuild and deployment.

How to set it up

  1. Go to your hosting platform’s dashboard (Cloudflare’s Workers & Pages page, Vercel, or Netlify)
  2. Create a new project and choose “Import from GitHub”
  3. Select your repository and authorize access
  4. Configure build settings:
    • Build command: npm run build (or astro build for Astro projects — most frameworks support npm run build as the standard command)
    • Output directory: dist/ (for Astro and Vite). For Next.js, follow the platform’s Next.js guide instead of setting a folder here.
  5. Save and deploy

Platform dashboard UIs change frequently. If any step looks different, check the platform’s current documentation: Cloudflare Workers docs, Vercel docs, Netlify docs.

From this point forward, the workflow is:

Make changes --> git add . --> git commit -m "description" --> git push --> Site auto-updates

No manual deploy steps. Push to GitHub, wait 1-5 minutes (depending on build size and queue), and your live site reflects the changes.

⚠Client-side password gates are not real security

Some tutorials suggest using localStorage or JavaScript to create a simple password gate. Do not use this for anything sensitive. Anyone can open browser DevTools and bypass client-side checks in seconds. For real access control, use server-side access control (like Cloudflare Access, Vercel Authentication, or Netlify’s project visibility setting). A private GitHub repository is not access control: a deployed site is public even when its repository is private.

Practice

Check your build

In your agent, in your own project folder, ask:

Run the build for this project and tell me whether it passes. If it fails, explain why before changing anything.

A passing build locally is your signal that the hosting platform will build it too.

🔧

When Things Go Wrong

Use the Symptom → Evidence → Request pattern: describe what you see, paste the error, then ask for a fix.

Symptom
The deploy fails with 'build command failed'
Evidence
Build log shows: Error: Cannot find module 'react' or npm ERR! code ERESOLVE
What to ask the AI
"My deployment build is failing because dependencies are not installing correctly. Check that package.json lists all required dependencies (not just devDependencies). Run npm install locally and verify npm run build succeeds. If it works locally, check if the hosting platform's Node.js version matches yours -- you may need to set a NODE_VERSION environment variable."
Symptom
The site deploys but shows a blank white page
Evidence
The URL loads but the page is empty. Browser console shows 404 errors for JavaScript files.
What to ask the AI
"My deployed site shows a blank page. This usually means the build output directory is wrong. Check the hosting platform's settings: for Vite and Astro the output is 'dist/'. Also check if the base URL needs to be set -- for GitHub Pages, add base: '/repo-name/' to the Vite or Astro config."
Symptom
All other routes show 404 when refreshing the page
Evidence
Clicking navigation links works, but refreshing a subpage like /about gives a 404 error
What to ask the AI
"My single-page app routes work with client-side navigation but break on direct URL access or refresh. I need to configure the hosting platform to redirect all routes to index.html. For Netlify, create a _redirects file with '/* /index.html 200'. For Vercel, create a vercel.json with rewrites. For Cloudflare Workers, add 'not_found_handling': 'single-page-application' under 'assets' in wrangler.jsonc. (Cloudflare Pages does this on its own when the site has no 404.html.)"
Symptom
Auto-deploy is not triggering after git push
Evidence
I pushed to GitHub 10 minutes ago but the live site still shows the old version
What to ask the AI
"My auto-deploy does not seem to be triggering. Check the hosting platform's dashboard for build status -- it may have failed silently. Also verify you are pushing to the correct branch (main or master) that the platform is watching. If the build succeeded, try clearing your browser cache or opening the URL in an incognito window."
Symptom
Deploy fails with 'missing environment variable' error
Evidence
Build log shows: Error: Missing required environment variable API_KEY or similar
What to ask the AI
"My deployment is failing because an environment variable is not set on the hosting platform. I have a .env file locally but the hosting platform does not have access to it. I need to add the required environment variables in the hosting platform's dashboard under Settings > Environment Variables. Never upload .env files directly."
Symptom
Build times out during deployment
Evidence
Build log ends with a timeout error after 10-15 minutes
What to ask the AI
"My deployment build is timing out. This can happen if the project is very large or has expensive build steps. Check if there are unnecessary files being processed. Also verify the build command is correct -- a wrong command might hang instead of failing cleanly. Try running the build locally to see how long it takes."
🔍Custom domainsclick to expand

Every hosting platform gives you a free URL (like my-project.your-subdomain.workers.dev or my-project.vercel.app). If you want a professional-looking URL like dashboard.yourdomain.com, you can buy a domain name from a domain registrar like Namecheap or Cloudflare Registrar (the yearly price depends on the name and its ending, so check before you buy) and connect it in your hosting platform’s domain settings. The platform handles SSL certificates automatically. This is optional — the free URLs work perfectly for sharing and portfolios.

Use cases and considerations

🧬In Your Field: Biotechclick to expand

Sharing research tools with your lab. Deploy your data visualization tool or lab calculator and share the link with collaborators. A live URL is much easier to share than “clone my repo and run npm install.” Your PI can open the tool on their phone during a meeting. Collaborators at other institutions can use it without any setup.

🏛️In Your Field: Government Devclick to expand

Government deployment considerations. Agencies may have restrictions on which hosting platforms are approved. Check with your IT department before deploying agency tools to external platforms. For internal tools, your agency may have an approved hosting environment. For personal portfolio projects or open-source civic tools, the free platforms listed here work well.

📊In Your Field: MIS / Businessclick to expand

Deploying business dashboards. For internal dashboards, you may want a private deployment. Vercel Authentication, available on every Vercel plan, limits a deployment to people you give access in Vercel. Password protection is a paid feature on Vercel (Pro) and Netlify (Pro). A private GitHub repository does not hide the site: a deployment is public even when its repository is private.

Key takeaways

  • Deployment is how you ship. A project on your laptop is invisible. A project with a URL is real.
  • Preview locally before deploying. For framework apps, build first. Fix errors on your machine, not on the hosting platform.
  • Cloudflare Workers is a great default. Ask your agent to preview and deploy it, approve the browser login, and visit the URL. Plain HTML folders and framework apps both work.
  • All four platforms have a free plan and work well. Cloudflare, Vercel, Netlify, and GitHub Pages all cover learning projects for free. Vercel’s free plan and GitHub Pages are for non-commercial sites. Pick whichever feels simplest.
  • Auto-deploy is the goal. Connect GitHub to your hosting platform once, and every git push updates the live site automatically.
KNOWLEDGE CHECK

After connecting your GitHub repo to a hosting platform, what happens when you push new changes?

Search lessons