fix: ensure API routes bypass SPA fallback + add troubleshooting docs (G4brym#126)

* fix: ensure API and share routes are handled by worker, not SPA fallback

The `not_found_handling = "single-page-application"` asset config causes
Cloudflare to serve index.html for any request that doesn't match a
static file — including /api/* and /share/* routes. This results in
downloads returning a ~2KB HTML page instead of the actual file.

Adding `run_worker_first = ["/api/*", "/share/*"]` ensures these routes
are always dispatched to the worker script first.

Fixes G4brym#119

* docs: add troubleshooting guide

Cover common issues: downloads returning HTML instead of files (SPA
fallback intercepting API routes), 401 errors with basic auth, and
blank page / routing errors.

Co-Authored-By: Marcelo <noreply@openclaw.ai>

---------

Co-authored-by: Debian <openclaw@openclaw.1.1.1.1>
Co-authored-by: Marcelo <noreply@openclaw.ai>

Author: 3 people

packages/docs/.vitepress/config.mts

@@ -39,6 +39,7 @@ export default defineConfig({
           items: [
             { text: 'Setup Email Explorer', link: '/guides/setup-email-explorer' },
             { text: 'Sharable Links', link: '/guides/sharable-links' },
+            { text: 'Troubleshooting', link: '/guides/troubleshooting' },
           ]
         }
       ],

packages/docs/guides/troubleshooting.md

@@ -0,0 +1,51 @@
+# Troubleshooting
+
+Common issues and solutions for R2 Explorer.
+
+## Downloads return HTML instead of the actual file
+
+**Symptoms:** Clicking "Download" in the context menu downloads a small (~2KB) HTML file instead of the actual object. Browsing and previewing files works normally.
+
+**Cause:** When using Cloudflare Workers with [static assets](https://developers.cloudflare.com/workers/static-assets/), the `not_found_handling = "single-page-application"` setting in `wrangler.toml` tells Cloudflare to serve `index.html` for any request that doesn't match a static file. This happens **before** your Worker code runs, so API requests like `/api/buckets/<bucket>/<key>` never reach the R2 Explorer backend — Cloudflare intercepts them and returns the SPA's HTML.
+
+**Fix:** Add `run_worker_first` to your `wrangler.toml` assets configuration so that API and share routes are always handled by the Worker:
+
+```toml
+# Before (broken)
+assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application" }
+
+# After (fixed)
+assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application", run_worker_first = ["/api/*", "/share/*"] }
+```
+
+After updating, redeploy with `wrangler deploy`.
+
+::: tip
+New projects created from the template already include this fix. This only affects existing deployments that were set up before this change.
+:::
+
+## Downloads fail with 401 when using Basic Auth
+
+**Symptoms:** File downloads from the right-click context menu fail with a `401 Unauthorized` error. Browsing and previewing files works fine. May work in Safari but fail in Chrome.
+
+**Cause:** The download function was creating a raw `<a>` HTML element pointing directly at the API URL and triggering `link.click()`. Browser-initiated downloads via `<a>` links do **not** include custom HTTP headers like `Authorization: Basic ...`, so the request arrives at the Worker without credentials. Chrome enforces this strictly; Safari is more lenient.
+
+**Fix:** This was fixed in [v0.5.2](https://github.com/G4brym/R2-Explorer/releases). Update your R2 Explorer dependency:
+
+```bash
+npm update r2-explorer
+wrangler deploy
+```
+
+## Dashboard shows a blank page or routing errors
+
+**Symptoms:** The dashboard loads but shows a blank page, or navigating between pages results in errors like `TypeError: Cannot read properties of undefined (reading 'name')`.
+
+**Cause:** This can happen when the Vue router's `this.$route.name` is `undefined` during navigation transitions.
+
+**Fix:** This was fixed in [v0.5.2](https://github.com/G4brym/R2-Explorer/releases). Update your R2 Explorer dependency:
+
+```bash
+npm update r2-explorer
+wrangler deploy
+```

packages/github-action/prepareDeploy.js

@@ -38,7 +38,7 @@ let wranglerConfig = `
 name = "${R2EXPLORER_WORKER_NAME}"
 compatibility_date = "2024-11-06"
 main = "src/index.ts"
-assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application" }
+assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application", run_worker_first = ["/api/*", "/share/*"] }
 `;
 
 if (R2EXPLORER_DOMAIN) {

packages/worker/dev/wrangler.toml

@@ -2,7 +2,7 @@ name = "my-r2-explorer"
 compatibility_date = "2024-11-06"
 main = "index.ts"
 workers_dev = true
-assets = { directory = "../../dashboard/dist/spa", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application" }
+assets = { directory = "../../dashboard/dist/spa", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application", run_worker_first = ["/api/*", "/share/*"] }
 
 [[r2_buckets]]
 binding = 'teste'

template/wrangler.toml

@@ -1,7 +1,7 @@
 name = "r2-explorer"
 compatibility_date = "2024-11-06"
 main = "src/index.ts"
-assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application" }
+assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application", run_worker_first = ["/api/*", "/share/*"] }
 
 # Bind R2 Buckets to your application.
 # Docs: https://r2explorer.com/getting-started/add-r2-buckets/