Implement SSR adapter abstraction

[andresgutgon]

What?

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

TODO

• Keep it simple for existing users. It should be totally transparent
• Setup vite plugin for handling HMR on the backend
• Generate JS/CSS assets based on the ViteJS manifest
• Being able to use ESM modules for compiled javascript
• Fix credo ✅
• Fix dyalizer errors ✅
• Make all tests pass ✅
• Use these changes in my app 🚀
• Make using a ViteJS setup in dev and prod easy. Bring ViteJS helpers in another package

Adapters

Coming from this conversation and with @Valian advise I wanted to give a try to complete integration between inertia-phoenix and ViteJS as js bundler .
The idea is to use a ViteJS adapter during development and use existing NodeJS call in production

---

TO BE DISCUSSED

I know you’ve shared your thoughts on this before, @derrickreimer — and I really appreciate your perspective. I hate to bother you with this again, but I’d truly love to bring the Vite experience into working with Inertia + Phoenix.

If I can manage to pull this off in a clean and maintainable way, and if you feel it aligns with the goals of the project, I’d be honored to contribute it. Totally up to you, of course — just wanted to put it out there. 🙏

[derrickreimer]

Appreciate the effort, @andresgutgon.

I'm not fundamentally opposed to having multiple adapters for different front-end build systems. If the past is any indication, I don't expect tool churn in the JavaScript world to slow down anytime soon 😅 . So it's reasonable for this library to not be overly opinionated about what people should use when the JS-bundling flavor of the week changes.

I'll need to give it more thought, but it might make sense to put these adapters into separate packages to keep bloat to a minimum.

In the meantime though, I still encourage folks to really consider if you need more than the simple esbuild setup we have baked in!

[andresgutgon]

@derrickreimer you commented that maybe would be better if adapters lived outside the Inertia package. And I think I really like this approach because I want to add Vite assets management and that would be too much to put in inertia.

[andresgutgon]

While adding a test for supporting ESM I saw that
Elixir 15 -> nodejs 18.x
Elixir 16 -> nodejs 20.x

18 is about to lose LTS on 30th of April and 20 next year

[andresgutgon]

@derrickreimer can you review this PR? 🙏

[derrickreimer]

@derrickreimer can you review this PR? 🙏

I'm in a pretty busy season at the moment, but I'll do my best to take a look at this soon.

[andresgutgon]

Okay, I did the last thing I wanted to do. I created an example repo app using my changes but with the standard Inertia setup explained in the README.

https://github.com/andresgutgon/inertia_ssr_adapters

I won't comment more here 🙏. I'll keep moving with my life 😃

[andresgutgon]

Hey @derrickreimer, hope you’re doing well!

Would you have a chance to review this soon? I’m working off my own fork at the moment, but I noticed you’ve merged some new changes and I’d much rather switch back to using the official package instead of maintaining my own branch.

It’s been a while since I started on this, but I put a lot of thought into the changes. I tried to keep things as non-disruptive as possible for existing users and added tests as well. I’m happy to adjust anything that needs improving—just let me know.

Thanks for taking a look!

[andresgutgon]

Btw, I noticed Inertia didn't compile unless I add Igniter to my Phoenix mix.exs file. Is that expected?

I see a note in the readme on how to get started with an Inertia project with Igniter, but maybe add a line telling that now Igniter has to be added as a project dependency

[derrickreimer]

Btw, I noticed Inertia didn't compile unless I add Igniter to my Phoenix mix.exs file. Is that expected?

I see a note in the readme on how to get started with an Inertia project with Igniter, but maybe add a line telling that now Igniter has to be added as a project dependency

D'oh! Nope it's supposed to be optional, I pushed a fix out.

Would you have a chance to review this soon? I’m working off my own fork at the moment, but I noticed you’ve merged some new changes and I’d much rather switch back to using the official package instead of maintaining my own branch.

Yeah, thanks for your patience here. This is a big enough structural change that I want to be sure to put enough thought into architectural decisions before merging. I'll try to put some time into it soon!

