Implement SSR adapter system

Now the only way of running JS code on Elixir is using NodeJS call but
there are other ways of executing JS like for example using Bun runtime
or in development rendering the inertia app using VideJS dev server.
This changes allow users to hook into inertia's ssr system and use their
own adapters.

Author: andresgutgon

.circleci/config.yml

@@ -6,8 +6,8 @@ jobs:
       version:
         type: string
 
-    # The resource_class feature allows configuring CPU and RAM resources for each job. 
-    # Different resource classes are available for different executors. 
+    # The resource_class feature allows configuring CPU and RAM resources for each job.
+    # Different resource classes are available for different executors.
     # https://circleci.com/docs/2.0/configuration-reference/#resourceclass
     resource_class: "large"
 
@@ -21,6 +21,8 @@ jobs:
     steps:
       - checkout
       - run: mix --version
+      - run: node -v
+      - run: npm -v
       - restore_cache:
           keys:
             - elixir-build-<< parameters.version >>-{{ checksum "mix.lock" }}

.gitignore

@@ -1,6 +1,9 @@
 # The directory Mix will write compiled artifacts to.
 /_build/
 
+# nvim ELP plugin output
+.elixir_ls/
+
 # If you run "mix test --cover", coverage assets end up here.
 /cover/
 

README.md

@@ -55,7 +55,7 @@ config :inertia,
   # conventional in JavaScript. Defaults to `false`.
   camelize_props: false,
 
-  # Instruct the client side whether to encrypt the page object in the window history 
+  # Instruct the client side whether to encrypt the page object in the window history
   # state. This can also be set/overridden on a per-request basis, using the `encrypt_history`
   # controller helper. Defaults to `false`.
   history: [encrypt: false],
@@ -64,6 +64,10 @@ config :inertia,
   # see instructions below). Defaults to `false`.
   ssr: false,
 
+  # By default the server side rendering is done by executing nodejs.
+  # you can use your own adapter following the spec.
+  ssr_adapter: MyAdapter
+
   # Whether to raise an exception when server-side rendering fails (only applies
   # when SSR is enabled). Defaults to `true`.
   #
@@ -313,7 +317,7 @@ conn
 
 ## Deferred props
 
-**Requires Inertia v2.x on the client-side**. 
+**Requires Inertia v2.x on the client-side**.
 
 If you have expensive data that you'd like to automatically fetch (from the client-side via an async background request) after the page is initially rendered, you can mark the prop as deferred:
 
@@ -361,7 +365,7 @@ defmodule MyApp.UserAuth do
 
   def authenticate_user(conn, _opts) do
     user = get_user_from_session(conn)
- 
+
     # Here we are storing the user in the conn assigns (so
     # we can use it for things like checking permissions later on),
     # AND we are assigning a serialized represention of the user
