docs: update documentations

Author: Andrea Cosentino

README.md

@@ -6,7 +6,7 @@
 
 # vite-plugin-universal-api
 
-### Seamless Mock APIs, Accelerate Your Development Journey
+### Accelerate Your Development Journey with Mock APIs without changing your client code.
 
 [![npm version](https://img.shields.io/npm/v/%40ndriadev/vite-plugin-universal-api?color=orange&style=for-the-badge)](https://www.npmjs.com/package/%40ndriadev/vite-plugin-universal-api)
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ndriadev%2Fvite-plugin-universal-api?style=for-the-badge&label=SIZE&color=yellow)
@@ -42,6 +42,10 @@
   - [REST API Handlers](#rest-api-handlers)
   - [WebSocket Handlers](#websocket-handlers)
   - [File-System Based API](#file-system-based-api)
+- [How it works](#how-it-works)
+  - [Vite proxy](#vite-proxy)
+  - [When to use what](#when-to-use-what)
+  - [Environment variables](#environment-variables)
 - [Usage Examples](#-usage-examples)
   - [File-Based Mocking](#file-based-mocking)
   - [Custom REST Handlers](#custom-rest-handlers)
@@ -608,7 +612,102 @@ interface WebSocketHandler {
 }
 ```
 
----
+## ⚙️ How it works
+
+**`vite-plugin-universal-api`** only affects development. In production, your application performs real HTTP requests.
+In a real application, you typically want to:
+
+- use local APIs during development
+- call real APIs in production
+
+You can achieve this with a simple base URL configuration:
+
+```ts
+// api.ts
+export const API_BASE_URL = import.meta.env.PROD
+  ? 'https://api.example.com'
+  : '/api'
+
+
+// usage.ts
+import {API_BASE_URL }from'./api'
+
+export async function getUsers() {
+    const res = await fetch(`${API_BASE_URL}/users`)
+    return res.json()
+}
+```
+
+- **In development**
+    - **`/api/users`** is intercepted by **`vite-plugin-universal-api`**
+    - you can return mocked or locally defined responses
+- **In production**
+    - requests go directly to **`https://api.example.com/users`**
+
+This means you can develop without a backend and switch to real APIs without changing your code.
+
+### Vite proxy
+Instead of defining local API endpoints, you can forward requests to a real backend during development using Vite's proxy.
+
+```ts
+// vite.config.ts
+export default {
+  server: {
+    proxy: {
+      '/api': {
+        target: 'https://api.example.com',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, '')
+      }
+    }
+  }
+}
+```
+
+You can then call your API as usual:
+
+```ts
+// in your file
+...
+fetch('/api/users')
+```
+
+### When to use what
+
+- **`vite-plugin-universal-api`** → mock or local APIs
+- Vite proxy → real backend during development
+
+Both approaches work with the same client code.
+
+### Environment variables
+
+For more flexibility, use .env files:
+
+```bash
+# .env.development
+VITE_API_BASE_URL=/api
+
+# .env.production
+VITE_API_BASE_URL=https://api.example.com
+```
+
+```ts
+// api.ts
+export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL
+
+// services/users.ts
+import {API_BASE_URL }from'../api'
+
+export async function getUsers() {
+    const res = await fetch(`${API_BASE_URL}/users`)
+    return res.json()
+}
+```
+
+### Result
+
+- **`Development`** → mocked response from local files
+- **`Production`** → real API calls
 
 ## 💡 Usage Examples
 

docs/examples/index.md

@@ -86,6 +86,71 @@ universalApi({
 })
 ```
 
+## Development strategies
+
+### 1. Local APIs (vite-plugin-universal-api)
+
+- fully mocked
+- no backend required
+
+```ts
+// api/users.handler.ts
+export default {
+    pattern: '/users/{id}',
+    method: 'GET',
+    handle: async (req, res) => {
+        const user = await db.findUser(req.params.id)
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify(user))
+    }
+}
+```
+
+### 2. Real backend via Vite proxy
+
+- no mocks
+- real API during development
+
+```ts
+// vite.config.ts
+export default {
+    server: {
+        proxy: {
+            '/api': {
+                target:'https://api.example.com',
+                changeOrigin:true,
+                rewrite: (path) =>path.replace(/^\/api/,'')
+            }
+        }
+    }
+}
+```
+
+### Shared client code
+
+```ts
+fetch('/api/users')
+```
+
+Both approaches work without changing your application code. You can switch between mocked APIs and a real backend without changing your client code.
+
+### Optional: Environment variables
+
+For more flexibility, use **`.env`** files:
+
+```bash
+# .env.development
+VITE_API_BASE_URL=/api
+
+# .env.production
+VITE_API_BASE_URL=https://api.example.com
+```
+
+```ts
+// api.ts
+export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL
+```
+
 ## Browse All Examples
 
 Click on any example below to see the complete implementation:

docs/guide/getting-started.md

@@ -114,7 +114,26 @@ Add some mock data:
 ]
 ```
 
-### 3. Start Development Server
+This file will handle requests to:
+
+```ts
+GET /api/users
+```
+
+### 3. Call the API from your app
+```ts
+// services/users.ts
+export async function getUsers() {
+    const res = await fetch('/api/users')
+
+    if (!res.ok) {
+        throw new Error('Failed to fetch users')
+    }
+
+    return res.json()
+}
+```
+### 4. Start Development Server
 
 ```bash
 npm run dev
@@ -124,9 +143,10 @@ npm run dev
 
 Your mock data is now available:
 
-```bash
+```ts
 # Fetch all users
-curl http://localhost:5173/api/users
+...
+const result = await getUsers();
 
 # Returns:
 # [
@@ -135,6 +155,101 @@ curl http://localhost:5173/api/users
 # ]
 ```
 
+## 🌐 Using real APIs in production
+
+In a real application, you usually want:
+
+- **mocked endpoints during development**
+- **real APIs in production**
+
+You can achieve this with a simple configuration.
+
+### Centralize your API base URL
+
+```ts
+// api.ts
+export const API_BASE_URL=import.meta.env.PROD
+    ? 'https://api.example.com'
+    : '/api'
+```
+
+### Use it in your services
+
+```ts
+// services/users.ts
+import {API_BASE_URL }from'../api'
+
+export async function getUsers() {
+    const res = await fetch(`${API_BASE_URL}/users`)
+
+    if (!res.ok) {
+        throw new Error('Failed to fetch users')
+    }
+
+    return res.json()
+}
+```
+
+### How it works
+
+- **Development**
+    - **`/api/users`** is handled by **`vite-plugin-universal-api`**
+    - responses come from your local files (e.g. **`api/users.get.ts`**)
+- **Production**
+    - requests go to **`https://api.example.com/users`**
+    - your app behaves like a standard client
+
+### **::: tip**
+
+**`vite-plugin-universal-api`** only affects development.
+
+In production, your application performs real HTTP requests.
+
+:::
+
+### 🧪 Optional: Environment variables
+
+For more flexibility, use **`.env`** files:
+
+```bash
+# .env.development
+VITE_API_BASE_URL=/api
+
+# .env.production
+VITE_API_BASE_URL=https://api.example.com
+```
+
+```ts
+// api.ts
+export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL
+```
+
+### 🔧 Alternative: Vite proxy
+
+If you prefer not to define local endpoints, you can proxy requests:
+
+```ts
+// vite.config.ts
+export default {
+    server: {
+        proxy: {
+            '/api': {
+                target:'https://api.example.com',
+                changeOrigin:true,
+                rewrite: (path) =>path.replace(/^\/api/,'')
+            }
+        }
+    }
+}
+```
+
+### 🧠 Summary
+
+- define API routes as files during development
+- call them using **`fetch('/api/...')`**
+- switch to real APIs in production with a base URL
+- no changes needed in your business logic
+
 ## What's Next?
 
 Now that you have a basic setup running, explore more features: