Properly document our client deployment

[sodic]

In production, our client is just a bunch of static files. When you input a non-existent file path into the address bar (or the browser tries to redirect to it), the navigation fails with a 404 - no surprises there.

You can see this behavior by serving the client files locally and trying to access http://localhost:3000/login directly from the address bar.

Therefore: for Wasp client deployments to work, the server that's serving the static files must return index.html for all extension-less paths (regardless of the path requested by the browser).
This way, the static server delegates all routing to the React Router on the frontend, which then knows what to do. The extension-less part is important because we still want to properly serve all other static resources (CSS, HTML, JS, images, etc.)

To solve this problem on Fly.io, we've configured our Go server to fall back onto index.html for all non-existent paths:

FROM pierrezemb/gostatic
CMD [ "-fallback", "index.html" ]
COPY ./dist/ /srv/http/

What needs to be done:

1. Decide whether fallback is the best option - Fallback means "return index.html when you can't find the requested path on disk. What we truly want is "return index.html for all paths without an extension." A possible edge case where fallback becomes problematic is a user-defined route that accidentally resolves to an existing extension-less file on disk (unlikely). Fallback might also have implications on response status codes.
2. Modify our docs - Our docs say "Since the app's frontend is just a bunch of static files, you can deploy it to any static hosting provider.". But that's not all there is to it. The docs should also mention that your hosting provider must make sure to resolve all paths to index.html. Perhaps we should include examples.

Easy solutions:

• npx serve -s - the -s or --single flag is meant for serving single page apps. The --help command says for the flag: Rewrite all not-found requests to index.html.

Note

Since our docs don't mention this problem at all, and many user deploy the frontend on their own (without using Fly.io), how come we haven't heard any complaints? Are most servers configured to fall back onto index.html by default? Or are they hitting the issue and giving up?

[sodic]

User hitting this: https://discord.com/channels/686873244791210014/1290413532772564992/1290413532772564992

[onurcanari]

I encountered same error on Vercel when deploying from GitHub Actions using the CLI. I resolved this by creating a vercel.json file in .wasp/build/web-app/build with the following rewrite configuration:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

This configuration ensures all routes are redirected to index.html, which solved the issue. Afterward, I deployed successfully with this command:

vercel --prod --token=${{ secrets.VERCEL_TOKEN }} --local-config=vercel.json

Sorry if this isn’t the right place. I wanted to share this for anyone else attempting the same thing.

[Martinsos]

I encountered same error on Vercel when deploying from GitHub Actions using the CLI. I resolved this by creating a vercel.json file in .wasp/build/web-app/build with the following rewrite configuration:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

This configuration ensures all routes are redirected to index.html, which solved the issue. Afterward, I deployed successfully with this command:

vercel --prod --token=${{ secrets.VERCEL_TOKEN }} --local-config=vercel.json

Sorry if this isn’t the right place. I wanted to share this for anyone else attempting the same thing.

Thanks, this helps!