Deploy Your First Website to Vercel

Deploy a personal portfolio site to Vercel's global CDN using the CLI.

Introduction

30 Second Summary

You've built something cool on your computer. Maybe it's a portfolio, a side project, or just a page you're proud of. But right now, nobody else can see it.

In this project, you will build a personal portfolio page and deploy it to the internet using the Vercel CLI. You'll get a live public URL you can share with anyone.

What You'll Build

A styled HTML/CSS portfolio page deployed to Vercel's global CDN using terminal commands.

By the end of this project, you'll have:

  • A portfolio page built with HTML and CSS from scratch.
  • A preview deployment and a production deployment live on Vercel with shareable URLs.
  • A repeatable deployment workflow for shipping website updates in seconds.
  • Secret Mission: Add a dark mode toggle with JavaScript and redeploy to see instant updates.

Are there any prerequisites?

None. This guide includes full setup instructions for every tool you need, including Node.js and the Vercel CLI.

Install Node.js and the Vercel CLI

Before you deploy anything to the internet, you need the right tools on your computer. Node.js is a JavaScript runtime that powers developer tools like the Vercel CLI.

The Vercel CLI handles the actual deployment process from your terminal. In this step, you'll install both tools and create your free Vercel account.

In this step, get ready to:
  • Install Node.js (version 18 or higher).
  • Install the Vercel CLI globally.
  • Create a free Vercel account and log in from your terminal.
Install Node.js

Node.js is required for the Vercel CLI to run. You need version 18 or higher for this project.

  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal and press Enter to open it.
  • Check if Node.js is already installed by running this command:
node --version

Look at the output in your terminal and pick the tab below that matches what you see.

✔️ I see version 18 or higher

Node.js is ready to go. Move on to the next substep below.

ⓧ I see an older version

Your current version is too old for this project. The Node.js installer will upgrade it in place.

  • Go to nodejs.org in your browser.
  • Download the version labeled LTS.
  • Run the installer and follow the prompts. Accept the default settings.
  • Close your terminal completely, then reopen it.
  • Run node --version again to confirm you now see version 18 or higher.

ⓧ Command not found

Node.js is not installed yet. You'll download it from the official website.

  • Go to nodejs.org in your browser.
  • Download the version labeled LTS.
  • Run the installer and follow the prompts. Accept the default settings.
  • Close your terminal completely, then reopen it.
  • Run node --version to confirm you see a version number starting with 18 or higher.

Still not seeing a version number?

Make sure you fully closed and reopened your terminal after installing. The terminal needs to restart to pick up newly installed programs.

On Windows, try searching for and opening Command Prompt instead of Terminal if you don't see a Terminal app.

Help me install Node.js on my computer

Install the Vercel CLI

The Vercel CLI is the tool that uploads your project files to Vercel's servers. You install it using npm, the package manager that comes bundled with Node.js.

  • Install the Vercel CLI globally by running this command:
npm i -g vercel

What does this command do?

npm i -g vercel tells npm to install the vercel package globally (the -g flag). Global means you can run the vercel command from any folder on your computer.

  • Confirm the installation by running:
vercel --version

You should see a version number in the output. This confirms the Vercel CLI is installed and ready to use.

Seeing a permission error?

On macOS or Linux, you may need to add sudo before the install command. Run sudo npm i -g vercel and enter your computer password when prompted.

On Windows, try closing your terminal and reopening it with Run as administrator.

Help me fix this npm permission error

Create a Vercel account and log in

You need a free Vercel account so the CLI knows where to deploy your site. The Hobby plan is completely free and does not require a credit card.

  • Go to vercel.com in your browser.
  • Click Sign Up.
  • Create your account using GitHub, GitLab, Bitbucket, or email. Any option works.
  • Once your account is created, return to your terminal.
  • Log in to Vercel from your terminal by running this command:
vercel login

What happens when you run this?

The CLI will open your default browser and ask you to confirm the login. Click the confirmation button in the browser to authorize your terminal session.

Once confirmed, your terminal will display a success message. You're now authenticated and ready to deploy.

  • Follow the prompts in your browser to approve the login.
  • Return to your terminal and confirm you see a success message.

Browser didn't open?

If the browser did not open automatically, look in the terminal output for a URL. Copy and paste that URL into your browser manually.

Make sure you're logging in with the same account you just created on vercel.com.

Help me log in to Vercel from my terminal

