Skip to main content

​
Quick Start

Get Jowy Portfolio up and running on your local machine in just a few minutes. This guide covers the essential steps to start the development server.
This quick start guide gets you running with minimal configuration. For production deployment and advanced features, see the Installation guide.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18.0 or higher
  • npm, yarn, or pnpm package manager
  • Git for cloning the repository

​
Setup Steps

1

Clone the Repository

Clone the Jowy Portfolio repository from GitHub:
git clone https://github.com/mrcl29/jowy-portfolio.git
cd jowy-portfolio
2

Install Dependencies

Install all required packages using your preferred package manager:
npm install
This will install all dependencies defined in package.json, including:
  • Astro framework
  • TailwindCSS for styling
  • TypeScript for type safety
  • Vercel Analytics and Speed Insights
3

Configure Environment Variables

Create a .env file in the project root with your API credentials:
# Spotify API (Required for music features)
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# SoundCloud API (Required for track listings)
SOUNDCLOUD_CLIENT_ID=your_soundcloud_client_id

# YouTube API (Required for video playlists)
YOUTUBE_API_KEY=your_youtube_api_key

# Google Calendar API (Optional - for events)
GOOGLE_CALENDAR_API_KEY=your_google_calendar_key
GOOGLE_CALENDAR_ID=your_calendar_id
Without API credentials, some features will not work. At minimum, configure Spotify and SoundCloud APIs to see core functionality.

​
Getting API Credentials

Spotify:
  1. Visit Spotify Developer Dashboard
  2. Create a new app
  3. Copy the Client ID and Client Secret
SoundCloud:
  1. Visit SoundCloud Developers
  2. Register a new app
  3. Copy the Client ID
YouTube:
  1. Go to Google Cloud Console
  2. Enable YouTube Data API v3
  3. Create API credentials
4

Start the Development Server

Launch the Astro development server:
npm run dev
The server will start with the following configuration:
// astro.config.mjs:14-17
server: {
  host: true,  // Binds to 0.0.0.0 for network access
  port: 4321,
},
You should see output similar to:
🚀 astro v5.15.9 started in 243ms

┃ Local    http://localhost:4321/
┃ Network  http://192.168.1.x:4321/
5

Open in Browser

Navigate to http://localhost:4321 in your web browser.You should see the Jowy Portfolio landing page with three main sections:
  • DJ - Purple neon theme (#6113C9)
  • JOWY (Producer) - Bronze neon theme (#B57B45)
  • Sound Designer - Green neon theme (#1d6d30)

​
Verify the Setup

After starting the development server, verify that key features are working:

​
Check API Integration

The application fetches data at build time through server-side services. Check the console for any API errors: 
// src/server/services/spotify/auth.ts:15-20
export async function getSpotifyToken(): Promise<string> {
  // 1. Check cache first
  const cachedToken = getFromCache<string>(TOKEN_CACHE_KEY);
  if (cachedToken) {
    return cachedToken;
  }
  // 2. Fetch new token if cache expired
  // ...
}
If configured correctly, you’ll see API responses cached in memory.

​
Test Internationalization

Switch between languages using the language selector:
  • Default: Spanish (/)
  • English: /en/
The routing is configured in astro.config.mjs:21-28: 
i18n: {
  defaultLocale: "es",
  locales: ["es", "en"],
  routing: {
    prefixDefaultLocale: false,
    redirectToDefaultLocale: true,
  },
}

​
Verify Dark Mode

The application initializes in dark mode by default. Check that the neon glow effects are visible on navigation elements.

​
Common Issues

If another process is using port 4321, you can change it in astro.config.mjs:
server: {
  host: true,
  port: 3000,  // Use any available port
}
Double-check your .env file:
  • Ensure there are no extra spaces
  • Verify credentials are correct
  • Restart the dev server after changing .env
Example of proper formatting:
SPOTIFY_CLIENT_ID=abc123xyz
SPOTIFY_CLIENT_SECRET=def456uvw
If you see import errors, try:
# Clear node_modules and reinstall
rm -rf node_modules
npm install
Or if using pnpm:
pnpm store prune
pnpm install
The project uses strict TypeScript. If you see type errors, ensure you’re using Node.js 18+:
node --version  # Should be v18.0.0 or higher

​
Development Commands

Key commands defined in package.json:5-9: 
{
  "scripts": {
    "dev": "astro dev --host",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}
  • npm run dev - Start development server with hot reload
  • npm run build - Build for production (outputs to dist/)
  • npm run preview - Preview production build locally

​
Next Steps

Now that you have Jowy Portfolio running locally:

Installation Guide

Learn about production deployment, environment configuration, and advanced features

Architecture Deep Dive

Understand the BaseFetcher pattern, caching system, and service layer
For production deployment to Vercel, see the detailed Installation guide which covers environment variables, build configuration, and CI/CD setup.

Build docs developers (and LLMs) love

Get started for freeTalk to us