Installation

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

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:

Visit the repository on GitHub
Click the “Fork” button
Clone your forked repository

git clone https://github.com/YOUR_USERNAME/astro-portfolio.git
cd astro-portfolio

Install dependencies

Install all required packages using your preferred package manager:

pnpm install

npm install

yarn 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.

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

Variable	Required	Description
`BEEHIIV_PUBLICATION_ID`	Optional	Your Beehiiv publication ID for newsletter integration
`BEEHIIV_API_KEY`	Optional	Your Beehiiv API key for newsletter subscriptions
`GTM_ID`	Optional	Google 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.

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

Get Started

Core Features

Content Management

Customization

Deployment

Prerequisites

Node.js

Package Manager

Git

Text Editor

Installation Methods

Environment Variables Explained

Project Structure Overview

Key Directories

src/content/

src/components/

src/pages/

src/data/

Configuration Files

astro.config.mjs

src/config.ts

Common Installation Issues

Next Steps

Customize Your Site

Configure Integrations

Add Content

Deploy

​Prerequisites

Node.js

Package Manager

Git

Text Editor

​Installation Methods

​Environment Variables Explained

​Project Structure Overview

​Key Directories

src/content/

src/components/

src/pages/

src/data/

​Configuration Files

​astro.config.mjs

​src/config.ts

​Common Installation Issues

​Next Steps

Customize Your Site

Configure Integrations

Add Content

Deploy

Prerequisites

Installation Methods

Environment Variables Explained

Project Structure Overview

Key Directories

Configuration Files

astro.config.mjs

src/config.ts

Common Installation Issues

Next Steps