PhoenixKit - The Elixir Phoenix Starter Kit for SaaS apps

Hex VersionCIcodecov

We are actively building PhoenixKit, a comprehensive SaaS starter kit for the Elixir/Phoenix ecosystem. Our goal is to eliminate the need to reinvent the wheel every time we all start a new SaaS project.

🚧 Early Access - We Need Your Feedback!

PhoenixKit is under heavy development and we're looking for early adopters to test, provide feedback, and help shape the future of this toolkit. If you're building with Phoenix and want to skip the boilerplate setup, we'd love to have you try it out and share your experience.

With PhoenixKit, you will be able to create production-ready Elixir/Phoenix apps much faster and focus on your unique business logic instead of reimplementing common SaaS patterns.

📖 Documentation

Semi-Automatic Installation

PhoenixKit provides pretty simple installation method, powered by igniter library, which takes care of all configuration needs.

Add phoenix_kit to your project dependencies. igniter installed in phoenix_kit.

# mix.exs
def deps do
  [
    {:phoenix_kit, "~> 1.7"}
  ]
end

Then run the PhoenixKit installer:

mix deps.get
mix phoenix_kit.install

This will automatically:

📦 Current PhoenixKit Features / Modules:

✅ Simple installation using Igniter (`mix phoenix_kit.install` and updating via `mix phoenix_kit.update`) 
✅ Tailwind and DaisyUI integration
✅ App layout integration
✅ App database integration (Postgres only for now)
✅ Custom slug prefix (default: `/phoenix_kit`)

✅ Backend Admin module

✅ User Module
  ✅ Registration
  ✅ Login
  ✅ Logout
  ✅ Magic link
  ✅ Email confirmation (waiting Email Module)
  ✅ Fail2ban (userbased, ip based, region based)
  ✅ Password reset
  ✅ User roles
  ✅ Custom user fields
    ✅ JSONB storage for flexibility
  ✅ Location of registration (ip, country, region, city)
  ✅ User's timezone (and mismatch detection)
  ✅ User's locale
  ✅ OAuth (google, facebook)


✅ Modules Manager

✅ Session Manager Module

✅ Settings
    ✅ General
    ✅ App title
    ✅ Global app timezone (switched from timex to native elixir)
    ✅ Global time format (switched from timex to native elixir)
    ✅ Language configuration

✅ Languages (Backend and frontend languages, broken down to countries and regions)
    ✅ Backend languages
    ✅ Frontend enduser languages, broken down and organized by countries and regions

✅ Users Module
    ✅ Role management
    ✅ Referral Program

✅ User Relationship Module (for User Generated Content/UGC)

✅ Maintenance Mode Module

✅ Email Module
    ✅ AWS SES integration

✅ Entities Module (dynamic content types)
    ✅ Dynamic entity type creation
    ✅ Flexible field schemas (13 field types)
    ✅ JSONB storage for flexibility
    ✅ Full CRUD interfaces
    ✅ Settings management

✅ Media Module
    ✅ Photos and Videos
    ✅ Local and cloud multiple storages
    ✅ Image resizing 
    ✅ Video resizing
✅ Publishing Module
     ✅ 2 types supported: timed and slug based
     ✅ Multilingual publishing
     ✅ Timezone support

✅ Posts Module (for User Generated Content/UGC)

✅ Sync Module (to sync dev / testing / staging / production) environments

✅ Sitemap Module

✅ AI Module
     ✅ OpenRouter Integration

✅ Billing Module
    - Invoices
    - Payment
      - Integration
        - Stripe
        - PayPal
    - Orders
  - Membership / Subscription Module

✅ Basic UI Components
    ✅ [Draggable List](guides/draggable_list_component.md) - Drag-and-drop grid/list component

🛣️ Roadmap / Ideas / Feature requests

--- Next priority

--- To sort items

💡 Send your ideas and suggestions about any existing modules and features our way. Start building your apps today!

Installation

PhoenixKit provides multiple installation methods to suit different project needs and developer preferences.

Semi-Automatic Installation

Recommended for most projects

Add phoenix_kit to your project dependencies (Igniter is included automatically):

# mix.exs
def deps do
  [
    {:phoenix_kit, "~> 1.7"}
  ]
end

Then run the PhoenixKit installer:

mix deps.get
mix phoenix_kit.install

This will automatically:

Optional parameters:

# Specify custom repository
mix phoenix_kit.install --repo MyApp.Repo

# Use PostgreSQL schema prefix for table isolation
mix phoenix_kit.install --prefix "auth" --create-schema

# Specify custom router file path
mix phoenix_kit.install --router-path lib/my_app_web/router.ex

Manual Installation

  1. Add {:phoenix_kit, "~> 1.7"} to mix.exs
  2. Run mix deps.get && mix phoenix_kit.gen.migration
  3. Configure repository: config :phoenix_kit, repo: MyApp.Repo
  4. Add phoenix_kit_routes() to your router
  5. Run mix ecto.migrate

Quick Start

Visit these URLs after installation:

Where {prefix} is your configured PhoenixKit URL prefix (default: /phoenix_kit).

Configuration

Basic Setup

# config/config.exs (automatically added by installer)
config :phoenix_kit,
  repo: YourApp.Repo,
  from_email: "noreply@yourcompany.com",  # Required for email notifications
  from_name: "Your Company Name"          # Optional, defaults to "PhoenixKit"

# Production mailer (see config/prod.exs for more options)
config :phoenix_kit, PhoenixKit.Mailer,
  adapter: Swoosh.Adapters.SMTP,
  relay: "smtp.your-provider.com",
  username: System.get_env("SMTP_USERNAME"),
  password: System.get_env("SMTP_PASSWORD"),
  port: 587

Layout Integration

