---
title: "Connection: optical-dev Apache Subpath + Vite basePath"
description: "The two-system pairing that makes React SPAs work at /project-name/ — Apache and Vite must be configured together or nothing works"
connects:
  - "architecture/optical-dev-server-deploy"
  - "tech-patterns/react-vite-typescript"
  - "concepts/nextjs-basepath-auth-redirects"
created: 2026-04-27
updated: 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`)
```apache
# 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`)
```ts
// 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
```bash
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|nextjs-basepath-auth-redirects]]:

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

In MSAL config:
```ts
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

- [[wiki/architecture/optical-dev-server-deploy|optical-dev-server-deploy]] — full Apache config reference
- [[wiki/tech-patterns/react-vite-typescript|react-vite-typescript]] — Vite patterns
- [[wiki/concepts/nextjs-basepath-auth-redirects|nextjs-basepath-auth-redirects]] — basePath + auth
- [[wiki/architecture/troubleshooting-playbooks|troubleshooting-playbooks]] — when it breaks
