Skip to main content

​
Prerequisites

Before installing the template, ensure your system meets these requirements:

​
Required Software

Node.js is the JavaScript runtime required to run Astro and build your portfolio.Check your version:
node --version
Install or update:
  • Download from nodejs.org
  • Or use a version manager like nvm: 
    nvm install 18
nvm use 18
Node.js 16 and below are not supported. You must use version 18 or higher.
This template uses pnpm as its package manager for faster, more efficient dependency management.Check your version:
pnpm --version
Install pnpm:
npm install -g pnpm
Or use Corepack (comes with Node.js 16.13+):
corepack enable
corepack prepare [email protected] --activate
The template specifies [email protected] in package.json. While newer versions should work, this version is tested and guaranteed to work.
Git is needed to clone the repository and manage version control.Check if installed:
git --version
Install Git:
  • Download from git-scm.com
  • Or use your system’s package manager: 
    # macOS (with Homebrew)
brew install git

# Ubuntu/Debian
sudo apt install git

# Windows (with Chocolatey)
choco install git

​
Installation Methods

This is the recommended method for most users.
1

Clone the repository

git clone https://github.com/vaibhav227/portfolio.git my-portfolio
cd my-portfolio
Replace my-portfolio with your preferred directory name.
2

Install dependencies

pnpm install
This will install all required packages defined in package.json:
  • Core: astro, react, react-dom
  • Integrations: @astrojs/react, @astrojs/tailwind, @astrojs/mdx
  • UI: tailwindcss, shadcn components, lucide-react icons
  • Utilities: typescript, sharp, motion
The installation typically takes 1-2 minutes depending on your internet speed.
3

Start development server

pnpm run dev
You should see output like:
astro v4.16.16 ready in 431 ms

┃ Local    http://localhost:4312/
┃ Network  use --host to expose
Open http://localhost:4312 in your browser.

​
Method 2: Fork and Clone

If you want to make it your own repository on GitHub:
1

Fork the repository

  1. Visit github.com/vaibhav227/portfolio
  2. Click the “Fork” button in the top right
  3. Choose your GitHub account as the destination
2

Clone your fork

git clone https://github.com/YOUR_USERNAME/portfolio.git my-portfolio
cd my-portfolio
Replace YOUR_USERNAME with your GitHub username.
3

Install and run

pnpm install
pnpm run dev

​
Method 3: Download as ZIP

If you prefer not to use Git:
1

Download the ZIP

  1. Go to github.com/vaibhav227/portfolio
  2. Click the green “Code” button
  3. Select “Download ZIP”
  4. Extract the ZIP file to your desired location
2

Navigate and install

cd path/to/extracted/portfolio
pnpm install
pnpm run dev

​
Project Structure

After installation, your project structure will look like this: 
portfolio/
├── public/                    # Static assets (images, fonts, etc.)
│   └── myprofile.webp        # Your profile picture
├── src/
│   ├── components/
│   │   ├── sections/         # Homepage card sections
│   │   │   ├── IntroCard.astro
│   │   │   ├── AboutMe.astro
│   │   │   ├── Projects.astro
│   │   │   └── ...
│   │   ├── ui/               # Shadcn UI components
│   │   └── Card.astro        # Reusable card wrapper
│   ├── content/              # Content collections
│   │   ├── config.ts         # Content schemas
│   │   ├── profileData.ts    # Your profile data
│   │   ├── projects/         # Project MDX files
│   │   ├── posts/            # Blog post MDX files
│   │   ├── experiences/      # Experience MDX files
│   │   └── books/            # Book MDX files
│   ├── layouts/              # Page layouts
│   │   ├── BaseLayout.astro
│   │   ├── MDXLayout.astro
│   │   └── ...
│   ├── pages/                # File-based routing
│   │   ├── index.astro       # Homepage
│   │   ├── projects/
│   │   ├── posts/
│   │   └── ...
│   └── lib/                  # Utilities and constants
├── astro.config.ts           # Astro configuration
├── tailwind.config.ts        # Tailwind configuration
├── tsconfig.json             # TypeScript configuration
└── package.json              # Dependencies and scripts

​
Available Scripts

The template includes these npm scripts in package.json: 
pnpm run dev
# or
pnpm start
# Starts dev server at http://localhost:4312

​
Verification Steps

Verify your installation is working correctly:
1

Check the homepage

Visit http://localhost:4312 and verify:
  • The page loads without errors
  • You see the bento grid layout with multiple cards
  • The intro card displays “Vaibhav Sharma” (this will be your name after customization)
2

Test navigation

Click through the navigation to verify these pages load:
  • /projects - Project listing page
  • /posts - Blog posts page
  • /experiences - Experiences timeline
  • /tags - Tag cloud page
3

Test dark mode

Click the theme toggle (usually in the header) to switch between dark and light modes. Both should work smoothly.
4

Check content collections

Verify that content is loading from the src/content/ directory:
  • Projects appear on the projects page
  • Blog posts are listed
  • Experiences show up correctly
5

Test hot reload

Make a small change to src/content/profileData.ts (like changing the name) and save. The browser should update automatically without a full refresh.

​
Troubleshooting

If port 4312 is already in use, Astro will automatically try the next available port. Check your terminal output for the actual port.To specify a different port:
pnpm run dev -- --port 3000
Make sure pnpm is installed globally:
npm install -g pnpm
Or enable Corepack:
corepack enable
This usually means dependencies weren’t installed correctly. Try:
rm -rf node_modules pnpm-lock.yaml
pnpm install
If you see TypeScript errors in your editor:
  1. Make sure you have the Astro VS Code extension installed
  2. Restart your editor
  3. Run pnpm install to ensure all type definitions are installed
Make sure your images are in the public/ directory. Images in public/ can be referenced with a leading slash:
<img src="/myprofile.webp" alt="Profile" />
If you’re on an M1/M2 Mac and encounter Sharp errors:
pnpm install --force
Or rebuild Sharp:
pnpm rebuild sharp

​
Next Steps

Now that you have the template installed and running:

Quickstart Guide

Follow the quickstart to customize your portfolio

Configuration

Learn about configuration options

Content Management

Understand how to manage your content

Deployment

Deploy your portfolio to production
If you encounter any issues not covered in the troubleshooting section, check the GitHub Issues or open a new issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us