[andresgutgon]

Super quick fix! 👏

Don't worry, I understand this change can break things. Take your time. It's just that I want to ship this. I think it would be a good addition. Also, I'm quite proud of it. I learned a lot!

[andresgutgon]

Hi @derrickreimer, it's me again 🙏 I hope you're doing well. Did you have a chance to take a look at these changes?

[derrickreimer]

Hi @derrickreimer, it's me again 🙏 I hope you're doing well. Did you have a chance to take a look at these changes?

Apologies, I've not had a chance yet.

[andresgutgon]

Ok, thanks, Derrick, for the quick response. appreciate

[andresgutgon]

Hi, it's me again 😅. Happy 2026 @derrickreimer I hope this year is the year of Inertia adapter 💪

[vonagam]

Just noting that I have used the intertia from this PR plus @andresgutgon's vitex (thought the package would need a name change since there is now other vitex published) and phoenix_vite on back with latest versions of vite/typescript/vue/inertiajs (including it's @inertiajs/vite package) on front. Everything worked for me.

Noting that in this PR there is a mention of ssr_adapter option for intertia config - but it's never read in the code. Right now it's only possible to set adapter by Inertia.SSR spec opts.

[andresgutgon]

Just noting that I have used the intertia from this PR plus @andresgutgon's vitex (thought the package would need a name change since there is now other vitex published)

Yeah, I have pending choosing the name after this is merged he he

Noting that in this PR there is a mention of ssr_adapter option for intertia config - but it's never read in the code. Right now it's only possible to set adapter by Inertia.SSR spec opts.

In main there is no concept of SSR adapter. After this PR in the future someone will be able to plug a Bun or Deno adapter for example. For now what was working keep working which is the existing Inertia.SSR.Adapters.NodeJS

[vonagam]

After this PR in the future someone will be able to plug a Bun or Deno adapter for example.

Right, I'm noting that PR adds description for ssr_adapter config option without implementing it. Right now (in this PR) it is only possible to set an adapter directly though a child spec. (Which reduces usability a bit since the idea is to use different adapters in dev and prod.) And implementing the config option won't change the default (from nodejs), so I don't understand why config option is not read in this PR.

[andresgutgon]

I don't understand why config option is not read in this PR.

It's been a year since i implemented this code but i think is used. Just that only existing nodejs implementation was converted in the only and default ssr adapter. After this is meeged other people could bring another adapters.

it's used in bootstrap.ex

[vonagam]

it's used in bootstrap.ex

There is no call to read the application config, in Bootstrap it gets adapter from opts passed to process child spec (the init option is also called ssr_adapter, which is reasonable).

[andresgutgon]

There is no call to read the application config, in Bootstrap it gets adapter from opts passed to process child spec (the init option is also called ssr_adapter, which is reasonable).

Here the config is read https://github.com/inertiajs/inertia-phoenix/pull/44/changes#diff-dba29715f803cdaa6aa99dad1320eb56ece773bbac53640e0adc5ee5a3b036f9R10-R15 and here that custom SSR adapter is invoked https://github.com/inertiajs/inertia-phoenix/pull/44/changes#diff-03cd03cff821332cd979084df8dcc112045f5f17836f9046612315f8e6c1861aR15-R16

Probably I'm not following your concern.

I wanted this to enable Vite development which is industry standard today and that for sure is working. I'm ussing ssr_adapter like this
https://github.com/andresgutgon/ash_learning/blob/main/config/runtime.exs#L26-L29

[vonagam]

There is an application config. It is defined in config/config.exs, config/dev.exs and so on. It is read through Application.get_env/Application.fetch_env/Application.compile_env. This PR adds information to Readme that there is now a new application config option under config :inertia called ssr_adapter that allows to specify an adapter. But there is nowhere in the code that this config is read.

There are a child spec opts that get passed to start_link and init. This PR supports and reads ssr_adapter from those opts on the lines that you've linked. It is a separate concept from application config.