# express-auto-frontend

[![npm version](https://badge.fury.io/js/express-auto-frontend.svg)](https://badge.fury.io/js/express-auto-frontend)

Effortlessly connect and serve any modern frontend (React, Vue, Angular, Svelte) with your Express backend in development and production.

---

## Why Express Auto Frontend?

Developers often face repetitive tasks when connecting a frontend and backend:

- Manually setting up proxies for dev servers
- Handling CORS issues
- Remembering frontend build paths
- Writing separate deployment scripts  

`express-auto-frontend` **automates all of this**, giving you a seamless full-stack development experience.

---

## Advantages

- **Automatic Detection:** Detects your frontend framework (React, Vue, Angular, Svelte, Nuxt, or static files).  
- **Zero-Config Dev Proxy:** Automatically proxies API requests to your backend during development.  
- **Production Ready:** Serves optimized static builds with SPA routing support.  
- **Framework Agnostic:** Works with all major modern frontends and static sites.  
- **Unified Development Workflow:** One server to run, one URL to access, no CORS headaches.  

---

## Use Case Scenario

Imagine you have a React frontend built with Vite and an Express API backend. Traditionally, you'd:

1. Start your Express server on port 3000
2. Start the React dev server on port 5173
3. Configure a proxy in `vite.config.js` to send API calls to Express
4. Deal with CORS issues in production builds  

With `express-auto-frontend`:

1. You just call `include(app, '../frontend')` in your Express server
2. The frontend is automatically detected
3. Dev server starts and proxies are automatically configured
4. Production build is served from Express  
All of this **without additional configuration**.

---

## Installation

```bash
npm install express-auto-frontend

Quick Start

server.js

const express = require('express');
const include = require('express-auto-frontend');

const app = express();
const PORT = 3001;

// API routes
app.get('/api/message', (req, res) => {
    res.json({ message: 'Hello from the backend!' });
});

// Automatically include frontend (detects React, Vue, Angular, Svelte, or static)
include(app, '../frontend');

app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
});

What happens now:

• Dev: Frontend dev server runs automatically, /api/* routes go to Express, everything else goes to frontend dev server.
• Prod: Static build served automatically with SPA routing fallback.

How It Works

Development Mode

• Express runs on your chosen backend port (e.g., 3001).
• Frontend dev server runs on its default port (e.g., Vite: 5173, Vue CLI: 8080).
• API requests (/api/*) are proxied to Express.
• Frontend requests (/*) are proxied to the frontend dev server.
• Provides one unified URL during development.

Production Mode

• Frontend npm run build outputs static files (dist/build).
• Express serves static files automatically.
• SPA routing is supported by fallback to index.html.

Configuration

Optional config object as the third argument:

include(app, '../frontend', {
    backendPort: 3001, // Required for proxying
    devPort: 8080,     // Override frontend dev server port
    buildDir: 'build', // Override build directory
    devScript: 'start' // Override npm dev script
});

Default Framework Configurations

| Framework | Dev Port | Build Dir | Dev Script | | ------------ | -------- | ----------------- | ---------- | | React (Vite) | 5173 | dist | dev | | Vue (CLI) | 8080 | dist | serve | | Angular | 4200 | dist/project-name | start | | SvelteKit | 5173 | build | dev |

Supported Frontends

• ✅ React (Vite or CRA)
• ✅ Vue (Vue CLI or Nuxt)
• ✅ Angular
• ✅ Svelte / SvelteKit
• ✅ Static HTML or Pug

License

MIT

## **🔧 Development Workflow**

┌──────────────────────────┐ │ Browser (User) │ └───────────────┬──────────┘ │ Frontend Requests (/, /assets, etc.) │ ▼ ┌──────────────────────┐ │ Frontend Dev Server │ │ (React/Vue/Angular/ │ │ Svelte, etc.) │ └──────────┬───────────┘ │ Hot Reload / HMR │ ─────────────────┼──────────────────────────── │ API Requests (/api/*) │ ▼ ┌──────────────────────┐ │ Express Backend │ │ (API + Proxying) │ └──────────────────────┘

### **How it works in dev:**

* Browser requests **frontend UI** → sent to the **frontend dev server** (Vite/Webpack/Angular CLI).
* Browser requests **`/api/...`** → Express backend handles them.
* Express proxies UI requests to frontend dev server automatically.
* Full hot-reloading & unified origin → **no CORS needed**.

---

## **🚀 Production Workflow**

┌──────────────────────────┐ │ Browser (User) │ └───────────────┬──────────┘ │ All UI Requests (/, /js/, /css/) │ ▼ ┌──────────────────────┐ │ Express Serves Built │ │ Frontend (dist/ │ │ build/ production) │ └──────────┬───────────┘ │ SPA Fallback (index.html) ─────────────────┼──────────────────────────── │ API Requests (/api/*) │ ▼ ┌──────────────────────┐ │ Express Backend │ │ (API Only) │ └──────────────────────┘

### **How it works in production:**

* Browser requests the UI → Express serves files from `dist` / `build`.
* Client-side routing works using **index.html fallback**.
* `/api/*` is handled normally by Express.
* No dev server is running.

---

## **✨ Combined Architecture Overview**

      ┌─────────────────────────┐
      │   express-auto-frontend │
      │       (Middleware)      │
      └───────────┬────────────┘
                  │ Auto-detects framework
  ┌───────────────┼────────────────┬─────────────────────┐
  ▼               ▼                ▼                     ▼

React Project Vue Project Angular Project Svelte/SvelteKit (Vite/CRA) (Vue CLI/Nuxt) (ng CLI) (Kit)

             ┌─────────────────────────────┐
             │   Development Mode          │
             │  - Runs Dev Server         │
             │  - Proxies automatically    │
             └───────────────┬─────────────┘
                             │
                             ▼
                      Unified Server
                 http://localhost:<backendPort>

             ┌──────────────────────────────┐
             │      Production Mode         │
             │   - Serves static build      │
             │   - Handles SPA fallback     │
             └──────────────────────────────┘