@@ -405,7 +409,7 @@ The `assign_errors` function will automatically convert the changeset errors int
 {
   "name" => "can't be blank",
 
-  // Nested errors keys are flattened with a dot separator (`.`) 
+  // Nested errors keys are flattened with a dot separator (`.`)
   "team.name" => "must be at least 3 characters long",
 
   // Nested arrays are zero-based and indexed using bracket notation (`[0]`)
@@ -507,7 +511,6 @@ conn
 
 The `Inertia.Testing` module includes helpers for testing your Inertia controller responses, such as the `inertia_component/1` and `inertia_props/1` functions.
 
-
 ```elixir
 use MyAppWeb.ConnCase
 
@@ -629,6 +632,7 @@ Add the `ssr` build to the watchers in your dev environment, alongside the other
     ]
 ```
 
+### Build and deploy with SSR
 Add the `ssr` build step to the asset build and deploy scripts.
 
 ```diff
@@ -714,7 +718,7 @@ Then, update your config to enable SSR (if you'd like to enable it globally).
     # assets using the `static_paths` config). Defaults to "1".
     default_version: "1",
 
-    # Enable server-side rendering for page responses (requires some additional setup, 
+    # Enable server-side rendering for page responses (requires some additional setup,
     # see instructions below). Defaults to `false`.
 -   ssr: false
 +   ssr: true
@@ -728,6 +732,20 @@ Then, update your config to enable SSR (if you'd like to enable it globally).
     raise_on_ssr_failure: config_env() != :prod
 ```
 
+### Using ESM (EcmaScript Modules) on SSR entrypoint
+
+By default this library uses CommonJS modules for SSR. If you want to use ESM (EcmaScript Modules) set `esm: true` in your config.
+
+```elixir
+  {Inertia.SSR, path: Path.join([Application.app_dir(:my_app), "priv"]), esm: true},
+```
+
+### Custom SSR adapter
+
+You can setup your own SSR adapter. This is a list of third party adapters.
+
+- [vitex](https://github.com/andresgutgon/vitex) is a package that helps with ViteJS development in Phoenix apps. It has a custom SSR adapter for this package (inertia-phoenix) so SSR can be handle in development through Vite Dev server instead of calling a NodeJS process like we do in production. You can see [how it's configured here](https://github.com/andresgutgon/vitex?tab=readme-ov-file#configuring-vitejs-in-your-phoenix-app)
+
 ### Installing Node.js in your production
 
 You need to have Node.js installed in your production server environment, so that we can call the SSR script when serving pages. These steps assume you are deploying your application using a Dockerfile and releases.

lib/inertia/ssr.ex

@@ -1,54 +1,24 @@
 defmodule Inertia.SSR do
+  alias Inertia.SSR.{Config, Adapter}
+  alias Inertia.SSR.Adapters.{Bootstrap, NodeJS}
+
   @moduledoc """
-  A supervisor that provides SSR support for Inertia views. This module is
-  responsible for starting a pool of Node.js processes that can run the SSR
-  rendering function for your application.
+  Supervisor for SSR support in Inertia views.
   """
-
   use Supervisor
 
-  require Logger
-
-  alias Inertia.SSR.Config
-
-  @default_pool_size 4
-  @default_module "ssr"
-
-  @doc """
-  Starts the SSR supervisor and accompanying Node.js workers.
-
-  ## Options
-
-  - `:path` - (required) the path to the directory where your `ssr.js` file lives.
-  - `:module` - (optional) the name of the Node.js module file. Defaults to "#{@default_module}".
-  - `:pool_size` - (optional) the number of Node.js workers. Defaults to #{@default_pool_size}.
-  """
   def start_link(init_arg) do
     Supervisor.start_link(__MODULE__, init_arg, name: __MODULE__)
   end
 
-  @impl true
-  @doc false
   def init(opts) do
-    path = Keyword.fetch!(opts, :path)
-    module = Keyword.get(opts, :module, @default_module)
-    pool_size = Keyword.get(opts, :pool_size, @default_pool_size)
-
-    children = [
-      {Config, module: module},
-      {NodeJS.Supervisor, name: supervisor_name(), path: path, pool_size: pool_size}
-    ]
-
+    {adapter, config} = Bootstrap.fetch_adapter(opts: opts, default_adapter: NodeJS)
+    children = [{Config, adapter: adapter, config: config}] ++ adapter.children(config)
     Supervisor.init(children, strategy: :one_for_one)
   end
 
-  @doc false
+  @spec call(Adapter.page()) :: Adapter.ssr_result()
   def call(page) do
-    module = GenServer.call(Config, :module)
-    NodeJS.call({module, :render}, [page], name: supervisor_name(), binary: true)
-  end
-
-  defp supervisor_name do
-    Module.concat(__MODULE__, Supervisor)
+    Config.call(page)
   end
 end

lib/inertia/ssr/adapter.ex

@@ -0,0 +1,20 @@
+defmodule Inertia.SSR.Adapter do
+  @moduledoc false
+
+  @type adapter_config :: struct()
+  @type page :: %{
+          required(:component) => String.t(),
+          required(:props) => map(),
+          required(:url) => String.t(),
+          optional(:version) => String.t(),
+          optional(:encryptHistory) => boolean(),
+          optional(:clearHistory) => boolean(),
+          optional(:mergeProps) => list(String.t()),
+          optional(:deferredProps) => map()
+        }
+  @type ssr_result :: {:ok, map()} | {:error, String.t()}
+
+  @callback init(opts :: keyword()) :: adapter_config()
+  @callback children(adapter_config()) :: [{module(), keyword()}]
+  @callback call(page(), adapter_config()) :: ssr_result()
+end

lib/inertia/ssr/adapters/bootstrap.ex

@@ -0,0 +1,27 @@
+defmodule Inertia.SSR.Adapters.Bootstrap do
+  @moduledoc false
+
+  alias Inertia.SSR.Adapter
+
+  @spec fetch_adapter(
+          opts: keyword(),
+          default_adapter: module()
+        ) :: {module(), Adapter.adapter_config()}
+  def fetch_adapter(opts: opts, default_adapter: default_adapter) do
+    custom_adapter = Keyword.get(opts, :ssr_adapter, nil)
+    adapter = resolve_adapter(default_adapter, custom_adapter)
+    config = adapter.init(opts)
+    {adapter, config}
+  end
+
+  @spec resolve_adapter(module(), module() | nil) :: module()
+  defp resolve_adapter(default_adapter, custom_adapter) do
+    if is_atom(custom_adapter) and
+         Code.ensure_loaded?(custom_adapter) and
+         function_exported?(custom_adapter, :init, 1) do
+      custom_adapter
+    else
+      default_adapter
+    end
+  end
+end

lib/inertia/ssr/adapters/config.ex

@@ -0,0 +1,18 @@
+defmodule Inertia.SSR.Adapters.Config do
+  @moduledoc false
+
+  defmacro __using__(opts) do
+    name = Keyword.fetch!(opts, :name)
+    config_module = Keyword.fetch!(opts, :config)
+
+    quote do
+      @behaviour Inertia.SSR.Adapter
+      @name unquote(name)
+
+      def init(opts) do
+        config = unquote(config_module).build(opts)
+        config
+      end
+    end
+  end
+end

lib/inertia/ssr/adapters/node_js/adapter.ex

@@ -0,0 +1,37 @@
+defmodule Inertia.SSR.Adapters.NodeJS do
+  require Logger
+  alias Inertia.SSR.Supervisor, as: SSRSupervisor
+  alias Inertia.SSR.Adapters.NodeJS.Config
+
+  @moduledoc """
+  ## Options
+
+  - `:path` - (required) the path to the directory where your `ssr.js` file lives.
+  - `:module` - (optional) the name of the Node.js module file
+  - `:esm` - (optional) Use ESM for the generated ssr.js file
+  - `:pool_size` - (optional) the number of Node.js workers
+
+  SSR adapter using NodeJS invoked from Elixir.
+  """
+
+  use Inertia.SSR.Adapters.Config, name: :nodejs, config: Config
+
+  @impl true
+  def children(%Config{path: path, pool_size: pool_size}) do
+    [
+      {NodeJS.Supervisor, name: SSRSupervisor, path: path, pool_size: pool_size}
+    ]
+  end
+
+  @impl true
+  def call(page, %Config{module: module, esm: esm}) when is_map(page) do
+    # ESM module needs the `.js` extension
+    module = if(esm, do: "#{module}.js", else: module)
+
+    NodeJS.call({module, :render}, [page],
+      name: SSRSupervisor,
+      binary: true,
+      esm: esm
+    )
+  end
+end

lib/inertia/ssr/adapters/node_js/config.ex

@@ -0,0 +1,27 @@
+defmodule Inertia.SSR.Adapters.NodeJS.Config do
+  @moduledoc false
+
+  @enforce_keys [:path]
+  defstruct [:path, :module, :esm, :pool_size]
+
+  @default_module "ssr"
+  @default_esm false
+  @default_pool_size 4
+
+  @type t :: %__MODULE__{
+          path: String.t(),
+          module: String.t(),
+          esm: boolean(),
+          pool_size: pos_integer()
+        }
+
+  @spec build(keyword()) :: t()
+  def build(opts) do
+    %__MODULE__{
+      path: Keyword.fetch!(opts, :path),
+      module: Keyword.get(opts, :module, @default_module),
+      esm: Keyword.get(opts, :esm, @default_esm),
+      pool_size: Keyword.get(opts, :pool_size, @default_pool_size)
+    }
+  end
+end

lib/inertia/ssr/config.ex

@@ -1,27 +1,52 @@
 defmodule Inertia.SSR.Config do
   @moduledoc false
 
+  alias Inertia.SSR.Adapter
+
   use GenServer
 
-  # Client
+  @type state :: %{adapter: module(), config: struct()}
+
+  def start_link(opts) do
+    adapter = Keyword.fetch!(opts, :adapter)
+    config = Keyword.fetch!(opts, :config)
 
-  def start_link(init_arg) do
-    GenServer.start_link(__MODULE__, init_arg, name: __MODULE__)
+    GenServer.start_link(
+      __MODULE__,
+      %{
+        adapter: adapter,
+        config: config
+      },
+      name: __MODULE__
+    )
   end
 
-  def module(pid) do
-    GenServer.call(pid, :module)
+  @doc "Stores the adapter module and its config"
+  def set_adapter(adapter_module, config) do
+    GenServer.call(__MODULE__, {:set_adapter, adapter_module, config})
   end
 
-  # Server (callbacks)
+  @doc "Forwards the page call to the adapter"
+  def call(page) do
+    GenServer.call(__MODULE__, {:call, page})
+  end
+
+  @impl true
+  @spec init(state()) :: {:ok, state()}
+  def init(state), do: {:ok, state}
 
   @impl true
-  def init(state) do
-    {:ok, state}
+  @spec handle_call(
+          {:call, Adapter.page()},
+          GenServer.from(),
+          state()
+        ) :: {:reply, Adapter.ssr_result(), state()}
+  def handle_call({:call, page}, _from, %{adapter: adapter, config: config} = state) do
+    {:reply, adapter.call(page, config), state}
   end
 
   @impl true
-  def handle_call(:module, _from, state) do
-    {:reply, state[:module], state}
+  def handle_call({:set_adapter, adapter_module, config}, _from, _state) do
+    {:reply, :ok, %{adapter: adapter_module, config: config}}
   end
 end