Skip to main content
This guide provides comprehensive instructions for installing and configuring your Astro Portfolio v3. Follow these steps to set up your development environment and understand the project structure.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 18.14.1 or higherDownload from nodejs.org

Package Manager

pnpm (recommended), npm, or yarnInstall pnpm: npm install -g pnpm

Git

Latest stable versionRequired for cloning the repository

Text Editor

VS Code recommendedWith Astro extension for best experience
This project requires Node.js 18.14.1 or higher to support Astro v5 and modern JavaScript features.

​
Installation Methods

1

Clone the repository

Start by cloning the repository from GitHub:
git clone https://github.com/yourusername/astro-portfolio.git
cd astro-portfolio
Alternatively, you can fork the repository first to create your own copy:
  1. Visit the repository on GitHub
  2. Click the “Fork” button
  3. Clone your forked repository
git clone https://github.com/YOUR_USERNAME/astro-portfolio.git
cd astro-portfolio
2

Install dependencies

Install all required packages using your preferred package manager:
pnpm install
This will install the following core dependencies:
  • Astro v5.16.15 - The web framework
  • Tailwind CSS v4.1.18 - Utility-first CSS framework
  • @astrojs/cloudflare v12.6.12 - Cloudflare Pages adapter
  • @astrojs/sitemap v3.7.0 - Automatic sitemap generation
  • astro-expressive-code v0.41.6 - Beautiful code syntax highlighting
  • sharp v0.34.5 - High-performance image processing
The installation process may take 2-3 minutes depending on your internet connection and system performance.
3

Environment setup

Create your environment configuration file:
cp .env.example .env
Open the .env file and configure the following variables:
.env
# Beehiiv Newsletter API Configuration
# Get your API credentials from https://developers.beehiiv.com/
BEEHIIV_PUBLICATION_ID=your_publication_id_here
BEEHIIV_API_KEY=your_api_key_here

# Google Tag Manager for Analytics
# Get your GTM ID from https://tagmanager.google.com/
GTM_ID=your_google_tag_manager_id_here

​
Environment Variables Explained

VariableRequiredDescription
BEEHIIV_PUBLICATION_IDOptionalYour Beehiiv publication ID for newsletter integration
BEEHIIV_API_KEYOptionalYour Beehiiv API key for newsletter subscriptions
GTM_IDOptionalGoogle Tag Manager ID for analytics tracking
Never commit your .env file to version control! The .gitignore file is already configured to exclude it, but always double-check before pushing code.
All environment variables are optional. The site will function without them, but newsletter subscriptions and analytics tracking will be disabled.
4

Verify installation

Confirm everything is set up correctly by starting the development server:
pnpm dev
You should see output similar to:
astro v5.16.15 ready in 1234 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose
Open your browser and navigate to http://localhost:4321 to see your portfolio.

​
Project Structure Overview

Understanding the project structure will help you navigate and customize your portfolio: 
/
├── .github/                    # GitHub workflows and configuration
├── public/                     # Static assets (images, fonts, etc.)
│   └── projects/              # Project screenshots and media
├── src/
│   ├── assets/                # Optimized image assets
│   │   ├── about-image.webp
│   │   └── lewis-profile-no-bg.webp
│   ├── components/            # Reusable Astro & React components
│   │   ├── home/             # Homepage sections
│   │   ├── navs/             # Navigation components
│   │   ├── shared/           # Shared components
│   │   └── ui/               # UI component library
│   ├── content/              # Content Collections (markdown)
│   │   ├── about/           # About page content
│   │   ├── advisory/        # Advisory services
│   │   ├── blog/            # Blog posts (30+ articles)
│   │   ├── operatingNotes/  # Operating notes
│   │   ├── projects/        # Project case studies
│   │   └── sponsors/        # Sponsor information
│   ├── data/                 # JSON data files
│   │   ├── books.json       # Reading list
│   │   ├── desktop-setup.json
│   │   ├── experience.json  # Work experience
│   │   ├── socials.json     # Social media links
│   │   └── tech-stack.json  # Tools and technologies
│   ├── layouts/              # Page layouts
│   │   ├── BlogLayout.astro
│   │   └── Layout.astro
│   ├── pages/                # File-based routing
│   │   ├── index.astro      # Homepage
│   │   ├── about.astro
│   │   ├── projects.astro
│   │   ├── blog/
│   │   └── api/             # API endpoints
│   ├── lib/                  # Utility functions
│   ├── styles/               # Global CSS
│   ├── utils/                # Helper utilities
│   └── config.ts             # Site configuration
├── astro.config.mjs          # Astro configuration
├── tailwind.config.js        # Tailwind CSS configuration
├── tsconfig.json             # TypeScript configuration
└── package.json              # Project dependencies

​
Key Directories

src/content/

Content CollectionsMarkdown files for blog posts, projects, and other content. Uses Astro’s Content Collections API.

src/components/

ComponentsReusable Astro and React components including UI library, navigation, and page sections.

src/pages/

RoutesFile-based routing. Each file becomes a route. Includes dynamic routes for blog posts.

src/data/

JSON DataStructured data files for experience, books, tech stack, and social links.

​
Configuration Files

​
astro.config.mjs

The main Astro configuration file includes:
astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';
import expressiveCode from 'astro-expressive-code';
import sitemap from '@astrojs/sitemap';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
  site: 'https://lewiskori.com',
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr', 'de'],
  },
  // ... more configuration
});
Key configuration features:
  • Output mode: Server-side rendering (SSR) with Cloudflare adapter
  • i18n support: Multi-language infrastructure (English, Spanish, French, German)
  • Integrations: Expressive Code for syntax highlighting, Sitemap generation
  • Vite plugins: Tailwind CSS v4 integration

​
src/config.ts

Site-wide configuration for personal information:
src/config.ts
export const siteConfig = {
  name: 'Lewis Kori',
  title: 'Lewis Kori – Building Products, Systems, and Leverage',
  url: 'https://lewiskori.com',
  description: 'Entrepreneur and product builder...',
  location: 'Kenya',
  email: '[email protected]',
  // ... more settings
};
Update src/config.ts with your own personal information, social links, and site metadata before deploying.

​
Common Installation Issues

Module not found errors: Make sure you’ve run pnpm install and all dependencies are installed correctly. Try deleting node_modules and running install again.
Port 4321 already in use: If port 4321 is occupied, you can specify a different port: pnpm dev --port 3000
Sharp installation fails: On some systems, sharp may require additional build tools. Install build tools for your OS:
  • Windows: npm install --global windows-build-tools
  • macOS: Install Xcode Command Line Tools
  • Linux: Install build-essential package

​
Next Steps

Now that you have everything installed:

Customize Your Site

Update content, styling, and components to make it your own

Configure Integrations

Set up newsletter, analytics, and other third-party services

Add Content

Learn how to create blog posts, projects, and other content

Deploy

Deploy your portfolio to Cloudflare Pages or other platforms

Build docs developers (and LLMs) love

Get started for freeTalk to us