CaravelaSvelte.Router (CaravelaSvelte v0.1.0)

Router macros for declaring :live and :rest mode routes.

use CaravelaSvelte.Router imports caravela_live/2..4 (wrapping Phoenix.LiveView.Router.live/2..4) and caravela_rest/2..3 (wrapping Phoenix.Router.resources/2..4).

defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  use CaravelaSvelte.Router

  scope "/", MyAppWeb do
    pipe_through :browser

    caravela_live "/dashboard", DashboardLive
    caravela_rest "/library/books", BookController
  end
end

Under the hood:

caravela_live expands 1:1 to live/2..4 — the existing LiveView route helper. The extra sugar is a per-route metadata entry saying "this route is CaravelaSvelte's :live mode" so future plugs (B.4 SSE, auth integration) can branch on it.
caravela_rest expands to resources/2..4 with sensible Inertia-style defaults (all 7 actions).

Both macros accept the same optional args as their Phoenix counterparts; options are passed through.

Action filtering

To opt out of actions (e.g., a read-only resource), use :only or :except as with resources:

caravela_rest "/library/books", BookController, only: [:index, :show]

Summary

Functions

__using__(opts)

Import caravela_live/2..4 and caravela_rest/2..3 into the caller. Assumes the caller already uses Phoenix.Router and has access to Phoenix.LiveView.Router.live/4 (usually via use MyAppWeb, :router).

caravela_live(path, live_view, action \\ nil, opts \\ [])

Declare a :live mode route. Forwards to Phoenix.LiveView.Router.live/2..4.

caravela_rest(path, controller, opts \\ [])

Declare a :rest mode route. Forwards to Phoenix.Router.resources/2..4 and merges a private: %{caravela_svelte_mode: :rest} entry so downstream plugs can branch on the mode.

Functions

using(opts)

(macro)

caravela_live(path, live_view, action \\ nil, opts \\ [])

(macro)

Declare a :live mode route. Forwards to Phoenix.LiveView.Router.live/2..4.

Accepts the same arguments: path, live_view, optional action atom, optional keyword options. Options are passed through to Phoenix's live macro.

A private: %{caravela_svelte_mode: :live} entry is merged into the options so downstream plugs (see CaravelaSvelte.Plug) can identify the route's mode at runtime.

caravela_rest(path, controller, opts \\ [])

(macro)

Declare a :rest mode route. Forwards to Phoenix.Router.resources/2..4 and merges a private: %{caravela_svelte_mode: :rest} entry so downstream plugs can branch on the mode.

Options

All resources/4 options are supported — :only, :except, :as, :param, :singleton. The :private map is merged, not overwritten.

`:realtime`

Pass realtime: true to register a Server-Sent Events endpoint alongside the resource:

caravela_rest "/dashboard", DashboardController, realtime: true

This registers a GET <path>/__events route dispatching to CaravelaSvelte.SSE. The client calls subscribe(topic, onPatch) (from @caravela/svelte/rest) to open an EventSource at that URL with a topic=<name> query parameter, and the server publishes patches with CaravelaSvelte.SSE.publish(topic, ops).

Pass a keyword list instead of true to forward plug options (:heartbeat_ms, :retry_ms, :topic_prefix, :pubsub) to CaravelaSvelte.SSE:

caravela_rest "/dashboard", DashboardController,
  realtime: [heartbeat_ms: 30_000, topic_prefix: "dashboard:"]