feat: Add more options for generating server fn routes

[spencewenski]

Summary

This PR adds a few different options to customize the generated server fn API routes.

Configure the default prefix

Allow configuring the default prefix for server function API routes. This is useful to override the default prefix (/api) for all server functions without needing to manually specify via #[server(prefix = "...")] on every server function.

Allow disabling the server fn hash

Also, allow disabling appending the server functions' hashes to the end of their API names. This is useful when an app's client side needs a stable server API. For example, shipping the CSR WASM binary in a Tauri app. Tauri app releases are dependent on each platform's distribution method (e.g., the Apple App Store or the Google Play Store), which typically are much slower than the frequency at which a website can be updated. In addition, it's common for users to not have the latest app version installed. In these cases, the CSR WASM app would need to be able to continue calling the backend server function API, so the API path needs to be consistent and not have a hash appended.

Module path in server fn API route

Allow including the module path of the server function in the API route. This is an alternative strategy to prevent duplicate server function API routes (the default strategy is to add a hash to the end of the route). Each element of the module path will be separated by a /. For example, a server function with a fully qualified name of parent::child::server_fn would have an API route of /api/parent/child/server_fn (possibly with a different prefix and a hash suffix depending on the values of the other server fn configs).

Example

As an example, I have a server function called current_user in a sub-crate called web with module path app::account::context::current_user, I have /api/fn set as the default prefix, and I have the hash suffix disabled. This results in the following API route: /api/fn/web/app/account/context/current_user/current_user.

Related PRs

I also opened a cargo-leptos PR to add support for setting the env vars based on values in the leptos config: leptos-rs/cargo-leptos#412

[benwis]

Overall I think this looks good and would be a useful change. The hashes were added by default primarily to prevent collisions between server fn paths. Have you experimented to see what happens in that case? If I recall correctly it should throw an error.

Otherwise I think this is good to go

[spencewenski]

The hashes were added by default primarily to prevent collisions between server fn paths. Have you experimented to see what happens in that case?

Yeah, Axum throws an error when you try to add a duplicate route. I can add a comment calling this out. I think it’s okay though since removing the hashes is an opt-in behavior.

I was thinking another option to prevent conflicts could be to use the module path as the prefix for the api route. From what I was seeing though that’s not possible in macros, but I’m not super familiar with macros so I could be wrong.

[benwis]

The hashes were added by default primarily to prevent collisions between server fn paths. Have you experimented to see what happens in that case?

Yeah, Axum throws an error when you try to add a duplicate route. I can add a comment calling this out. I think it’s okay though since removing the hashes is an opt-in behavior.

I was thinking another option to prevent conflicts could be to use the module path as the prefix for the api route. From what I was seeing though that’s not possible in macros, but I’m not super familiar with macros so I could be wrong.

A comment's good, overall I don't think we have to worry about additional conflict detection as long as it throws a proper error

[spencewenski]

Yeah, Axum throws an error when you try to add a duplicate route.

I was double checking this, and I was correct that Axum throws an error. However, it appears that Actix doesn't. In that case, do we want to add a check somewhere in Leptos?

[spencewenski]

I was thinking another option to prevent conflicts could be to use the module path as the prefix for the api route. From what I was seeing though that’s not possible in macros, but I’m not super familiar with macros so I could be wrong.

I actually figured out how to do this. It would require adding const-str as a dependency in server_fn, similar to how const_format is added as a dependency. I think I would be interested in this for my project, so I'll open this as a separate PR.

Here's the code: spencewenski#1. I'll move the PR to the main leptos repo once this PR is merged. I added this to this PR.

[spencewenski]

Hey @benwis , are you able to review/approve this?

[spencewenski]

Hey @gbj, no rush, but can you take a look at this when you get a chance? I'm hoping to get this into 0.8 because it requires a semver breaking change to the LeptosOptions struct.

[benwis]

As is I think this makes sense and works pretty well. I do feel like you might want to version the server fn api for your use case of different versions

[benwis]

@spencewenski the checks here say you're missing a ServerFnError import in the actix file. If you can make those pass I'm happy to merge

[spencewenski]

As is I think this makes sense and works pretty well. I do feel like you might want to version the server fn api for your use case of different versions

@benwis Can you elaborate on this? Do you mean bump the server_fn and server_fn_macro crates? Or do you mean I would want to version my APIs in my application?

@spencewenski the checks here say you're missing a ServerFnError import in the actix file. If you can make those pass I'm happy to merge

This appears to be broken in the leptos_0.8 branch -- it was broken in a previous PR too. I can fix try to fix it though if you want.

• PR: chore: upgrade axum to v0.8 #3439
• Workflow run: https://github.com/leptos-rs/leptos/actions/runs/12834906687/job/35793186558

[benwis]

As is I think this makes sense and works pretty well. I do feel like you might want to version the server fn api for your use case of different versions

Can you elaborate on this? Do you mean bump the server_fn and server_fn_macro crates? Or do you mean I would want to version my APIs in my application?

@spencewenski the checks here say you're missing a ServerFnError import in the actix file. If you can make those pass I'm happy to merge

This appears to be broken in the leptos_0.8 branch -- it was broken in a previous PR too. I can fix try to fix it though if you want.

* PR: [chore: upgrade `axum` to `v0.8` #3439](https://github.com/leptos-rs/leptos/pull/3439)

* Workflow run: https://github.com/leptos-rs/leptos/actions/runs/12834906687/job/35793186558

Oh yeah, for versioning this isn't a PR change, but for example you might have a version endpoint or you might have your server fn URL include the api version.

I see that it's broken elsewhere, if you'd like to fix it it looks easy, otherwise I'll just merge this and then try to fix it.

EDIT: I see you beat me to it

[benwis]

Well that's fun and unlikely to be related to this PR. So I'll merge this and figure the rest out later

[spencewenski]

Thanks for your help, @benwis! 🎉

[benwis]

No trouble, feel free to poke me on Discord if you need me, sometimes I miss git notifications. Getting merged into a noncompiling repo isn't optimal of course

…

On Fri, Jan 24, 2025, at 8:15 PM, Spencer Ferris wrote: Thanks for your help, @benwis <https://github.com/benwis>! 🎉 — Reply to this email directly, view it on GitHub <#3438 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVBTCKNU46CL3AYMUTPEFL2MMFVJAVCNFSM6AAAAABURGEIL6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMJTG43DSNRQGY>. You are receiving this because you were mentioned.Message ID: ***@***.***>