"The fastest way to discover and enjoy podcasts on the web"

Podr revolutionizes podcast discovery with lightning-fast performance and a beautifully crafted user experience. Built for podcast enthusiasts who demand speed, simplicity, and style.

• 🔍 Podcast Discovery - Find trending shows instantly
• ⭐ Curated Collections - Save and organize your favorites
• 🚀 Quick Access - Zero-delay browsing with offline capabilities
• 📱 Any Device - Seamless experience across all screen sizes

• ⚡ Instant Loading - Top podcasts data pre-loaded for zero-wait discovery
• 🔄 Auto-Refresh - Daily automated builds ensure fresh content
• 📦 Optimized Bundles - Lightweight architecture with aggressive caching
• 🛡️ Rock Solid - 99.9% uptime with global CDN delivery

• 📱 Responsive Design - Pixel-perfect on mobile, tablet, and desktop
• � Modern UI - Clean, intuitive interface with smooth animations
• ⚡ Lightning Search - Find any podcast in milliseconds
• ⭐ Smart Favorites - One-click bookmarking with persistent storage

• 🔧 Modern Stack - Preact + TypeScript + cutting-edge tooling
• 🧪 Fully Tested - Comprehensive test suite with 90%+ coverage
• � Security First - CSP headers, HTTPS, and secure dependencies
• 🌐 PWA Ready - Offline capabilities and installable experience

# 📥 Clone the repository
gh repo clone cascadiacollections/podr
# or using git
git clone https://github.com/cascadiacollections/podr.git

# 📂 Navigate to project directory
cd podr

# 📦 Install dependencies
yarn install

# 🚀 Start development server
yarn start

🎉 Success! Open http://localhost:9000 to see Podr in action!

# 1. Start development
yarn start              # Launch dev server

# 2. Make changes
# Edit files in src/ - hot reload active!

# 3. Lint your code
yarn lint               # Check for issues
yarn lint:fix           # Auto-fix problems

# 4. Test your changes
yarn test:watch         # Run tests continuously

# 5. Check code quality
yarn test:coverage      # Ensure coverage targets met

This repository is organized as a monorepo containing the main Podr application and reusable packages:

📦 podr/
├── 📱 src/                           # Main Podr application
│   ├── 🎨 ui/                        # React/Preact components
│   │   ├── 🧪 __tests__/             # Component test suites
│   │   ├── 📱 App.tsx                # Main application shell
│   │   ├── 🔍 Search.tsx             # Podcast search interface
│   │   ├── 📋 List.tsx               # Podcast listing component
│   │   ├── 📄 Result.tsx             # Individual search results
│   │   └── 🛡️ ErrorBoundary.tsx      # Error handling wrapper
│   ├── 🛠️ utils/                     # Shared utilities & helpers
│   │   ├── 🌐 AppContext.tsx         # Global application state
│   │   ├── 🔧 helpers.ts             # Pure utility functions
│   │   └── 🪝 hooks.ts               # Custom React hooks
│   ├── 📝 types/                     # TypeScript type definitions
│   │   └── testing-library__jest-dom.d.ts
│   └── 🎨 app.scss                   # Global styles & variables
└── 📦 packages/                      # Reusable packages
    └── 🔌 webpack-api-inliner-plugin/ # API inlining webpack plugin
        ├── 📖 README.md              # Plugin documentation
        ├── 📝 CHANGELOG.md           # Release notes
        ├── 🔧 index.ts               # Main plugin implementation
        └── 📋 package.json           # Package configuration

• webpack-api-inliner-plugin - A webpack plugin that fetches API data at build time and inlines it for faster initial page rendering

• 🧩 Component-Based - Modular, reusable UI components
• 📱 Mobile-First - Responsive design from ground up
• ⚡ Performance - Code splitting and lazy loading
• 🔒 Type Safety - Comprehensive TypeScript coverage
• 🧪 Test Coverage - Unit and integration testing
• ♿ Accessibility - WCAG 2.1 AA compliance

Experience zero-config development with our containerized environment:

# 🚀 One-click setup in VS Code
code .                  # VS Code will prompt for container reopen

🎁 What's Included:

