# `CaravelaSvelte.Router`
[🔗](https://github.com/rsousacode/caravela_svelte/blob/v0.1.0/lib/caravela_svelte/router.ex#L1)

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]

# `__using__`
*macro* 

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

# `caravela_live`
*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`
*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:"]

---

*Consult [api-reference.md](api-reference.md) for complete listing*