For developers using PhoenixKit as a Hex dependency in their Phoenix application.
This guide is designed to help both developers and AI assistants (Claude, Cursor, Copilot, Tidewave MCP, etc.) understand how to integrate and use PhoenixKit effectively.
Table of Contents
Quick Start
# 1. Verify database is prepared
mix ecto.migrations
# 2. Add to mix.exs
{:phoenix_kit, "~> 1.7"}
# 3. Run installation
mix deps.get
mix phoenix_kit.install
mix compile --force
# 4. Create database if needed
mix ecto.create
# 5. Run migrations
mix ecto.migrate
# 6. Start your server
mix phx.server
# Visit /phoenix_kit/adminInstallation
Step 1: Add Dependency
# mix.exs
defp deps do
[
{:phoenix_kit, "~> 1.7"}
]
endStep 2: Install
mix deps.get
mix phoenix_kit.install
The installer will:
- Detect your Repo automatically (or use
--repoto specify) - Add configuration to
config/config.exs - Generate migrations
- Set up mailer integration
Step 3: Configure
The installer adds this to your config. Customize as needed:
# config/config.exs
config :phoenix_kit,
parent_app_name: :my_app,
parent_module: MyApp,
url_prefix: "/phoenix_kit",
repo: MyApp.Repo,
mailer: MyApp.Mailer,
layouts_module: MyApp.Layouts,
phoenix_version_strategy: :modernStep 4: Add Routes
The installer adds something like this to your router.ex. Customize as needed:
# lib/my_app_web/router.ex
import PhoenixKitWeb.Integration
scope "/" do
pipe_through :browser
phoenix_kit_routes()
endStep 5: Run Migrations
mix ecto.migrate
Configuration Reference
Core Settings
| Setting | Type | Default | Description |
|---|---|---|---|
repo | module | auto-detected | Your Ecto Repo module |
mailer | module | nil | Your Swoosh Mailer module |
url_prefix | string | "/phoenix_kit" | URL prefix for all routes |
layout | tuple | PhoenixKit default | {LayoutModule, :template} |
root_layout | tuple | PhoenixKit default | Root layout for pages |
Authentication Settings
config :phoenix_kit, :password_requirements,
min_length: 8,
max_length: 72,
require_uppercase: false,
require_lowercase: false,
require_digit: false,
require_special: falseRate Limiting
# Hammer 7.x uses ETS backend via PhoenixKit.Users.RateLimiter.Backend
# No additional :hammer config needed
config :phoenix_kit, PhoenixKit.Users.RateLimiter,
login_limit: 5, # Max login attempts per window
login_window_ms: 60_000, # 1 minute window
magic_link_limit: 3, # Max magic link requests per window
magic_link_window_ms: 300_000, # 5 minute window
password_reset_limit: 3, # Max password reset requests per window
password_reset_window_ms: 300_000, # 5 minute window
registration_limit: 3, # Max registration attempts per window
registration_window_ms: 3_600_000, # 1 hour window
registration_ip_limit: 10, # Max registrations per IP per window
registration_ip_window_ms: 3_600_000 # 1 hour windowAuthentication Integration
Access Current User
# In a LiveView
def mount(_params, _session, socket) do
current_user = socket.assigns[:current_user]
{:ok, socket}
end
# In a Controller
def index(conn, _params) do
current_user = conn.assigns[:current_user]
render(conn, :index)
endRequire Authentication
# In your router
import PhoenixKitWeb.Users.Auth
scope "/", MyAppWeb do
pipe_through [:browser, :require_authenticated_user]
live "/dashboard", DashboardLive
endCheck User Roles
# Check if user has a role
PhoenixKit.Users.Roles.user_has_role?(user, "Admin")
PhoenixKit.Users.Roles.user_has_role?(user, "Owner")
# Get user's roles
roles = PhoenixKit.Users.Roles.get_user_roles(user)
# Check in templates
<%= if PhoenixKit.Users.Roles.user_has_role?(@current_user, "Admin") do %>
<.link navigate="/admin">Admin Panel</.link>
<% end %>Check Module-Level Permissions
PhoenixKit V53+ includes granular permissions that control which admin sections each role can access.
# In a LiveView, use the scope from assigns
scope = socket.assigns.phoenix_kit_current_scope
# Check single permission
Scope.has_module_access?(scope, "billing") # true/false
# Check multiple permissions
Scope.has_any_module_access?(scope, ["billing", "shop"]) # any granted?
Scope.has_all_module_access?(scope, ["billing", "shop"]) # all granted?
# Check system role (Owner or Admin, not custom roles)
Scope.system_role?(scope)
# Get all granted keys
Scope.accessible_modules(scope) # MapSet of granted permission keysRoute enforcement: PhoenixKit's phoenix_kit_ensure_admin and phoenix_kit_ensure_module_access on_mount hooks automatically enforce permissions on admin routes. Sidebar navigation is gated per-user.
User Registration
# Register a new user
{:ok, user} = PhoenixKit.Users.Auth.register_user(%{
email: "user@example.com",
password: "securepassword123"
})
# First user automatically becomes OwnerTroubleshooting
"Repo not configured"
# Ensure config is set
config :phoenix_kit, repo: MyApp.Repo"Routes not found"
# Ensure you imported and called the macro
import PhoenixKitWeb.Integration
phoenix_kit_routes()"Mailer not sending emails"
# Check your mailer is configured
config :my_app, MyApp.Mailer,
adapter: Swoosh.Adapters.SMTP,
# ... your SMTP settings
# And PhoenixKit knows about it
config :phoenix_kit, mailer: MyApp.Mailer"Rate limiting not working"
PhoenixKit uses Hammer 7.x with ETS backend via PhoenixKit.Users.RateLimiter.Backend. No additional Hammer configuration is required. If you need to adjust rate limits:
config :phoenix_kit, PhoenixKit.Users.RateLimiter,
login_limit: 5,
login_window_ms: 60_000Further Reading
- Entities Guide - Dynamic content types without migrations
- Custom Admin Pages - Add pages to the admin sidebar
- Admin Dashboard Reference - Admin navigation and tabs system
- Dashboard Components - Tabs, subtabs, badges, and more
For AI Assistants
When helping a developer with PhoenixKit:
- PhoenixKit is a Hex dependency - Code lives in
deps/phoenix_kit/ - Don't modify PhoenixKit files - Create code in the user's app that calls PhoenixKit APIs
- Entity names are snake_case - e.g.,
"contact_form", not"Contact Form" - Field keys are snake_case - e.g.,
"full_name", not"Full Name" - First user is Owner - First registered user gets the Owner role automatically
- Routes are prefixed - Default is
/phoenix_kit/, configurable viaurl_prefix - Permissions are cached in Scope - Use
Scope.has_module_access?/2not raw DB queries - Owner bypasses all permission checks - No DB rows needed for Owner access
- Entities use
created_by_uuid- The field iscreated_by_uuid, notcreated_by - Always use
entity.uuid- Never useentity.idfor entity operations
Last Updated: 2026-03-02