PhoenixKitWeb.Integration (phoenix_kit v1.7.62)

Integration helpers for adding PhoenixKit to Phoenix applications.

Basic Usage

Add to your router:

defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  import PhoenixKitWeb.Integration

  # Add PhoenixKit routes
  phoenix_kit_routes()  # Default: /phoenix_kit prefix
end

Automatic Integration

When you run mix phoenix_kit.install, the following is automatically added to your :browser pipeline:

plug PhoenixKitWeb.Plugs.Integration

This plug handles all PhoenixKit features including maintenance mode, and ensures they work across your entire application

Layout Integration

Configure parent layouts in config.exs:

config :phoenix_kit,
  repo: MyApp.Repo,
  layout: {MyAppWeb.Layouts, :app},
  root_layout: {MyAppWeb.Layouts, :root}

Authentication Callbacks

Use in your app's live_sessions:

:phoenix_kit_mount_current_scope - Mounts user and scope (recommended)
:phoenix_kit_ensure_authenticated_scope - Requires authentication
:phoenix_kit_redirect_if_authenticated_scope - Redirects if logged in

Routes Created

Authentication routes:

/users/register, /users/log-in, /users/magic-link
/users/reset-password, /users/confirm
/users/log-out (GET/DELETE)

User dashboard routes (if enabled, default: true):

/dashboard, /dashboard/settings
/dashboard/settings/confirm-email/:token

Admin routes (Owner/Admin only):

/admin, /admin/users, /admin/users/roles
/admin/users/live_sessions, /admin/users/sessions
/admin/settings, /admin/modules

Public pages routes (if Pages module enabled):

{prefix}/pages/* (explicit prefix - e.g., /phoenix_kit/pages/test)
/* (catch-all at root level - e.g., /test, /blog/post)
Both routes serve published pages from priv/static/pages/*.md
The catch-all can optionally serve a custom 404 markdown file when enabled
Example: /test or /phoenix_kit/pages/test renders test.md

Configuration

You can disable the user dashboard by setting the environment variable in your config:

# config/dev.exs or config/runtime.exs
config :phoenix_kit, user_dashboard_enabled: false

This will disable all dashboard routes (/dashboard/*). Users trying to access the dashboard will get a 404 error.

DaisyUI Setup

Install: npm install daisyui@latest
Add to tailwind.config.js:
- Content: "../../deps/phoenix_kit"
- Plugin: require('daisyui')

Layout Templates

Use {@inner_content} not render_slot(@inner_block):

<%!-- Correct --%>
<main>{@inner_content}</main>

Scope Usage in Templates

<%= if PhoenixKit.Users.Auth.Scope.authenticated?(@phoenix_kit_current_scope) do %>
  Welcome, {PhoenixKit.Users.Auth.Scope.user_email(@phoenix_kit_current_scope)}!
<% end %>

Summary

Functions

call(conn, atom)

init(opts)

locale_scope(opts \\ [], list)

Creates locale-aware routing scopes based on enabled languages.

phoenix_kit_admin_routes(suffix)

phoenix_kit_authenticated_routes(suffix)

phoenix_kit_dashboard_routes(suffix)

phoenix_kit_public_routes(suffix)

phoenix_kit_routes()

phoenix_kit_socket() deprecated

DEPRECATED: This macro is no longer needed.

Functions

call(conn, atom)

init(opts)

locale_scope(opts \\ [], list)

(macro)

Creates locale-aware routing scopes based on enabled languages.

This macro generates both a localized scope (e.g., /en/) and a non-localized scope for backward compatibility. The locale pattern is dynamically generated from the database-stored enabled language codes.

Examples

locale_scope do
  live "/admin", DashboardLive, :index
end

# Generates routes like:
# /phoenix_kit/en/admin (with locale)
# /phoenix_kit/admin (without locale, defaults to "en")

phoenix_kit_admin_routes(suffix)

(macro)

phoenix_kit_authenticated_routes(suffix)

(macro)

phoenix_kit_dashboard_routes(suffix)

(macro)

phoenix_kit_public_routes(suffix)

(macro)

phoenix_kit_routes()

(macro)

phoenix_kit_socket()

(macro)

This macro is deprecated. Sync websocket is now handled automatically via phoenix_kit_routes().

DEPRECATED: This macro is no longer needed.

The Sync WebSocket is now automatically handled via the router when you use phoenix_kit_routes(). The websocket endpoint is available at {url_prefix}/sync/websocket without any additional configuration.

You can safely remove this macro from your endpoint.ex if you have it.

Legacy Usage (deprecated)

Previously, this macro was required in endpoint.ex:

defmodule MyAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_app
  import PhoenixKitWeb.Integration

  # No longer needed - remove this line
  # phoenix_kit_socket()
end

Implementation Note

WebSocket handling is now done via forward in the router, which makes the setup fully self-contained within PhoenixKit. No endpoint modifications are required.