PhoenixKit — A Foundation for Building Your Elixir Phoenix Apps

Hex VersionCIcodecov

We are actively building PhoenixKit, a foundation for building your Elixir Phoenix apps — SaaS, social networks, ERP systems, marketplaces, internal tools, AI-powered apps, community platforms, and more. Our goal is to eliminate the need to reinvent the wheel every time you start a new project.

With PhoenixKit, you are able to create Elixir/Phoenix apps much faster and focus on your unique business logic instead of reimplementing common patterns.

📖 Documentation

Installation

One command sets up the dependency, configuration, routes, mailer, and migrations:

mix igniter.install phoenix_kit

Prerequisite: the igniter_new archive (one-time setup, same as phx_new):

mix archive.install hex igniter_new

This will automatically:

See Installation Options below for advanced flags and fallback flows.

📦 Current PhoenixKit Features / Modules:

✅ One-command install via Igniter (`mix igniter.install phoenix_kit`, updates 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)



✅ 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 Options

The recommended path is mix igniter.install phoenix_kit (see the quick install at the top of this README). The sections below cover advanced options and fallback flows.

Installer options

# Specify custom repository

mix igniter.install phoenix_kit --repo MyApp.Repo



# Use PostgreSQL schema prefix for table isolation

mix igniter.install phoenix_kit --prefix "auth" --create-schema



# Specify custom router file path

mix igniter.install phoenix_kit --router-path lib/my_app_web/router.ex

The same flags work with mix phoenix_kit.install if the dep is already in your project.

Fallback: two-step install

If you'd rather not use the igniter_new archive, add the dep yourself and invoke the installer directly — :igniter is already pulled in transitively, so this works on any Phoenix project:

# mix.exs

def deps do

  [

    {:phoenix_kit, "~> 1.7"}

  ]

end

mix deps.get

mix phoenix_kit.install

Manual Installation

For full control, skip the installer entirely:

  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.

24 permission keys: 5 core sections (dashboard, users, media, settings, modules) + 19 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

PhoenixKitAI.enabled?()                 # => false (default, when installed)

PhoenixKit.Modules.Entities.enabled?()  # => false (default)



# Enable modules before use

PhoenixKitAI.enable_system()

PhoenixKit.Modules.Entities.enable_system()

PhoenixKit.Modules.Posts.enable_system()

PhoenixKit.Emails.enable_system()

PhoenixKit.Billing.enable_system()



# Disable when no longer needed

PhoenixKitAI.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:

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.