This content originally appeared on DEV Community and was authored by Michael Uzukwu
When I set out to recreate the Vue.js documentation using Astro Starlight a month ago, I had two main goals — keep it static, and make it accessible online with minimal setup.
At first, I figured GitHub Pages would do the trick — but I ran into a few headaches pretty quickly. Then I made the switch to Vercel, and it turned out to be one of the best decisions for this project.
In this post, I’ll walk you through how I deployed my Astro-powered documentation site using Vercel, and why it’s now my preferred tool for static site hosting.
Why Vercel for Static Sites?
So, what made me go with Vercel? Here’s what really convinced me before I even got to the setup:
- Instant GitHub integration – Deploy right from your repository with no CLI fuss.
- Global CDN out of the box – Blazing-fast performance for static assets.
- Custom domain support – Easy setup and automatic HTTPS
- Automatic deploy previews – See what each branch or PR looks like live.
- Zero-config setup – Frameworks like Astro are detected automatically.
- Free tier available – Ideal for personal projects and experimentation.
Project Context: Rebuilding Vue.js Docs with Astro Starlight
As part of Product Documentation Cohort-1 of the Technical Writing Mentorship Program (TWMP), I recreated the Vue.js documentation using Astro Starlight — a lightweight static site generator that focuses on performance, markdown-based content, and great developer experience.
The idea was to restructure and improve the official Vue.js docs — but powered by Astro.
Since the content was static, with no backend or dynamic data, this made it perfect for static deployment — no server needed, just HTML, CSS, and JavaScript.
Step-by-Step: Deploying an Astro Site on Vercel
Prerequisites
Make sure you have:
- A GitHub account with your static site code pushed to a repo.
Figure 1: Ensure your static site code (like this Vue.js repo) is pushed to GitHub before importing it into Vercel.
- A Vercel account (you can sign up with GitHub for seamless integration).
1. Import Your Project into Vercel
Figure 2: Vercel automatically detects Astro as the framework and applies default build and output settings.
- Go to vercel.com/dashboard
- Click “Add New Project”
- Select your GitHub repository (Vercel may ask for GitHub access the first time).
Vercel will auto-detect Astro as the framework and pre-fill the build command (astro build) and output directory (dist).
2. Configure the Settings
You can usually go with the defaults:
Framework: Astro
Build command: astro build
Output directory: dist
3. Deploy
Click the “Deploy” button.
Vercel will:
- Clone your repo
- Install dependencies
- Build the project
- Host the
dist/output on its CDN
After a minute or so, you’ll get a unique .vercel.app URL to view your live site.
Figure 3: Vercel deployment success screen. Once the build completes, your site is live on a unique .vercel.app URL.
Setting Up a Custom Domain (Optional but Awesome)
If you want a branded URL:
- In the project dashboard, go to the Domains tab
- Click “Add” to connect your custom domain
- Update your domain’s DNS to point to Vercel’s servers
HTTPS is auto-enabled with Let’s Encrypt — no extra setup needed.
Figure 4: A quick look at the domain setup screen on Vercel.
Why I Switched from GitHub Pages to Vercel
GitHub Pages is great for simple projects, but I ran into issues like:
- Having to manually build and push the
dist/folder to agh-pagesbranch - Problems with routing (e.g., missing
_redirectssupport) - Extra configuration for Astro and Starlight projects
With Vercel, all that friction disappeared.
Tips & Best Practices
- Add
.vercel/to your.gitignore - Use Vercel’s dashboard to securely manage environment variables
- Enable analytics (available on paid plans)
- 👥 Working in a team? Preview deployments make collaboration smooth and safe.
Conclusion
Deploying with Vercel made the process incredibly smooth. From GitHub integration to instant deployment and live previews, it handled everything I needed for a modern static site — no DevOps headaches.
Whether you’re building documentation, blogs, or full sites using Astro, Next.js, or even plain HTML — Vercel is a solid choice.
🔗 Want to see the live site? Check it out here: https://vue-js-nine-rouge.vercel.app/
💻 Project repository:
https://github.com/Mike-4-prog/vue.js
(Note: The documentation is still a work in progress, with more pages and improvements coming soon!)
Have you tried deploying with Vercel? Got stuck with GitHub Pages too?
💬 Feel free to drop your questions or share your experience in the comments!
This content originally appeared on DEV Community and was authored by Michael Uzukwu
Michael Uzukwu | Sciencx (2025-07-08T21:53:49+00:00) From Code to Live in Minutes: Deploying My Astro Starlight Static Site on Vercel.. Retrieved from https://www.scien.cx/2025/07/08/from-code-to-live-in-minutes-deploying-my-astro-starlight-static-site-on-vercel/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.