Search documentation of phoenix_kit

# PhoenixKit Development Guides

Copy Markdown View Source

This folder contains comprehensive guides to help developers work with PhoenixKit features and patterns.

## For External Users (Using PhoenixKit as a Dependency)

### Integration Guide ⭐ Start Here

The essential guide for developers using PhoenixKit as a Hex dependency. Covers:

- Quick start installation
- Configuration reference
- Authentication integration
- Troubleshooting common issues
- Links to feature-specific guides

This guide is optimized for AI assistants (Claude, Cursor, Copilot, Tidewave MCP) to help you integrate PhoenixKit into your Phoenix application.

## Available Guides

### Core Guides

#### Custom Admin Pages

Add custom pages to the PhoenixKit admin sidebar. Learn how to:

- Create LiveViews that integrate with PhoenixKit's admin layout
- Register tabs in the admin navigation
- Configure permission gates
- Use seamless LiveView navigation
- Implement common patterns (pagination, events, etc.)

Use this guide when:

- Adding custom admin pages to your application
- Extending the PhoenixKit admin interface
- Building admin functionality for your features

### Feature Guides

#### Making Pages Live: Real-time Updates & Collaborative Editing

Learn how to add real-time functionality to LiveView pages, including:

- PubSub event broadcasting
- Presence tracking for collaborative editing
- Temporary state storage with auto-expiration
- On-mount hooks for centralized subscriptions
- Common patterns and troubleshooting

Use this guide when:

- Adding real-time updates to list pages
- Implementing collaborative form editing
- Building live dashboards or detail pages
- Setting up presence tracking for any resource

#### OAuth & Magic Link Setup

Configure OAuth providers and magic link authentication for PhoenixKit.

#### AWS Email Setup

Set up AWS SES for email infrastructure automation.

#### Auth Header Integration

Authentication header patterns for PhoenixKit.

#### PHK Publishing Format

Understanding the .phk publishing file format.

#### Draggable List Component

Using the draggable list component for sortable UIs.

## Guide Purpose

These guides are designed to:

1. Speed up development - Provide working examples and patterns
2. Maintain consistency - Establish conventions across the codebase
3. Reduce errors - Document common pitfalls and solutions
4. Help AI assistants - Give clear context for code generation
5. Onboard new developers - Comprehensive documentation of systems

## Using These Guides

### For Developers

1. Read the relevant guide before implementing a feature
2. Copy and adapt the patterns to your use case
3. Reference the example files mentioned in each guide
4. Follow the best practices section
5. Check troubleshooting if you encounter issues

### For AI Assistants (Claude, etc.)

These guides provide the context needed to generate accurate code:

- System architecture and locations
- Established patterns and conventions
- Working examples from the codebase
- Common pitfalls to avoid

When asked to implement a feature, reference the appropriate guide to understand the existing infrastructure and patterns.

## Contributing New Guides

When adding a new guide:

1. Focus on patterns - Show how systems work together
2. Provide examples - Include working code from the codebase
3. Reference real files - Point to actual implementations
4. Include troubleshooting - Document common issues
5. Keep it practical - Focus on "how to" not just "what is"

### Guide Template

    # [Feature Name]: [Brief Description]

    ## Table of Contents
    - Overview
    - Quick Start
    - Detailed Explanation
    - Common Patterns
    - Troubleshooting
    - Best Practices
    - Reference Files

    ## Overview
    Brief explanation of the system and its purpose.

    ## Quick Start
    Minimal working example to get started quickly.

    ## Detailed Explanation
    Deep dive into how the system works.

    ## Common Patterns
    Real examples from the codebase.

    ## Troubleshooting
    Common issues and solutions.

    ## Best Practices
    Conventions and recommendations.

    ## Reference Files
    Links to actual implementation files.

## Planned Guides

Future guides to add:

- Testing LiveView Pages - Patterns for testing real-time features
- Database Migrations - PhoenixKit's versioned migration system
- UI Components - Creating reusable Phoenix components
- Internationalization - Multi-language support patterns

## Completed Guides

- ✅ Integration Guide - Core installation and configuration
- ✅ Custom Admin Pages - Admin sidebar integration
- ✅ Making Pages Live - Real-time updates and collaborative editing
- ✅ OAuth & Magic Link Setup - Authentication providers
- ✅ AWS Email Setup - Email infrastructure automation
- ✅ Auth Header Integration - Authentication header patterns

## Feedback

If you find issues or have suggestions for these guides, please update them directly or document the issue for future improvement.

← Previous Page Draggable List Component
Next Page → Custom Admin Pages