docs: add warning about azure functions stability

[GerryWilko]

🔗 Linked issue

❓ Type of change

This PR adds a warning to the Azure Functions page to clarify that support for this deployment type is not currently working reliably.

I got myself a little stuck in a hole trying to fix this issue for a service I wished to deploy to an Azure Function to later realise that it doesn't really work at present. Hopefully this warning will help someone to avoid Azure Functions for now.

The work arounds listed in unjs/nitro-deploys#48 may be helpful to some but I couldn't find a way to get my Nuxt 3 deployment working properly.

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[nuxt-studio]

✅ Live Preview ready!

Name	Edit	Preview	Latest Commit
nitro	Edit on Studio ↗︎	View Live Preview	0af3999

[pi0]

Thanks! Checking with @danielroe if we should deprecate preset fully. Because it was more of an experiment as I recall.

[danielroe]

I think we should keep the preset. Similar to AWS Lambda, it's a lower level preset that might be used in advanced use cases but is almost certainly not the right preset to pick, standalone. (For example, it would lack the ability to serve static assets in a performance way.)

[danielroe]

cc @itpropro who is doing some work on updating the Azure functions presets IIRC

[itpropro]

cc @itpropro who is doing some work on updating the Azure functions presets IIRC

I am currently updating the preset to Azure Functions Runtime v4. We already discussed having a hint to that in the docs, but as there are still scenarios where it is working, it's hard to make a clear statement.
I think we should merge this PR for now as it gives users a good indication of problems that currently exist, even though they are partly a result of changes at the Azure platform.

@pi0 we should definitely be more clear about the target environment, as Azure has Functions, Container Apps, Web Apps, Static Web Apps etc.. We should revise which environments we want to support in which specific configuration and integration settings.

[pi0]

For example, it would lack the ability to serve static assets in a performance way

@danielroe Indeed. More thinking we should put some presets like azure functions browser sw explicitly aside and not advice them. And if there is no plan of active maintenance, I prefer to unsupport it at all. Having this state of half-broken presets is so frustrating honestly..

