What you'll learn
  • How a Git-connected host builds the code you push
  • How builds and configured checks work, and what npm ci locks down
  • What a CDN caches and what a cache hit and a cache miss are
  • How a registrar, DNS records, and propagation point your domain at the host
  • The short list of reasons a site works locally and breaks in production
on this page

Your app works at http://localhost:3000. To share it, you need a host that serves it when your laptop is closed.

This guide follows one common route: a static site built from a Git repository and served through a content delivery network (CDN). Server-rendered apps and APIs also need a running backend; static sites and servers explains that difference.

The full journey

deployment flowselect a step to see what it does

Nothing selected yet. Pick a step above.

Click through each node above to see its role. Here’s the whole story, step by step.

Step 1: Where does your code actually live?

For this workflow, push your source to a remote repository that your host can access. The host builds a selected commit from that repository. Other workflows can upload built files directly; Git hosting is a convenient option, not a requirement of the web.

If “remote repo,” “push,” and “branch” aren’t second nature yet, go read Git beyond add, commit, push first, then come back. The short version: you push your latest code up to GitHub (or GitLab), and that becomes the version this whole pipeline builds from.

git add .
git commit -m "feat: ready to ship"
git push origin main

Step 2: Run the build and configure checks

A hosting provider can connect to your repository and build the branches you select. Some common options:

The moment you push, the provider springs into action:

  1. Pulls your latest code from the repo you linked.
  2. Installs your dependencies (all the packages you’ve been adding by hand or with npm).
  3. Runs your build (npm run build) to turn your source into shippable files.

npm installs your project’s JavaScript packages. In a project with a committed package-lock.json, npm ci installs the locked dependency versions and fails if the manifest and lockfile disagree. Match the Node and npm versions across your laptop and host as well. Native dependencies and environment settings can still make the builds differ.

Continuous integration (CI) runs the checks you configure. npm run build does not automatically run your tests or every type checker. For example, Astro needs a separate astro check command for type checking. Configure those checks as required steps before deployment, and confirm that a failure actually blocks release. See Astro’s type-checking documentation.

A green build means those commands succeeded. It does not prove that the app is free of bugs. Preview the built site and test the important user flows before releasing it.

Step 3: The hosting provider serves your build

Once the build succeeds, the output (your folder of HTML, CSS, JS, and images) gets handed to the hosting provider to store and serve. For a static site that’s basically the whole job: they drop your files on a server and hand you a temporary URL like your-project.vercel.app so you can see it live right away.

That temp URL already works for anyone in the world. The only thing missing is your name on it, which is the next two steps.

Step 4: A CDN caches your assets

Here’s where it gets fast. A CDN (Content Delivery Network) is a small army of servers scattered across the planet. Those servers run in edge locations. Instead of every visitor phoning one lonely server in Virginia, the CDN keeps a copy of your files close to wherever your users actually are.

“Cached” means a saved copy. If an edge has a usable copy, it can return it as a cache hit. On a miss, it may fetch from the origin and store the response if the caching rules allow it. Copies expire or get evicted, and some responses must be revalidated. Deployment platforms handle updates differently, so check the host’s cache behavior instead of assuming every visitor always gets an instant hit. For a static site this is basically free speed: your HTML, CSS, and JS don’t change between requests, so they cache beautifully. Vercel, Cloudflare, and Netlify all bundle a CDN in by default, something that used to cost real money and a lost weekend to wire up yourself.

Step 5: Your domain points at the CDN

So far your site lives at something like your-project.vercel.app. Time to give it a real name.

A domain is just the human-friendly address people type instead of a string of numbers, raindev.fyi instead of 76.76.21.21. Under the hood, computers route everything by IP address; domains exist so you don’t have to memorize those.

You rent a domain (yes, rent, usually a yearly fee) from a registrar. Common ones: Namecheap, Cloudflare Registrar (sells at cost, no markup), Porkbun, or Google’s old domains business, now run by Squarespace. Pick a name that isn’t taken, pay the yearly fee, and it’s yours to point wherever you want.

Pointing it is the job of DNS (Domain Name System): the phone book of the internet, mapping names to IP addresses. In the dashboard of whoever manages your DNS (which may be different from your registrar), add the records shown by your hosting provider after you attach the domain.

For example, a provider may ask for an A record at the root (@) and a CNAME for www. A normal CNAME cannot coexist with the records required at the root of a DNS zone; some DNS providers support flattening or an ALIAS-like feature instead. Use the exact names and values from your project’s domain settings, not a copied IP address from a tutorial. Vercel’s domain instructions show where to find them.

That change propagates across the internet (usually within minutes, occasionally up to 48 hours), and after that, your name routes real traffic to your site. If DNS still feels like guesswork (apex versus www, A records versus CNAME, why nothing updates instantly), the deeper Custom Domains and DNS guide untangles it.

Step 6: The browser does the rest

Someone finally types raindev.fyi and hits enter. Here’s the relay race that runs in well under a second:

  1. DNS lookup: “what IP is raindev.fyi?” The CDN’s address comes back.
  2. TLS handshake: the secure-connection part. TLS (Transport Layer Security, the “S” in HTTPS) encrypts everything traveling between the browser and the server, so nobody sharing the coffee-shop WiFi can read it. The server presents its certificate (cryptographic proof it really is raindev.fyi, signed by an authority browsers trust), the two sides agree on a set of keys, and from that point on the connection is private.
  3. HTTP request: now they can actually talk. HTTP is the request-and-response language browsers and servers speak. The browser sends a request like GET / (“send me the homepage”), and the server replies with a response: a status code (200 = OK, 404 = not found, 500 = the server tripped) plus the actual index.html.
  4. Parse: the browser reads the HTML, spots the <link>, <script>, and <img> tags, and fires off more HTTP requests to grab each one.
  5. Render: it paints the whole thing onto the screen.

The fastest path to production right now

For a static site, here is the workflow. If your Astro or Next.js app needs server rendering, first choose a deployment target that supports that runtime:

  1. Push your repo to GitHub.
  2. Connect it to a host like Vercel or Cloudflare Pages (free).
  3. Set your build command, output directory, runtime version, and required checks.
  4. Add your custom domain in the host’s dashboard.
  5. Update your registrar’s DNS to point at the host.

That’s it. From there, every push to main deploys itself. You go back to just writing code.

The classic “but it works on localhost” traps

Everything green locally and broken in prod? Start by checking these common causes:

ProblemCauseFix
Works locally, 404 in prodWrong base URLCheck the deployed route, output files, and any subpath base setting
Images missingAbsolute vs relative pathsCheck the requested URL, filename case, and whether the asset exists in the build
Env variables missingNot set on the hostAdd them in the host’s dashboard
Build fails on the host onlyDifferent Node versionPin engines.node in package.json

Now you know the whole journey. This is one common deployment workflow. The goal is a reproducible build, a reachable host, and a way to verify the result.

Where to go next

This guide is the map. The rest of the Deploy series zooms in on each leg of the trip:

signal check

Can you answer these without scrolling back up?

  1. What happens the moment you push to the repo your host is linked to?

    For a Git-connected deployment, the provider checks out the selected commit, installs dependencies, and runs the configured build. Tests and type checks block deployment only if you configure them as required steps. Passing checks reduces risk but cannot guarantee a bug-free release.

  2. Why do build servers run npm ci instead of a regular install?

    npm ci installs from package-lock.json and fails if it disagrees with package.json. Match the Node and npm versions, operating system requirements, and build configuration too; a lockfile alone does not reproduce the entire environment.

  3. What does it mean when a CDN serves a cache hit?

    A cache hit means an edge server can reuse a stored response. A miss may fetch from the origin and store the response if the cache rules allow it. Copies can expire, be evicted, or need revalidation.

progress is stored in this browser only

related guides