Vadym/obsidian
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
obsidian/wiki/connections/optical-dev-apache-vite-basepath.md
Vadym Samoilenko 401c22d9ff vault backup: 2026-04-27 18:22:09
2026-04-27 18:22:09 +01:00

3.7 KiB
Raw Blame History

title description connects created updated
Connection: optical-dev Apache Subpath + Vite basePath The two-system pairing that makes React SPAs work at /project-name/ — Apache and Vite must be configured together or nothing works
architecture/optical-dev-server-deploy
tech-patterns/react-vite-typescript
concepts/nextjs-basepath-auth-redirects
2026-04-27 2026-04-27

Connection: optical-dev Apache Subpath + Vite basePath

The Connection

React SPAs deployed to optical-dev live at a URL subpath (/barclays-banner-builder/) not the domain root. This requires Apache and Vite to both be configured with the same base path — getting one wrong without the other causes different but equally confusing failures.

Key Insight

Apache routes to the SPA. Vite tells the SPA where it lives. These are two independent configurations that must match. A mismatch produces symptoms that look like routing bugs or blank pages, not configuration errors.

The Two Configurations That Must Match

Apache fragment (/opt/project/deploy/apache-project.conf)

# API proxy (MUST come before Alias)
ProxyPass        /project-name/api/ http://127.0.0.1:8010/api/
ProxyPassReverse /project-name/api/ http://127.0.0.1:8010/api/

# SPA static files
Alias /project-name /var/www/html/project-name
<Directory /var/www/html/project-name>
    RewriteEngine On
    RewriteBase /project-name/
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.html [L]
</Directory>

Vite + React (vite.config.ts + main.tsx)

// vite.config.ts
export default defineConfig({
  base: process.env.VITE_BASE_PATH ?? "/",
})

// main.tsx
<BrowserRouter basename={import.meta.env.VITE_BASE_PATH ?? "/"}>

// api calls — must include base path
const API = import.meta.env.VITE_BASE_PATH ?? "";
fetch(`${API}/api/endpoint`)

Build command

VITE_BASE_PATH=/project-name npm run build

What Breaks When Misconfigured

Misconfiguration Symptom
Apache has subpath, Vite doesn't App loads at /project-name/ but JS assets 404 (wrong asset paths)
Vite has basePath, Apache doesn't 404 on all subpath URLs
API calls don't include basePath API calls work locally (no Apache), fail in prod
ProxyPass AFTER Alias Apache serves index.html for all /api/ calls → API returns HTML → JSON parse error
Azure AD redirect URI doesn't include basePath Auth callback 404 after login

Auth + basePath

Azure AD redirect URI must include the subpath. See wiki/concepts/nextjs-basepath-auth-redirects:

✅ https://optical-dev.oliver.solutions/project-name/auth/callback
❌ https://optical-dev.oliver.solutions/auth/callback

In MSAL config:

auth: {
  redirectUri: `${import.meta.env.VITE_BASE_PATH}/auth/callback`
}

Checklist When Deploying a New SPA to optical-dev

  • Apache fragment: ProxyPass before Alias, trailing slashes on ProxyPass
  • Vite config: base: VITE_BASE_PATH
  • React Router: basename={VITE_BASE_PATH}
  • All fetch() calls: prefix with VITE_BASE_PATH
  • Build command: VITE_BASE_PATH=/project npm run build
  • Azure AD redirect URI: includes subpath in Portal + env var
  • Apache configtest passes before reload

Related