PluginMind Docs

Frontend Development

PluginMind’s frontend is built with Next.js 14 (App Router), TypeScript, and NextAuth. This guide helps you extend it without breaking the secure proxy flow.

🧱 Project Layout

Loading code snippet…

🔐 NextAuth Configuration (src/auth.ts)

  • Google provider only (GitHub scaffolding is present but optional).
  • Secure mode controlled via NEXT_PUBLIC_SECURE_TOKENS.
  • JWT callback stores Google tokens server-side.
  • Session callback exposes session.hasToken when secure mode is enabled.
Loading code snippet…

🛰️ Proxy Route (app/api/proxy/[...path]/route.ts)

  • Runs on the Node.js runtime.
  • Injects id_token when forwarding POST /auth/google.
  • Forwards cookies and selected headers to the FastAPI backend.
  • Retries against BACKEND_ALT_URL if the primary backend is unreachable.

Key snippet:

Loading code snippet…

When calling API routes from the frontend, use the proxy:

Loading code snippet…

🪝 Useful Hooks & Services

FilePurpose
hooks/useAuth.tsWraps NextAuth session and the hasToken flag.
services/api.service.tsCentralised fetch helper that hits the proxy with credentials included.
services/ai.service.tsFrontend helper for calling /process and /services.

When building new pages, import these utilities instead of rolling custom fetch logic.

🧪 Frontend Testing Tips

  • Use Playwright (already listed in devDependencies) for E2E flows.
  • For unit tests, react-testing-library works well with the existing component pattern.
  • Mock next-auth/react in tests to simulate authenticated states.

Example Playwright stub:

Loading code snippet…

🎨 Styling

  • Tailwind CSS + shadcn/ui components power the design system.
  • components/ui/ holds low-level components (buttons, cards, etc.).
  • Shared iconography lives in components/icons.tsx.

Remember to run pnpm lint and pnpm typecheck before committing UI changes.

🧭 Tips for Extending the App

  1. Reuse the proxy – Never call the backend directly from fetch in the browser.
  2. Keep tokens server-only – If you must expose more session detail, do it inside the proxy route.
  3. Handle 401s gracefully – Redirect users to /auth/signin when the backend responds with AUTHENTICATION_FAILED.
  4. Surface metadata – The /services endpoint returns registry metadata you can display in the UI.

Happy frontend hacking! 🎉