Your tools are installed and authenticated. Next up, you'll build the portfolio page that you'll deploy to the internet.

Build Your Portfolio Page

Your development environment is set up and your Vercel account is ready to go. Now it's time to build the actual page you'll deploy to the internet.

Every deployed website starts as local files on your computer. In this step, you'll write the HTML structure and CSS styles for a personal portfolio page.

In this step, get ready to:
  • Create a project folder with an HTML file for your portfolio page.
  • Style the page with CSS for a clean, professional look.
  • Preview the site locally in your browser.
Create your project folder

You need a dedicated folder to hold your website files. This folder is what you'll deploy to Vercel in the next step.

  • Move to your Desktop by running this command:
cd ~/Desktop
  • Create your project folder and move into it by running these commands:
mkdir my-portfolio
cd my-portfolio
  • Confirm the folder was created by running:
pwd

You should see a path ending in my-portfolio.

Seeing "No such file or directory"?

Make sure you ran cd ~/Desktop first. The tilde (~) means your home folder, so ~/Desktop points to the Desktop inside it.

help me fix a "No such file or directory" error when creating my project folder

  • Open Cursor by pressing Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Cursor and press Enter to open it.
  • In Cursor, click File in the top menu bar.
  • Click Open Folder.
  • Select the my-portfolio folder on your Desktop, then click Open.

Cursor now shows your empty project folder in the sidebar.

  • Create a new file by pressing Cmd+N (macOS) or Ctrl+N (Windows).
  • Save it immediately with Cmd+S (macOS) or Ctrl+S (Windows).
  • Name the file index.html and save it inside the my-portfolio folder.
  • Add the full page structure to index.html by copying this code into the file:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Portfolio</title>
    <!-- Link to our stylesheet -->
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <!-- Main content wrapper -->
    <div class="container">
        <header>
            <h1>Hi, I'm Alex</h1>
            <p class="bio">I'm a developer learning to build and deploy websites. This portfolio is hosted on Vercel's global CDN.</p>
        </header>

        <!-- Projects section with two card placeholders -->
        <section class="projects">
            <h2>My Projects</h2>
            <div class="project-grid">
                <div class="project-card">
                    <h3>Project One</h3>
                    <p>A simple calculator app built with JavaScript. Handles basic arithmetic operations with a clean interface.</p>
                </div>
                <div class="project-card">
                    <h3>Project Two</h3>
                    <p>A weather dashboard that displays the current forecast. Uses a public API to fetch real-time data.</p>
                </div>
            </div>
        </section>

        <footer>
            <p>Deployed with Vercel</p>
        </footer>
    </div>
</body>
</html>

What does this code do?

  • The <head> section sets up the page title and links to a CSS file you'll create next.
  • The <header> contains your name and a short bio paragraph.
  • The .projects section holds a grid of cards, each representing a project you've worked on.
  • The <footer> adds a small note at the bottom crediting Vercel for hosting.
  • Save index.html with Cmd+S (macOS) or Ctrl+S (Windows).

File not showing in the sidebar?

Make sure you saved the file inside the my-portfolio folder, not somewhere else on your Desktop. If the Explorer sidebar is empty, click File then Open Folder again and select the correct folder.

help me find where my index.html file was saved

✔️ Awesome, I've got everything!

Great. Double check you've saved index.html and it appears in Cursor's Explorer sidebar.

ⓧ I'd like to double check the full code

Here's the complete index.html file for comparison:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Portfolio</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="container">
        <header>
            <h1>Hi, I'm Alex</h1>
            <p class="bio">I'm a developer learning to build and deploy websites. This portfolio is hosted on Vercel's global CDN.</p>
        </header>

        <section class="projects">
            <h2>My Projects</h2>
            <div class="project-grid">
                <div class="project-card">
                    <h3>Project One</h3>
                    <p>A simple calculator app built with JavaScript. Handles basic arithmetic operations with a clean interface.</p>
                </div>
                <div class="project-card">
                    <h3>Project Two</h3>
                    <p>A weather dashboard that displays the current forecast. Uses a public API to fetch real-time data.</p>
                </div>
            </div>
        </section>

        <footer>
            <p>Deployed with Vercel</p>
        </footer>
    </div>
</body>
</html>
Style the page

Your HTML has the structure, but it looks plain without any styling. CSS controls how the page looks: colors, spacing, fonts, and layout.

  • Create another new file with Cmd+N (macOS) or Ctrl+N (Windows).
  • Save it as style.css inside the my-portfolio folder.
  • Add the base layout styles to style.css by copying this code into the file:
/* Reset default browser styles */
* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

/* Page-level layout and font */
body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif;
    line-height: 1.6;
    color: #333;
    background-color: #f9fafb;
    padding: 2rem;
}

/* Center content with a max width */
.container {
    max-width: 720px;
    margin: 0 auto;
}

/* Space below the header section */
header {
    margin-bottom: 3rem;
}

/* Main heading style */
h1 {
    font-size: 2.5rem;
    margin-bottom: 0.5rem;
    color: #111;
}

/* Bio paragraph styling */
.bio {
    font-size: 1.1rem;
    color: #555;
}

What does this code do?

  • The * selector resets all default browser margins and padding so you start with a clean slate.
  • The body rule sets a system font stack that looks native on every operating system.
  • The .container class centers your content and caps it at 720px wide so it doesn't stretch across large screens.
  • Save style.css.
  • Open index.html in your browser by double-clicking the file in Finder (macOS) or File Explorer (Windows).

You should see your name as a large heading with the bio text below it, centered on the page with a light gray background. The project cards are there but unstyled.

Page looks completely unstyled?

Check that style.css is saved in the same folder as index.html. The <link> tag in your HTML references style.css by name, so both files must be in my-portfolio together.

help me figure out why my CSS styles aren't loading

  • Now add the project card and footer styles below the existing code in style.css:
/* Section heading */
h2 {
    font-size: 1.5rem;
    margin-bottom: 1rem;
    color: #111;
}

/* Two-column grid for project cards */
.project-grid {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 1.5rem;
}

/* Individual card styling */
.project-card {
    background: #fff;
    border: 1px solid #e5e7eb;
    border-radius: 8px;
    padding: 1.5rem;
}

.project-card h3 {
    font-size: 1.1rem;
    margin-bottom: 0.5rem;
    color: #111;
}

.project-card p {
    font-size: 0.95rem;
    color: #555;
}

/* Footer at the bottom */
footer {
    margin-top: 3rem;
    text-align: center;
    color: #999;
    font-size: 0.85rem;
}

What does this code do?

  • The .project-grid uses CSS Grid to lay out the two cards side by side in equal columns.
  • Each .project-card gets a white background, rounded corners, and a subtle border so it looks like a tidy card.
  • The footer sits at the bottom with centered, muted text.
  • Save style.css and refresh your browser.

Your project cards should now appear as two white boxes side by side with rounded corners and a border. The footer text appears centered at the bottom.

Cards stacked vertically instead of side by side?

If your browser window is narrow, the two cards may wrap below each other. Try making your browser window wider. Also confirm that the .project-grid selector exactly matches class="project-grid" in your HTML.

help me fix my CSS grid layout for project cards

✔️ Awesome, I've got everything!

Great. Double check you've saved style.css and your page looks styled in the browser.

ⓧ I'd like to double check the full code

Here's the complete style.css file for comparison:

* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif;
    line-height: 1.6;
    color: #333;
    background-color: #f9fafb;
    padding: 2rem;
}

.container {
    max-width: 720px;
    margin: 0 auto;
}

header {
    margin-bottom: 3rem;
}

h1 {
    font-size: 2.5rem;
    margin-bottom: 0.5rem;
    color: #111;
}

.bio {
    font-size: 1.1rem;
    color: #555;
}

h2 {
    font-size: 1.5rem;
    margin-bottom: 1rem;
    color: #111;
}

.project-grid {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 1.5rem;
}

.project-card {
    background: #fff;
    border: 1px solid #e5e7eb;
    border-radius: 8px;
    padding: 1.5rem;
}

.project-card h3 {
    font-size: 1.1rem;
    margin-bottom: 0.5rem;
    color: #111;
}

.project-card p {
    font-size: 0.95rem;
    color: #555;
}

footer {
    margin-top: 3rem;
    text-align: center;
    color: #999;
    font-size: 0.85rem;
}
Preview locally

Before deploying anything to the internet, it's good practice to confirm your page looks right locally.

  • Refresh index.html in your browser if it's still open.
  • Confirm you see: a large heading that says "Hi, I'm Alex", a bio paragraph below it, and two project cards side by side.
  • Scroll down and check that the footer says "Deployed with Vercel" at the bottom.

Why preview before deploying?

Catching layout issues locally is instant. Once you deploy to Vercel, every change requires re-running a deploy command. Previewing first saves you from shipping a broken page.