• ✅ Node.js 24 - Latest LTS with optimal performance
• ✅ Yarn - Fast, reliable package management
• ✅ Git + Git LFS - Full version control with large files
• ✅ GitHub CLI - Streamlined GitHub workflow
• ✅ VS Code Extensions - Pre-configured development tools

📦 Pre-installed Extensions:

• ESLint + Prettier - Code quality and formatting
• TypeScript - Enhanced IntelliSense
• CSS Peek - Quick stylesheet navigation
• Auto Rename Tag - Synchronized tag editing
• GitLens - Advanced Git visualization

💡 Pro Tip: The dev container ensures every team member has an identical development environment!

We maintain enterprise-grade code quality through automated tooling:

# 🔍 Check code quality
yarn lint               # Run ESLint checks (catches re-render issues)
yarn lint:fix           # Auto-fix ESLint issues
yarn format             # Format with Prettier
yarn type-check         # TypeScript validation

💡 Performance Tip: ESLint now catches common re-render issues like inline arrow functions and object/array literals in JSX. See docs/ESLINT.md for details.

Comprehensive testing ensures reliability and prevents regressions:

• 💯 High Coverage - Target 90%+ code coverage
• 🧩 Component Focus - Test behavior, not implementation
• ⚡ Fast Feedback - Sub-second test execution
• 🔄 Continuous - Tests run on every commit

# 🚀 Quick test run
yarn test                    # Run full test suite

# 👀 Development mode
yarn test:watch             # Watch mode with hot reload

# 📊 Coverage analysis
yarn test:coverage          # Generate detailed coverage report

# 🔍 Specific test patterns
yarn test Button            # Test files matching "Button"
yarn test --testNamePattern="search" # Test names containing "search"

• ✅ Component Rendering - UI components render correctly
• ✅ User Interactions - Clicks, inputs, and navigation
• ✅ State Management - Context and hooks behavior
• ✅ API Integration - Mock external dependencies
• ✅ Error Boundaries - Graceful error handling

📊 Coverage Reports are automatically generated and stored in coverage/ directory

Zero-downtime deployments with enterprise-grade reliability:

graph LR
    A[Push to main] --> B[GitHub Actions]
    B --> C[Build & Test]
    C --> D[Deploy to Netlify]
    D --> E[Live on podr.netlify.app]

# 📦 Build for production
yarn build:ci               # Optimized production build

# 🚀 Deploy to Netlify (if CLI configured)
netlify deploy --prod --dir=dist

# 🔍 Preview deployment locally
yarn serve                  # Serve built files locally

• 🗜️ Bundle Splitting - Separate vendor and app chunks
• 🎯 Tree Shaking - Dead code elimination
• 📦 Asset Optimization - Image compression and minification
• 🔗 Preload Hints - Critical resource prioritization

We ❤️ contributions! Help make Podr even better for the podcast community.

# 1. 🍴 Fork the repository
gh repo fork cascadiacollections/podr

# 2. 🌟 Create feature branch
git checkout -b feature/amazing-feature

# 3. ✨ Make your changes
# Edit files, add tests, update docs

# 4. ✅ Verify quality
yarn test                    # Run tests
yarn build                   # Ensure it builds

# 5. 📝 Commit with clear message
git commit -m "feat: add amazing feature that does X"

# 6. 🚀 Push and create PR
git push origin feature/amazing-feature
gh pr create --title "Add amazing feature" --body "Description of changes"

• ✅ Follow Code Style - ESLint + Prettier enforced
• ✅ Write Tests - Maintain 90%+ coverage
• ✅ Update Docs - Keep README and comments current
• ✅ Small PRs - Focused, reviewable changes
• ✅ Clear Commits - Use conventional commit format
• ✅ Security First - Report vulnerabilities privately (see SECURITY.md)

📖 Detailed guidelines: See CONTRIBUTING.md for complete information

We take security seriously. If you discover a security vulnerability:

• DO NOT open a public issue
• See SECURITY.md for responsible disclosure instructions
• Email: kevintcoughlin@users.noreply.github.com

This project is licensed under the MIT License - see the LICENSE file for details.

🎉 Free to use, modify, and distribute!

Podr stands on the shoulders of giants: