Quick Start

Quick Start

Get a production-ready podcast website running in under 10 minutes. This guide will walk you through creating a new podcast site from scratch.

Prerequisites

Before you begin, make sure you have:

• Node.js 18+ installed (download here)
• Git installed (download here)
• A Sanity account (free - sign up at sanity.io)

Time estimate

This entire guide takes 5-10 minutes from start to finish.

Step 1: Create Project

Use the Podcast Framework CLI to create a new project:

npm create @rejected-media/podcast-framework my-podcast

The CLI will prompt for a short description (or press Enter to use the default). That’s it!

Skip prompts

Use the --yes flag to skip all prompts and use defaults:

npm create @rejected-media/podcast-framework my-podcast --yes

This will:

• ✅ Create project structure
• ✅ Generate configuration files
• ✅ Set up with all features enabled (newsletter, search, contributions)
• ✅ Create a .env.template file

Note

All features are enabled by default. You can customize them later in podcast.config.js.

Step 2: Navigate to Project

cd my-podcast

Step 3: Create Sanity Project

Create a new Sanity project at sanity.io/manage:

1. Click “Create project”
2. Enter project name: my-podcast
3. Choose “Production” dataset
4. Write down your Project ID - you’ll need it next!

Project ID Location

After creating the project, you’ll see your Project ID in the project settings or in the URL.

Step 4: Add Your 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',

  // ...
});

Also create a .env file:

cp .env.template .env

Add your project ID to .env:

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

SANITY_TOKEN="your_write_token"  # Optional: for RSS import

Important

Use PUBLIC_ prefix for Sanity variables so they’re accessible in the browser. The .env.template includes examples for all optional services (Resend, ConvertKit, etc). Add these later!

Step 5: Install Dependencies

npm install

Step 6: Start Development Servers

Start both the Astro dev server and Sanity Studio:

# Terminal 1: Astro dev server
npm run dev

# Terminal 2: Sanity Studio (in a new terminal)
npm run dev:sanity

Your podcast site is now running at:

• Website: http://localhost:4321
• Sanity Studio: http://localhost:3333

First Time Setup

The first time you run npm run dev:sanity, Sanity Studio will deploy your schemas automatically.

Step 7: Add Your First Episode

1. Open Sanity Studio at http://localhost:3333
2. Click “Podcast” in the sidebar
3. Fill in your podcast information:
   • Name
   • Tagline
   • Description
   • Links (Spotify, Apple Podcasts, etc.)
4. Click “Publish”
5. Click “Episode” in the sidebar
6. Click “Create new Episode”
7. Fill in episode details:
   • Title
   • Episode number
   • Publish date
   • Duration
   • Description
   • Links (Spotify, Apple, YouTube)
8. Click “Publish”

RSS Import

Have existing episodes? Import them from your RSS feed:

# Add your RSS feed URL to .env
echo 'RSS_FEED_URL="https://feeds.transistor.fm/your-show"' >> .env

# Import all episodes
npm run import:episodes

The import will:

• Fetch all episodes from your RSS feed
• Create Episode documents in Sanity with full metadata
• Download and upload cover images
• Skip episodes that already exist (safe to run multiple times)

Step 8: Add Your First Guest (Optional)

1. Click “Guest” in the sidebar
2. Click “Create new Guest”
3. Fill in guest details:
   • Name
   • Slug (auto-generated from name)
   • Bio
   • Photo (upload)
   • Social links (Twitter, LinkedIn, Website)
4. Click “Publish”
5. Go back to your episode
6. Add the guest to the episode’s “Guests” field
7. Click “Publish”

Step 9: Customize Your Theme

1. In Sanity Studio, click “Theme” in the sidebar
2. Customize colors:
   • Primary color (links, buttons)
   • Background color
   • Text colors
3. Select fonts (Google Fonts integration)
4. Choose layout options
5. Click “Publish”

Refresh your website to see the changes!

What You’ve Built

In 10 minutes, you now have:

• ✅ Beautiful homepage with featured episodes
• ✅ Episode archive with search functionality
• ✅ Individual episode pages with Spotify embeds
• ✅ Guest directory with photos and bios
• ✅ Guest profile pages with all their episodes
• ✅ About page (CMS-configurable)
• ✅ Newsletter signup (ready for ConvertKit integration)
• ✅ Contribution form (ready for Resend integration)
• ✅ Custom theme (your colors and fonts)
• ✅ Fully responsive (mobile, tablet, desktop)
• ✅ Type-safe (TypeScript with strict mode)
• ✅ SEO optimized (meta tags, sitemaps)

Next Steps

Now that your site is running, you can:

1. Deploy to production - Go live in 5 minutes
2. Customize components - Make it yours
3. Set up email - Enable newsletter and contributions
4. Add analytics - Track your visitors

Common Next Steps

Import Existing Episodes

If you have an existing podcast RSS feed:

# Set RSS_FEED_URL in .env
echo 'RSS_FEED_URL="https://feeds.transistor.fm/your-show"' >> .env

# Import episodes (includes images)
npm run import:episodes

# Or use command directly with options
podcast-framework import-rss --feed https://feeds.transistor.fm/your-show --verbose

Supported podcast hosts: Transistor (more coming soon)

Set Up Newsletter

1. Create a ConvertKit account (free)
2. Get your API key and Form ID
3. Add to .env:

CONVERTKIT_API_KEY="your-api-key"
CONVERTKIT_FORM_ID="your-form-id"

Newsletter signups now work!

Set Up Contributions

1. Create a Resend account (free tier available)
2. Get your API key
3. Add to .env:

RESEND_API_KEY="your-api-key"
NOTIFICATION_EMAIL="[email protected]"

Contribution form now sends emails!

Deploy to Production

Deploy to Cloudflare Pages in 5 minutes:

# Build the site
npm run build

# Deploy (follow prompts)
npx wrangler pages deploy dist

Or use the Cloudflare Pages dashboard for automatic deployments on git push.

Getting Help

Stuck? Here’s where to get help:

• GitHub Discussions - Ask questions
• GitHub Issues - Report bugs
• Documentation - Read the full docs
• Examples - See example projects

Troubleshooting

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

Make sure dependencies are installed:

npm install

“Sanity client error: Project not found”

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

”Build failed: Type error”

Make sure you’re using Node.js 18 or higher:

node --version  # Should show v18.0.0 or higher

Episode images not showing

Images must be uploaded to Sanity. In Sanity Studio:

1. Go to your episode
2. Click the “Cover Image” field
3. Upload an image
4. Click “Publish”

What’s Next?

Continue learning:

• Project Structure - Understand the file layout
• Configuration - Configure your site
• Components - Learn about the components
• Deployment - Deploy to production

---

🎉 Congratulations! You’ve created your first podcast website with Podcast Framework. Now go make it yours!