intellimetrics Learning
Mastery Module 11 · Ship It

Deploy Your Project

What you'll learn

~20 min
  • Understand what deployment means and why it matters
  • Deploy a project to Cloudflare Pages 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 Pages, 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:

  • Node.js and npm installed — verify with node -v and npm -v
  • Git installed and configured — verify with git --version
  • Code pushed to a GitHub repository — 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 npm run build succeed? Run it locally. If the build fails on your machine, it will fail on the hosting platform too.
  • No secrets in the code? Search your 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 (Cloudflare, Vercel, or Netlify all have a settings page for this). 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 committed and pushed. If you need a refresher, see Module 7 Lesson 4: GitHub: Your Cloud Backup.
  • Does the project look right? Run npm run dev, open it in your browser, and click through the main pages and features.

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.

💡This walkthrough is for static-export projects

The steps below work for static site generators and frameworks like Astro, Vite, and Create React App. If you are using a server-rendered framework (Next.js with SSR, Nuxt, SvelteKit), deployment requires platform-specific configuration — check your framework’s deployment docs for details.

Primary walkthrough: Cloudflare Pages

Cloudflare Pages is a great first choice. It is free, fast, and works with any static site or framework. Here is the full CLI walkthrough.

Step 1: Log in to Cloudflare

This opens your browser to authenticate with your Cloudflare account (sign up for free if you don’t have one). We use npx to run the Wrangler CLI without a global install, which avoids permission errors:

Terminal window
npx wrangler@latest login

Step 2: Build your project

Run the production build:

Terminal window
npm run build

This creates a dist/ folder (for Astro/Vite projects) or build/ folder (for Create React App) containing the optimized files ready for deployment.

Verify the build output exists before deploying:

Terminal window
ls dist

If you see a list of files (including index.html), you are ready. If you get “No such file or directory,” the build may have failed or your framework uses a different output folder (check build/ instead).

Step 3: Deploy

Send the built files to Cloudflare:

Terminal window
npx wrangler@latest pages deploy dist --project-name my-project

Replace my-project with a name for your site (lowercase, hyphens only). Replace dist with build if you are using Create React App.

Step 4: Visit your URL

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

https://my-project.pages.dev

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

💡That's it -- four commands

Login, build, deploy, visit. Every subsequent deploy is just two commands: npm run build and npx wrangler@latest pages deploy dist --project-name my-project.

Alternatives at a glance

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

PlatformBest forFree tierCLI deploy command
Cloudflare PagesAny static site, fast global CDNUnlimited sites, 500 builds/monthnpx wrangler@latest pages deploy dist
VercelReact/Next.js appsFree tier availablevercel --prod
NetlifyStatic sites, forms, serverlessFree tier availablenetlify deploy --prod
GitHub PagesSimple static sites, portfoliosUnlimited (public repos)Via git push (no separate CLI)

All four are free for personal and learning projects and 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 and Netlify build in the cloud

Unlike Wrangler (which uploads your pre-built dist folder), Vercel and Netlify upload your source code and run the build on their servers. This means you do not need to run npm run build before deploying with their CLIs — they handle it. It also means builds may take a bit longer since they install dependencies from scratch.

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, select the main branch, and save.

⚠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, Gemini CLI, 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, 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/Vite) or build/ (for Create React App) or .next/ (for Next.js)
  5. Save and deploy

Platform dashboard UIs change frequently. If any step looks different, check the platform’s current documentation: Cloudflare Pages 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 authentication (like Cloudflare Access, Vercel Password Protection, or Netlify Identity) or keep the project in a private repo and share the URL only with authorized users.

Practice

TRY ITWhat command would you run to build your project before deploying?
$
🔧

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/Astro the output is 'dist/', for Create React App it is 'build/'. 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 Pages, the _redirects file approach also works."
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 domains

Every hosting platform gives you a free URL (like my-project.pages.dev or my-project.vercel.app). If you want a professional-looking URL like dashboard.yourdomain.com, you can buy a domain name (around $10-15/year from a domain registrar like Namecheap, Cloudflare Registrar, or Squarespace Domains) 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 / State Devclick to expand

Government deployment considerations. State 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 and Netlify both support password-protected deployments on paid plans. For a free alternative, keep the GitHub repository private and only share the deployment URL with authorized users.

Key takeaways

  • Deployment is how you ship. A project on your laptop is invisible. A project with a URL is real.
  • Build locally before deploying. Run npm run build first. Fix errors on your machine, not on the hosting platform.
  • Cloudflare Pages is a great default. Login, build, deploy, visit. Done.
  • All four platforms are free and work well. Cloudflare Pages, Vercel, Netlify, and GitHub Pages all have free tiers for learning projects. 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?