# Use your app's layout (optional)
config :phoenix_kit,
  layout: {YourAppWeb.Layouts, :app},
  root_layout: {YourAppWeb.Layouts, :root}

Email Configuration

PhoenixKit supports multiple email providers with automatic setup assistance:

AWS SES (Complete Setup)

For AWS SES, PhoenixKit automatically configures required dependencies and HTTP client:

# Add to mix.exs dependencies (done automatically by installer when needed)
{:gen_smtp, "~> 1.2"}

# Application supervisor includes Finch automatically
{Finch, name: Swoosh.Finch}

# Production configuration
config :phoenix_kit, PhoenixKit.Mailer,
  adapter: Swoosh.Adapters.AmazonSES,
  region: "eu-north-1"  # or "eu-north-1", "eu-west-1", etc.

AWS SES Checklist:

Other Email Providers

# SendGrid
config :phoenix_kit, PhoenixKit.Mailer,
  adapter: Swoosh.Adapters.Sendgrid,
  api_key: System.get_env("SENDGRID_API_KEY")

# Mailgun
config :phoenix_kit, PhoenixKit.Mailer,
  adapter: Swoosh.Adapters.Mailgun,
  api_key: System.get_env("MAILGUN_API_KEY"),
  domain: System.get_env("MAILGUN_DOMAIN")

Note: Run mix deps.compile phoenix_kit --force after changing configuration.

OAuth Configuration

Enable social authentication (Google, Apple, GitHub) through admin UI at {prefix}/admin/settings. Built-in setup instructions included. For reverse proxy deployments, ensure X-Forwarded-Proto header is set:

proxy_set_header X-Forwarded-Proto $scheme;

See OAuth Setup Guide for details.

Advanced Options

Routes

User Authentication Routes

User Dashboard Routes (when enabled)

Admin Routes (Owner/Admin only)

API Usage

Current User Access

# In your controller or LiveView
user = conn.assigns[:phoenix_kit_current_user]

# Or using Scope system
scope = socket.assigns[:phoenix_kit_current_scope]
PhoenixKit.Users.Auth.Scope.authenticated?(scope)

Role-Based Access

# Check user roles
PhoenixKit.Users.Roles.user_has_role?(user, "Admin")

# Promote user to admin
{:ok, _} = PhoenixKit.Users.Roles.promote_to_admin(user)

# Use in LiveView sessions
on_mount: [{PhoenixKitWeb.Users.Auth, :phoenix_kit_ensure_admin}]

Authentication Helpers

# In your LiveView sessions
on_mount: [{PhoenixKitWeb.Users.Auth, :phoenix_kit_mount_current_scope}]
on_mount: [{PhoenixKitWeb.Users.Auth, :phoenix_kit_ensure_authenticated_scope}]

Database Schema

PhoenixKit creates these PostgreSQL tables:

Role-Based Access Control

System Roles

Role Management

# Check roles
PhoenixKit.Users.Roles.get_user_roles(user)
# => ["Admin", "User"]

# Role promotion/demotion
PhoenixKit.Users.Roles.promote_to_admin(user)
PhoenixKit.Users.Roles.demote_to_user(user)

# Create custom roles
PhoenixKit.Users.Roles.create_role(%{name: "Manager", description: "Team lead"})

Module-Level Permissions (V53)

PhoenixKit includes a granular permission system that controls which roles can access which admin sections and feature modules.

25 permission keys: 5 core sections (dashboard, users, media, settings, modules) + 20 feature modules

Access rules:

# Grant/revoke permissions for a role
Permissions.grant_permission(role_id, "billing", admin_id)
Permissions.revoke_permission(role_id, "billing")
Permissions.set_permissions(role_id, ["dashboard", "users", "billing"], admin_id)

# Query permissions
Permissions.get_permissions_for_role(role_id)    # ["dashboard", "users", ...]
Permissions.role_has_permission?(role_id, "shop") # true/false

# Check access via Scope (in LiveViews)
Scope.has_module_access?(scope, "billing")       # true/false
Scope.has_any_module_access?(scope, ["billing", "shop"])
Scope.system_role?(scope)                        # Owner or Admin?

Admin UI: Interactive permission matrix at {prefix}/admin/users/permissions and inline editor on the Roles page.

Route enforcement: phoenix_kit_ensure_admin and phoenix_kit_ensure_module_access on_mount hooks enforce permissions at the route level. Sidebar navigation is gated per-user based on granted permissions.

Module System

PhoenixKit uses a modular architecture where features can be enabled/disabled at runtime. All modules are disabled by default and must be enabled before use.

Enable via Admin UI: Visit {prefix}/admin/modules to toggle modules on/off.

Enable via Code:

# Check if a module is enabled
PhoenixKit.Modules.AI.enabled?()        # => false (default)
PhoenixKit.Modules.Entities.enabled?()  # => false (default)

# Enable modules before use
PhoenixKit.Modules.AI.enable_system()
PhoenixKit.Modules.Entities.enable_system()
PhoenixKit.Modules.Posts.enable_system()
PhoenixKit.Emails.enable_system()
PhoenixKit.Billing.enable_system()
PhoenixKit.Modules.Sync.enable_system()

# Disable when no longer needed
PhoenixKit.Modules.AI.disable_system()

Important: Attempting to use a disabled module's API functions or admin pages will result in errors or redirects. Always enable modules before:

Built-in Admin Interface

Core Administration:

Content & Data:

Communication:

AI Module:

Billing & Payments:

Settings & Configuration:

Data Sync:

Architecture

PhoenixKit follows professional library patterns:

Contributing

See CONTRIBUTING.md for detailed instructions on setting up a development environment and contributing to PhoenixKit.

License

MIT License - see CHANGELOG.md for version history.

Built in 🇪🇺🇪🇪 with ❤️ for the Elixir Phoenix community.