Your portfolio page is looking sharp. Next up, you'll deploy it to Vercel and see it live on the internet.

Deploy a Preview to Vercel

Your portfolio page looks great on your machine. Now it is time to put it on the internet where anyone with the URL can see it.

The Vercel CLI handles the entire deployment process from your terminal. One command uploads your files, assigns a unique URL, and distributes your site across a global network.

In this step, get ready to:
  • Run your first deployment with the Vercel CLI.
  • Visit your live preview URL in the browser.
  • Understand preview vs production deployments.
Run your first deploy

Running vercel in your project folder kicks off an interactive setup wizard. It creates a new project, uploads your files, and returns a live URL.

  • Switch back to your terminal and make sure you are inside the my-portfolio folder by running:
cd ~/Desktop/my-portfolio
  • Deploy your project by running:
vercel

What will the CLI ask you?

The vercel command launches an interactive setup the first time you run it in a new folder. Here is how to answer each prompt:

  • Set up and deploy? Press Y and Enter to confirm.
  • Which scope? Select your personal account (the one you signed up with) and press Enter.
  • Link to existing project? Enter N to create a new one.
  • What's your project's name? Press Enter to accept the default name (my-portfolio).
  • In which directory is your code located? Press Enter to accept the default (./).
  • Want to override the settings? Enter N. Since your project is plain HTML/CSS with no framework, Vercel serves the files directly without a build step.

After you answer the prompts, the CLI uploads your files and outputs a preview URL. You should see a URL in your terminal that ends in .vercel.app.

Seeing an error about authentication?

If the CLI says you are not logged in, run vercel login again and complete the browser authentication. Then re-run vercel in your my-portfolio folder.

If the command itself is not found, the global install may not be on your PATH. Close and reopen your terminal, then try again.

Help me troubleshoot my Vercel deployment error.

Visit your preview URL

