Installation

This guide covers installing Podcast Framework in detail, including system requirements, manual setup, and troubleshooting.

System Requirements

Required

Node.js 18+ - Download
npm 9+ or pnpm 8+ or yarn 1.22+
Git - Download

Account Setup

You’ll need accounts for:

Sanity (free tier) - Required for CMS
GitHub (free) - Recommended for deployment
Cloudflare (free tier) - Recommended for hosting

Optional services:

ConvertKit (free tier) - Newsletter signups
Resend (free tier) - Contribution emails
Google Analytics (free) - Site analytics
Sentry (free tier) - Error tracking

Installation Methods

Method 1: CLI (Recommended)

The fastest way to get started:

# Create new project
npm create @rejected-media/podcast-framework my-podcast

# Navigate to project
cd my-podcast

Interactive Prompts:

The CLI will ask for:

Description (optional with default) - Press Enter to use: "my-podcast - A podcast built with @podcast-framework"

That’s the only prompt! All features are enabled by default.

CLI Flags:

# Skip all prompts (use defaults)
npm create @rejected-media/podcast-framework my-podcast --yes

# Use specific template (future feature)
npm create @rejected-media/podcast-framework my-podcast --template advanced

# Skip npm install
npm create @rejected-media/podcast-framework my-podcast --skip-install

What You Get:

✅ Complete project structure
✅ All features enabled (newsletter, search, contributions, transcripts)
✅ Configuration files (podcast.config.js, astro.config.mjs, .env.template)
✅ Ready for Sanity CMS setup

Method 2: Clone Template

Clone the template repository directly:

# Clone template
git clone https://github.com/rejected-media/podcast-template.git my-podcast

# Navigate to project
cd my-podcast

# Remove git history
rm -rf .git
git init

# Install dependencies
npm install

Method 3: GitHub Template

Use GitHub’s template feature:

Go to podcast-template
Click “Use this template”
Click “Create a new repository”
Name your repository
Click “Create repository”
Clone your new repository:

git clone https://github.com/your-username/your-podcast.git
cd your-podcast
npm install

Method 4: Manual Setup

For advanced users who want full control:

# Create new Astro project
npm create astro@latest my-podcast

# Navigate to project
cd my-podcast

# Install Podcast Framework packages
npm install @rejected-media/podcast-framework-core @rejected-media/podcast-framework-sanity-schema

# Install peer dependencies
npm install @sanity/client @sanity/cli

# Install Tailwind CSS
npx astro add tailwind

# Create required directories
mkdir -p src/pages/{episodes,guest,guests,api}
mkdir -p src/components
mkdir -p sanity/schemas

Sanity CMS Setup

Step 1: Create Sanity Project

Create a project at sanity.io/manage:

Click “Create project”
Enter project name: my-podcast
Choose “Production” dataset
Save your Project ID from the project settings

Step 2: Add Project ID

Update sanity.config.ts with your project ID:

export default defineConfig({
  name: 'default',
  title: 'my-podcast',

  projectId: 'abc123xyz',  // ← Replace with your actual Project ID
  dataset: 'production',

  // ...
});

Step 3: Configure Environment Variables

Already generated by CLI! Just update with your values in .env:

PUBLIC_SANITY_PROJECT_ID="abc123xyz"  # Your Project ID from Step 1
PUBLIC_SANITY_DATASET="production"
PUBLIC_SANITY_API_VERSION="2024-01-01"

SANITY_TOKEN="your_write_token"  # Optional: for RSS import

That’s it! The schemas are already configured in sanity/schemas/index.ts.

Environment Configuration

Step 1: Create .env File

cp .env.template .env

Step 2: Required Variables

Add these required variables to .env:

# Sanity CMS (Required)
PUBLIC_SANITY_PROJECT_ID="your-project-id"
PUBLIC_SANITY_DATASET="production"
PUBLIC_SANITY_API_VERSION="2024-01-01"

# Site Configuration (Required)
PUBLIC_SITE_URL="http://localhost:4321"

Step 3: Optional Variables

Add optional services as needed:

# Newsletter (Optional - ConvertKit)
CONVERTKIT_API_KEY="your-convertkit-api-key"
CONVERTKIT_FORM_ID="your-form-id"

# Contributions (Optional - Resend)
RESEND_API_KEY="your-resend-api-key"
NOTIFICATION_EMAIL="[email protected]"

# Analytics (Optional - Google Analytics)
PUBLIC_GA_MEASUREMENT_ID="G-XXXXXXXXXX"

# Error Tracking (Optional - Sentry)
SENTRY_DSN="your-sentry-dsn"

# RSS Import (Optional)
RSS_FEED_URL="https://your-podcast.com/feed.xml"

Verify Installation

Check Dependencies

npm list @rejected-media/podcast-framework-core

Should output:

[email protected]
└── @rejected-media/[email protected]

Start Dev Server

npm run dev

Visit http://localhost:4321 - you should see your podcast homepage!

Start Sanity Studio

In a new terminal:

npm run dev:sanity

Visit http://localhost:3333 - you should see Sanity Studio!

Package Versions

Current stable versions (generated by CLI):

{
  "dependencies": {
    "@rejected-media/podcast-framework-cli": "^0.1.20",
    "@rejected-media/podcast-framework-core": "^0.1.2",
    "@rejected-media/podcast-framework-sanity-schema": "^1.1.0",
    "@astrojs/tailwind": "^5.1.0",
    "astro": "^5.1.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "resend": "^4.0.0",
    "sanity": "^4.0.0",
    "@sanity/client": "^6.0.0",
    "@sanity/vision": "^3.0.0",
    "styled-components": "^6.1.15",
    "tailwindcss": "^3.4.0"
  }
}

TypeScript Configuration

Podcast Framework requires TypeScript with strict mode. Your tsconfig.json should include:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "react"
  }
}

Build Configuration

Your astro.config.mjs should include:

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [tailwind()],
  output: 'static',
  build: {
    inlineStylesheets: 'auto',
  },
});

Troubleshooting

Installation Issues

npm install fails

Try using a different package manager:

# Try pnpm
npm install -g pnpm
pnpm install

# Or try yarn
npm install -g yarn
yarn install

“ERESOLVE unable to resolve dependency tree”

Use the legacy peer deps flag:

npm install --legacy-peer-deps

“Module not found: @rejected-media/podcast-framework-core”

Make sure the package is installed:

npm install @rejected-media/podcast-framework-core

Sanity Issues

”Project not found”

Check your .env file - PUBLIC_SANITY_PROJECT_ID must match your Sanity project:

# List your Sanity projects
npx sanity projects list

“Dataset not found”

Create the production dataset:

cd sanity
npx sanity dataset create production
cd ..

“Schema deploy failed”

Make sure you’re in the sanity directory:

cd sanity
npx sanity schema deploy
cd ..

Build Issues

”Build failed: Type error”

Check your Node.js version:

node --version  # Must be v18.0.0 or higher

Update if needed:

# Using nvm
nvm install 18
nvm use 18

“Cannot find module ’…’”

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

“Out of memory” during build

Increase Node.js memory:

NODE_OPTIONS="--max-old-space-size=4096" npm run build

Port Conflicts

Port 4321 already in use

Change the dev server port:

npm run dev -- --port 3000

Port 3333 already in use (Sanity)

Change Sanity’s port:

cd sanity
npx sanity dev --port 3334
cd ..

IDE Setup

VS Code

Recommended extensions:

{
  "recommendations": [
    "astro-build.astro-vscode",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint"
  ]
}

Settings

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[astro]": {
    "editor.defaultFormatter": "astro-build.astro-vscode"
  }
}

Updating Podcast Framework

Update Core Package

npm update @rejected-media/podcast-framework-core

Update All Packages

npm update

Check for Updates

npm outdated

Breaking Changes

Always check the GitHub releases page before updating to a new major version.

Next Steps

Now that you have Podcast Framework installed:

Project Structure - Understand the file layout
Configuration - Configure your site
Quick Start - Build your first page
Components - Learn about the components

Getting Help

GitHub Discussions - Ask questions
GitHub Issues - Report installation problems
Quick Start - Simplified guide