FRONTEND_CONNECTION_GUIDE.md

🚀 Frontend Connection to Hugging Face Backend

✅ Configuration Complete!

Your Next.js frontend is now configured to connect to your Hugging Face Space backend.

---

📋 Changes Made

1. ✅ Frontend Environment Configuration

Created: frontend/.env.local

NEXT_PUBLIC_API_URL=https://baveshraam-open-notebook.hf.space
INTERNAL_API_URL=https://baveshraam-open-notebook.hf.space

This tells the frontend where to find your deployed backend API.

2. ✅ API Client Already Configured

File: frontend/src/lib/api/client.ts

The API client already uses dynamic configuration:

• ✅ Reads from process.env.NEXT_PUBLIC_API_URL
• ✅ Falls back to auto-detection
• ✅ Ultimate fallback to http://127.0.0.1:5055

No changes needed! The existing code will automatically use your .env.local settings.

3. ✅ CORS Configuration Updated

File: api/main.py

Updated CORS to allow requests from:

• ✅ http://localhost:3000 (local development)
• ✅ http://127.0.0.1:3000 (local development)
• ✅ https://baveshraam-open-notebook.hf.space (your HF Space)
• ✅ * (wildcard - allows any origin)

4. ✅ Hardcoded URLs Checked

All hardcoded localhost:5055 references in the frontend are:

• ✅ Fallback defaults only (when env vars not set)
• ✅ Example text in error messages (documentation)
• ✅ No action needed - proper fallback behavior

---

🎯 Next Steps

Step 1: Deploy Backend Changes to Hugging Face

The CORS update needs to be deployed to your Hugging Face Space:

git add api/main.py
git commit -m "Update CORS for frontend connection"
git push

Wait for Hugging Face to rebuild (check the Space logs).

Step 2: Start Your Frontend Locally

cd frontend
npm install  # If not already done
npm run dev

Your frontend will start on http://localhost:3000 and connect to:

• Backend API: https://baveshraam-open-notebook.hf.space

Step 3: Test the Connection

1. Open browser: http://localhost:3000
2. Check browser console for API connection messages
3. Try creating a notebook or any API-dependent feature
4. Check Network tab to verify requests go to your HF Space URL

---

🔍 How It Works

Configuration Priority

The frontend uses a smart fallback system:

1. Runtime config from /config endpoint (uses .env.local)
   ↓
2. Build-time NEXT_PUBLIC_API_URL
   ↓
3. Auto-detection from browser URL
   ↓
4. Fallback to http://127.0.0.1:5055

Environment Variables

Variable	Used By	Purpose
NEXT_PUBLIC_API_URL	Browser	Client-side API calls
INTERNAL_API_URL	Next.js Server	Server-side proxying

URL Structure

The frontend automatically constructs API URLs:

• Base URL: https://baveshraam-open-notebook.hf.space
• API Endpoint: /api (added automatically)
• Full API URL: https://baveshraam-open-notebook.hf.space/api

---

🛠️ Troubleshooting

Issue: "Failed to fetch" or CORS errors

Solution:

1. Verify backend is running: https://baveshraam-open-notebook.hf.space/health
2. Check backend logs for CORS rejections
3. Ensure CORS changes were deployed (check git commit)

Issue: Frontend still connects to localhost

Solution:

1. Verify .env.local file exists in frontend/ directory
2. Restart Next.js dev server: npm run dev
3. Check browser console for config messages
4. Clear browser cache and reload

Issue: 404 errors on /api/* endpoints

Solution:

1. Check that backend is running: https://baveshraam-open-notebook.hf.space/api/config
2. Verify the URL doesn't have double /api/api/
3. Check Next.js rewrite configuration in next.config.ts

---

📝 Environment Files Reference

.env.local (active configuration)

Your current deployment settings.

.env.local.example (template)

Copy this when deploying to new environments.

.env.example (backend configuration)

Backend environment variables (already configured on HF Space).

---

🎉 Success Indicators

You'll know the connection works when:

1. ✅ Browser console shows: ✅ [Config] Successfully loaded API config
2. ✅ Network tab shows requests to baveshraam-open-notebook.hf.space
3. ✅ No CORS errors in browser console
4. ✅ Features like "Create Notebook" work correctly
5. ✅ Health check responds: https://baveshraam-open-notebook.hf.space/health

---

🚀 Deploy Frontend (Optional)

When ready to deploy your frontend:

Vercel / Netlify

Add environment variables in dashboard:

NEXT_PUBLIC_API_URL=https://baveshraam-open-notebook.hf.space
INTERNAL_API_URL=https://baveshraam-open-notebook.hf.space

Docker

docker build -t open-notebook-frontend ./frontend
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=https://baveshraam-open-notebook.hf.space \
  -e INTERNAL_API_URL=https://baveshraam-open-notebook.hf.space \
  open-notebook-frontend

---

📚 Architecture Overview

┌─────────────────────┐
│   Browser           │
│   localhost:3000    │
└──────────┬──────────┘
           │ NEXT_PUBLIC_API_URL
           ↓
┌─────────────────────────────────────┐
│   Hugging Face Space Backend        │
│   baveshraam-open-notebook.hf.space │
│                                     │
│   ┌──────────┐      ┌──────────┐  │
│   │ FastAPI  │ ←──→ │ SurrealDB│  │
│   └──────────┘      └──────────┘  │
└─────────────────────────────────────┘

---

🎊 You're All Set!

Your frontend is now ready to connect to your Hugging Face deployed backend. Start the frontend with npm run dev and test away!