Docs unclear on how to handle forms for static sites

[JakeHadley]

I'm going through the gauntlet of learning astro by building my own site, and I had a good time going through the basics and getting a static site up and running. I was able to integrate a component library and everything, had a few pages, routing, etc. was great.

But when it came time to add a form and call an api, I got lost real quick. The first page I found was the build-forms recipe. And that indicated that the project needed to be SSR'd for forms to work in Astro. So I went through those steps begrudgingly, because I didn't feel like I should set my whole project to output: 'server' to handle a form.

Then the very next recipe had an example with a front-end framework, which I also didn't want to use just to do a form.

Then I looked at api endpoints, and just got confused real quick.

I already have an issue open for this, but I think it warrants a larger discussion on how to do some simple form stuff quickly in Astro.

My suggestion would be to have another section of the docs (maybe in the recipes) that are dedicated to interactivity on static sites.

[JusticeMatthew]

Just reposting my comment from discord regarding this

I think a good solution would be to update the script handling docs to use a very minimal form example instead of the confetti example which admittedly is cool, but probably not very helpful for as many use cases

[sarah11918]

Also pointing out from the Discord discussion that there are in fact many ways to "do forms" in Astro (which is why we already have multiple recipes!), so it can admittedly get a bit complicated. 😅

Will note there's already a related open issue that we've discussed and added the help wanted label at #10374 .

[delucis]

To answer the question a bit more generally: for static sites you generally can’t handle form submissions. They are a folder full of HTML files with no way to receive and do stuff with forms on the server. Instead there are a few alternative approaches people tend to use:

• Use some custom hosting platform feature. For example, Netlify Forms allow form submissions even from static sites. If the hosting platform has such a feature, then you can follow the docs for their specific service.

• Use a third-party API. Here you might set up a client-side form that instead of submitting to your server, triggers a fetch() call to post the user data to some other service you have set up (for example it might send stuff to a newsletter signup service, or a contact form service, etc.)

• Use your own API. Here the site might be static but there’s some dynamic server logic somewhere that forms can talk to. This could be within the same Astro project by using export const prerender = false; in your endpoints that handle this to make a “hybrid” part-static, part-on-demand-rendered site. Or it could be a separate service you host yourself elsewhere.

Long story short: you do need some kind of server that knows how to process user data, but there are several approaches and what you choose can depend a bit on your circumstances.

[JusticeMatthew]

That makes sense to me as to why the confetti script was used as an example

[JakeHadley]

Yeah that makes a lot more sense. I think I've discovered these options in trying to figure out how to do what I wanted with forms on my static site. I'd suggest that there be more of a distinction within individual pages of the docs for how to handle static vs server "actions". The whole site doesn't need to be server rendered to handle form submissions, for example. And, granted, solutions for these kinds of issues certainly don't (and shouldn't) come from the astro team, but I think making proper distinctions of what is necessary on the astro side to handle certain use cases would be helpful.