Feature/support configurable api base url (#19)

* feat(routes): make relay base url configurable

fixes #17

* chore(routes): update wiki to incorporate `routes.apiBaseUrl` config

config/nimbus.php

@@ -68,6 +68,24 @@ return [
         */
 
         'versioned' => false,
+
+        /*
+          |--------------------------------------------------------------------------
+          | API Base URL
+          |--------------------------------------------------------------------------
+          |
+          | This value defines the base URL that Nimbus will use when relaying
+          | API requests from the UI. It is useful in cases where your API is
+          | hosted on a different domain, port, or subpath than the UI itself.
+          |
+          | If left null, Nimbus will automatically use the same host and scheme
+          | as the incoming request that triggered the relay. This is the
+          | recommended default for most deployments where the API and UI share
+          | the same origin.
+          |
+          */
+
+        'apiBaseUrl' => null,
     ],
 
     /*

resources/views/app.blade.php

@@ -36,7 +36,7 @@
         'headers' => isset($headers) ? json_encode($headers) : null,
         'routeExtractorException' => isset($routeExtractorException) ? json_encode($routeExtractorException) : null,
         'isVersioned' => config('nimbus.routes.versioned'),
-        'apiBaseUrl' => request()->getSchemeAndHttpHost(),
+        'apiBaseUrl' => config('nimbus.routes.apiBaseUrl', request()->getSchemeAndHttpHost()),
         'currentUser' => isset($currentUser) ? json_encode($currentUser) : null,
     ]);
 

wiki/contribution-guide/README.md

@@ -361,9 +361,9 @@ composer run setup
 
 #### 3. Start a Web Server
 
-**Important:** The relay endpoint requires a real web server. Do not use `php artisan serve`.
+**Important:** The relay endpoint requires a real web server by default. Using `php artisan serve` alone won't work out of the box (check [#3.1](#31-using-it-without-a-real-server) for instructions on how to make it work).
 
-**Options:**
+**Suggeted Options:**
 - **Laravel Herd** - Recommended for macOS.
 - **Laravel Sail** - Docker-based environment.
 - **Valet** - Nginx-based for macOS.
@@ -373,6 +373,27 @@ composer run setup
 
 PHP's built-in server is single-threaded. When the relay endpoint makes a request back to the application, it creates a deadlock where the server waits for itself to respond.
 
+#### 3.1. Using it without a real server
+
+If you need to run Nimbus without a dedicated web server, you can still use php artisan serve with a two-server setup.
+
+A. In the nimbus-dev directory, start the main development process:
+```bash
+composer dev
+```
+
+B. In a separate terminal tab (or windo), start another PHP server:
+```bash
+php artisan serve
+```
+
+C. Once both are running, open your config/nimbus.php file and set the routes.apiBaseUrl value to the URL of the second server (the one started with php artisan serve).
+
+```php
+// Example.
+'apiBaseUrl' => 'http://127.0.0.1:8000',
+```
+
 #### 4. Run Frontend Development Server
 
 ```bash

wiki/user-guide/README.md

@@ -347,6 +347,7 @@ return [
 | **`allowed_envs`** | Environments where Nimbus is enabled. Avoid production for security reasons. | `['local', 'staging']` | `['testing', 'local']` |
 | **`routes.prefix`** | The base path used to detect application routes. Only routes starting with this prefix are analyzed. | `'api'` | `'api/v1'` |
 | **`routes.versioned`** | Enables version parsing for routes like `/api/v1/...`. | `false` | `true` |
+| **`routes.apiBaseUrl`** | The base URL used when Nimbus relays API requests from the UI. Useful when the API runs on a different domain or port. If set to null, Nimbus will default to the same host and scheme as the incoming request.| null | `http://127.0.0.1:8001` |
 | **`auth.guard`** | The Laravel guard used for the API requests authentication. | `'api'` | `'web'` |
 | **`auth.special.injector`** | Injector class used to attach authentication credentials to outgoing requests. Must implement `SpecialAuthenticationInjectorContract`. | `RememberMeCookieInjector::class` | `TymonJwtTokenInjector::class` |
 | **`headers`** | Global headers applied to all outgoing requests. Supports static values or enum generators. | `[]` | `['x-request-id' => GlobalHeaderGeneratorTypeEnum::UUID]` |