@itpropro Can you please kindly open an issue in this repo that we can mention it in docs as a tracker for azure functions and perhaps what is exactly broken that needs update if v4 is absolutely necessary? (we might delay #1785 if there is a faster way of solving issues) (I can check it too but since you plan to take lead on it you probably know more context than I know currently)

[itpropro]

For example, it would lack the ability to serve static assets in a performance way

@danielroe Indeed. More thinking we should put some presets like azure functions browser sw explicitly aside and not advice them. And if there is no plan of active maintenance, I prefer to unsupport it at all. Having this state of half-broken presets is so frustrating honestly..

@itpropro Can you please kindly open an issue in this repo that we can mention it in docs as a tracker for azure functions and perhaps what is exactly broken that needs update if v4 is absolutely necessary? (we might delay #1785 if there is a faster way of solving issues) (I can check it too but since you plan to take lead on it you probably know more context than I know currently)

I will open an issue for that. I think the goal should be to have a preset that uses the provider specific tooling to be the least maintenance possible. In the Azure case I would prefer to only focus on a simple Azure Functions preset and based on that a static web apps (which also uses Azure Functions by default) one. We should probably deprecate special features like generating a static web app config. That would compromise the idea of a zero config, but would enable us to still have a Azure preset that is maintainable.

[danielroe]

related: nuxt/nuxt.com#1483

cc: @thomasgauvin

[thomasgauvin]

Thanks for the ping @danielroe. (I'm the PM on Azure Static Web Apps by the way).

While I can't speak to the issues that exist with Azure Functions, Nuxt SWA deployments seem to work quite well in my experience. I'm curious as to how SWA deployments work but Functions don't if SWA depends on them. Also, if there are any pressing SWA issues, would love to hear them so we can discuss.

Re deprecating SWA config, I think it's pretty essential to keep as you get the 'global serverless' server nature that SWA (and other similar hosts) offer. We aren't planning on making important changes to the config file any time soon, so maintenance on that could be considered relatively lower. With Functions, you may encounter limitations around the routing, etc.

All that said, as a developer, and I'm a big fan of Nuxt deployments, it's one of the few server-side rendered frameworks that actually works quite well on SWA.

[pi0]

Happy having you here dear @thomasgauvin. SWA is only preset I tried and at least inside emulator works well. Altough it seems there are some production deployment issues.

If you are on discord, would you mind to send me a DM (pi0) so I can invite you to a proper channel to keep in loop?

[itpropro]

Thanks for the ping @danielroe. (I'm the PM on Azure Static Web Apps by the way).

While I can't speak to the issues that exist with Azure Functions, Nuxt SWA deployments seem to work quite well in my experience. I'm curious as to how SWA deployments work but Functions don't if SWA depends on them. Also, if there are any pressing SWA issues, would love to hear them so we can discuss.

Re deprecating SWA config, I think it's pretty essential to keep as you get the 'global serverless' server nature that SWA (and other similar hosts) offer. We aren't planning on making important changes to the config file any time soon, so maintenance on that could be considered relatively lower. With Functions, you may encounter limitations around the routing, etc.

All that said, as a developer, and I'm a big fan of Nuxt deployments, it's one of the few server-side rendered frameworks that actually works quite well on SWA.

Hey @thomasgauvin,
thanks for the infos. There are several scenarios where the action works, but the SWA doesn’t render, where there are resolution problems with pnpm etc.. These are all solvable and I think this can be done with pretty low effort according to my test scenarios of the last few days.
Regarding the config, it’s just important that we provide some way of overwriting it for the user. Now we have several things “hardcoded”, like the platform/apiRuntime property.
I think providing a base configuration that works out of the box plus the possibility to overwrite should work.
I have been working with SWAs since the cli was not not even existent and collected a comprehensive list of scenarios and edge cases of configurations that I currently test against and also had some customers run into problems, so providing a consistently working baseline config that is still maintainable is my main goal.

[pi0]

ideally, similar to most of mainstream providers i like to see one preferred preset for azure deployment and it remains zero config. Currently we (sadly) always override a top level config which is not desired. It should be merged into .output for users.

(sorry this is all off topic here. i think 1) we need an explicit issue to track why azure_functions variant is broken to link and merge this PR asap and 2) move discussion to a proper place like discord.

[GerryWilko]

Thanks for the ping @danielroe. (I'm the PM on Azure Static Web Apps by the way).

While I can't speak to the issues that exist with Azure Functions, Nuxt SWA deployments seem to work quite well in my experience. I'm curious as to how SWA deployments work but Functions don't if SWA depends on them. Also, if there are any pressing SWA issues, would love to hear them so we can discuss.

Re deprecating SWA config, I think it's pretty essential to keep as you get the 'global serverless' server nature that SWA (and other similar hosts) offer. We aren't planning on making important changes to the config file any time soon, so maintenance on that could be considered relatively lower. With Functions, you may encounter limitations around the routing, etc.

All that said, as a developer, and I'm a big fan of Nuxt deployments, it's one of the few server-side rendered frameworks that actually works quite well on SWA.

@thomasgauvin Just FYI I think there may be some issues with Nuxt SWA deployments too. I had deployed this site https://signals.ignite.systems/ a few days ago and the routes seem broken. I didn't manage to debug this much just yet but the same deployment worked fine with preset vercel and local dev so it may not be quite as smooth on SWA just yet. I'm hoping to get back to take a closer look at what is going wrong next week.

EDIT: Just to be clear this site https://signals.ignite.systems/ is a pretty vanilla Docus site

[GerryWilko]

It seems that both Azure presets actually don't work. I been trying to debug why all morning and got no where really.

A simple docus site is not working:

npx nuxi@latest init -t themes/docus
cd docs
NITRO_PRESET=azure pnpm build
npx @azure/static-web-apps-cli deploy .output/public --api-location .output/server --deployment-token your-token-here --env production

Does not work. It appears that some static assets work but others dont and it also seems that on SSR all routes return 404 then do seem to match on hydration.

Example site: https://signals.ignite.systems

@pi0 should I raise a PR with a similar warning on the azure preset?

[pi0]

@GerryWilko can you please mirror your message in #2114 to keep track of context maybe possibly little more info.

I am busy but will do my best to investigate status of azure as soon as I can. Sorry for this all.

[GerryWilko]

Of course, thank you @pi0 absolutely no need to apologise. I'm still trying to see whats wrong. I'm currently putting together a simple reproduction.

To be honest I feel this is made much much harder due to the black box nature of the Azure Static Web App portal tools and the really difficult to use swa cli.

https://learn.microsoft.com/en-us/azure/static-web-apps/deploy-nuxtjs

The docs here and on Next.js imply the config seems to be "magic" and its not really documented how it works. I started looking at how SSR on Next.JS works with SWA to see if I could try fix it. 🤷

[pi0]

Code to all magic we do for Nitro/Nuxt:

azure swa:

• https://github.com/unjs/nitro/blob/main/src/runtime/entries/azure.ts
• https://github.com/unjs/nitro/blob/main/src/presets/azure.ts

azure fns:

• https://github.com/unjs/nitro/blob/main/src/runtime/entries/azure-functions.ts
• https://github.com/unjs/nitro/blob/main/src/presets/azure-functions.ts

(although let's mention it is not uncommon that deployment providers add special bits in their builder layer specifically for Next.js -- sadly. I hope it is not a case for azure only a guess since you have mentioned it works for Next)

[GerryWilko]

@pi0 I believe I may have found where the issue lies. I have put an explainer of what I have found on the issue you mentioned but thought it best to provide a TLDR here too. #2114 (comment)

TLDR: You cannot current use Azure Static Web Apps, with any framework it seems, when using a package manager other than npm. It appears to modify the built output, presumably applying fixes that explain the issues I am seeing. You also have limited control over the builder which may make it infeasible to use for some users.

I believe this should be called out on the Nitro presets docs pages?