The CLI printed a deployment URL in your terminal. This is your site, live on the internet.

  • Copy the preview URL from your terminal output (it looks like https://my-portfolio-xxxxxxxxx.vercel.app).
  • Paste it into your browser address bar and press Enter.

You should see your portfolio page with your name, bio, and project cards displayed exactly as they looked locally.

Page not loading or showing an error?

Make sure you copied the full URL including https://. The URL should end in .vercel.app.

If the page loads but looks unstyled, check that your style.css file is saved in the same folder as index.html. The <link> tag in your HTML needs to find style.css at the same level.

Help me fix my Vercel preview deployment.

Understand what happened

What is a preview deployment?

When you ran vercel, the CLI uploaded your HTML and CSS files, assigned them a unique URL, and distributed them across Vercel's global CDN (Content Delivery Network). Your site is now served from data centers around the world.

This is a preview deployment. It gives you a unique URL to test and share, but it is separate from your main production URL. Preview deployments let you verify changes before officially going live.

In the next step, you will promote your site to production with a cleaner, permanent URL.

Your portfolio is live on the internet. Next up, you will deploy to production to get a permanent, shareable URL.

Deploy to Production

In the last step, you created a preview deployment and saw your portfolio live for the first time. Now it's time to ship it to production.

Production deployments are the real deal. They give your site a clean, permanent URL that you can share with anyone. They're also what Vercel serves to the world at full speed through its global CDN.

In this step, get ready to:
  • Deploy your portfolio to production with a permanent URL.
  • Share your live URL with anyone on the internet.
  • Practice the edit-and-redeploy workflow for instant updates.
Ship to production

Preview deployments are great for testing, but they use a long, auto-generated URL. Production deployments assign your site a cleaner, permanent URL that stays the same every time you redeploy.

  • Deploy your portfolio to production by running this command in the terminal:
vercel --prod

The CLI uploads your files and outputs a production URL. Copy this URL from the terminal output.

What's different about production?

The vercel command (without --prod) creates a preview deployment with a unique, throwaway URL for testing.

Adding --prod tells Vercel this is the real thing. It assigns your site to your project's permanent production domain, following the pattern your-project-name.vercel.app.

Seeing a permissions or auth error?

Make sure you're still logged in by running vercel whoami. If it shows an error, run vercel login again to re-authenticate.

Also confirm your terminal is still inside the my-portfolio folder. Run pwd (macOS/Linux) or cd (Windows) to check your current directory.

Help me troubleshoot my Vercel production deployment

Visit your production URL
  • Open the production URL from the CLI output in your browser.

Your portfolio is now live at a public URL that anyone in the world can visit. This is your permanent production address.

What should I see?

You should see the same portfolio page you previewed earlier. The content is identical to your preview deployment, but the URL is shorter and cleaner. It follows the pattern your-project-name.vercel.app.

Make a change and redeploy

The real power of this workflow is how fast you can ship updates. Let's prove it by making an edit and redeploying in seconds.

  • Switch back to index.html in your editor.
  • Find the <p class="bio"> paragraph inside the <header> section.
  • Update the text to something personal. For example, change it to describe what you're excited about building.
  • Save index.html.
  • Redeploy your updated site to production by running:
vercel --prod
  • Open your production URL again (or refresh the tab if it's still open).
  • You should see your updated bio text live on the internet.

How fast was that?

You just experienced the edit-and-redeploy workflow. Edit a file, run vercel --prod, and your changes are live in seconds. This same workflow scales to any project you build in the future.

Changes not showing up?

Make sure you saved index.html before running vercel --prod. Unsaved changes in your editor won't be picked up by the CLI.

If the browser still shows old content, try a hard refresh with Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows) to bypass the cache.

Help me figure out why my redeployed changes aren't showing

You've now mastered the complete deployment workflow. Next up is a secret mission where you'll add a dark mode toggle with JavaScript and redeploy to see instant updates.

Secret mission

Add Dark Mode

Your portfolio looks great in light mode, but what about visitors who prefer a darker theme? In this bonus challenge, you'll add an interactive dark mode toggle with JavaScript and redeploy your updated site to production in seconds.

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely locally and deploys to Vercel's free Hobby plan, so there are no ongoing costs. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

  • The my-portfolio local folder (containing index.html, style.css, and script.js).
  • Your Vercel project and its production deployment.
  • The Vercel CLI (installed globally via npm).
  • Your Vercel account (free Hobby plan).
  • Node.js (installed on your machine).

Keep everything running

No action needed. Choose this if you are still actively building on your portfolio or plan to deploy more projects to Vercel.

  • Your site stays live at its production URL on Vercel's free Hobby plan at no cost.
  • Your local files remain on your Desktop for future edits.
  • The Vercel CLI stays available for deploying other projects.
  • Node.js remains installed for any JavaScript or npm-based work.

Pause - I'll come back to this later

Since this project uses Vercel's free Hobby plan, there is nothing to pause for cost reasons. Your deployment stays live at no charge.

  • Your production URL continues to serve your portfolio for free.
  • If you want to hide the site from public access without deleting it, open the Vercel dashboard, select your project, go to Settings, then Deployment Protection, and enable Vercel Authentication on production.
  • You can return and redeploy anytime by navigating back to your my-portfolio folder and running vercel --prod.

Delete - I don't want to use this again

Remove all project resources and start fresh. Follow each step below to fully clean up.

  • Delete the Vercel project by running this command from inside your my-portfolio folder:
vercel project rm

The CLI will ask you to confirm by typing the project name. This removes your deployment and the production URL permanently.

  • Delete the local project folder. On macOS or Linux, run:
cd ~/Desktop
rm -rf my-portfolio
  • On Windows, run:
cd ~\Desktop
rmdir /s /q my-portfolio
  • Uninstall the Vercel CLI by running:
npm uninstall -g vercel
  • Delete your Vercel account (optional). Go to vercel.com/account. Scroll to the bottom of the page and click Delete Personal Account. Confirm the deletion. This is permanent and removes all projects and deployments.
  • Uninstall Node.js (optional). On Windows, go to Settings, then Apps, and uninstall Node.js from the list. On macOS, if you installed via the .pkg installer, you can remove the binary at /usr/local/bin/node. Only do this if you no longer need Node.js for other projects.

Nice Work!

Nice Work!

You just took a website from local files to a live public URL using the Vercel CLI. Your portfolio is now hosted on a global CDN that anyone in the world can visit.

You've learned how to:

  • Build a portfolio page with HTML and CSS, structured with a container layout and styled project cards.
  • Deploy to the internet using the Vercel CLI, creating both preview deployments for testing and production deployments for your public URL.
  • Use the edit-and-redeploy workflow to ship updates to your live site in seconds from the terminal.
  • Added a dark mode toggle with JavaScript and localStorage persistence, then redeployed to see instant updates on production.

Ready to quiz yourself?