From 2e571fc1ccb854ed1a745626ae713ce6426dde5b Mon Sep 17 00:00:00 2001
From: fulleni <fulleni@hotmail.com>
Date: Fri, 24 Oct 2025 21:57:30 +0100
Subject: [PATCH 1/2] docs(local-setup): update mobile client and web dashboard
 environment configuration

- Replace in-code environment configuration with dart-define flags
- Add instructions for running in different environments using flutter run
- Remove outdated lib/main.dart code references
- Update step descriptions for running the applications
- Remove physical device connection note for web dashboard setup
---
 .../docs/mobile-client/local-setup.mdx        | 37 ++++++++++---------
 .../docs/web-dashboard/local-setup.mdx        | 37 ++++++++++---------
 2 files changed, 40 insertions(+), 34 deletions(-)

diff --git a/src/content/docs/mobile-client/local-setup.mdx b/src/content/docs/mobile-client/local-setup.mdx
index 0530760..93d571d 100644
--- a/src/content/docs/mobile-client/local-setup.mdx
+++ b/src/content/docs/mobile-client/local-setup.mdx
@@ -31,21 +31,22 @@ This guide will walk you through setting up and running the Flutter News App Mob
 
 4.  **Configure the Environment**
 
-    The mobile client can be run in different environments, allowing you to connect it to a live API, a local API, or run it with mock data for UI development.
-
-    -   Open the file `lib/main.dart`.
-    -   Locate the `appEnvironment` constant.
-    -   Set its value to one of the following:
-        -   `AppEnvironment.demo`: **(Recommended for UI development)** Runs the app with in-memory mock data. No backend API is required, making it perfect for focusing on UI changes and component testing.
-        -   `AppEnvironment.development`: Connects the app to a locally running instance of the API server (typically at `http://localhost:8080`).
-        -   `AppEnvironment.production`: Connects the app to your live, deployed backend API.
-
-    ```dart title="lib/main.dart"
-    // Use `AppEnvironment.demo` to run with in-memory data (no API needed).
-    // Use `AppEnvironment.development` to connect to a local backend API.
-    // Use `AppEnvironment.production` to connect to a live backend API.
-    const appEnvironment = AppEnvironment.demo;
-    ```
+    The mobile client uses compile-time variables to configure its environment. This allows you to easily switch between mock data, a local API, or a live production API without changing the code.
+
+    You can specify the environment by passing a `--dart-define` flag to the `flutter run` command.
+
+    -   **Demo (Default):** Runs the app with in-memory mock data. No backend API is required, making it perfect for focusing on UI changes and component testing.
+        ```bash
+        flutter run
+        ```
+    -   **Development:** Connects the app to a locally running instance of the API server.
+        ```bash
+        flutter run --dart-define=APP_ENVIRONMENT=development
+        ```
+    -   **Production:** Connects the app to your live, deployed backend API. You must also provide the base URL for your API.
+        ```bash
+        flutter run --dart-define=APP_ENVIRONMENT=production --dart-define=BASE_URL=https://your.api.com
+        ```
 
     <Aside>
     For the `development` environment, you must have the [API Server running locally](/docs/api-server/local-setup/) first.
@@ -57,12 +58,14 @@ This guide will walk you through setting up and running the Flutter News App Mob
 
 5.  **Run the Application**
 
-    Start the Flutter development server. Ensure you have a simulator/emulator running or a physical device connected.
+    Start the application using one of the commands from the previous step. Ensure you have a simulator/emulator running or a physical device connected.
+
+    For example, to run in `demo` mode:
 
     ```bash
     flutter run
     ```
 
-    The application will now be running on your selected device.
+    The application will now launch on your selected device.
 
 </Steps>
diff --git a/src/content/docs/web-dashboard/local-setup.mdx b/src/content/docs/web-dashboard/local-setup.mdx
index 95b3f19..a8470de 100644
--- a/src/content/docs/web-dashboard/local-setup.mdx
+++ b/src/content/docs/web-dashboard/local-setup.mdx
@@ -32,21 +32,22 @@ This guide will walk you through setting up and running the Flutter News App Web
 
 4.  **Configure the Environment**
 
-    The dashboard can be run in different environments, allowing you to connect it to a live API, a local API, or run it with mock data for UI development.
-
-    -   Open the file `lib/main.dart`.
-    -   Locate the `appEnvironment` constant.
-    -   Set its value to one of the following:
-        -   `AppEnvironment.demo`: **(Recommended for UI development)** Runs the dashboard with in-memory mock data. No backend API is required, making it perfect for focusing on UI changes and component testing.
-        -   `AppEnvironment.development`: Connects the dashboard to a locally running instance of the API server (typically at `http://localhost:8080`).
-        -   `AppEnvironment.production`: Connects the dashboard to your live, deployed backend API.
-
-    ```dart title="lib/main.dart"
-    // Use `AppEnvironment.demo` to run with in-memory data (no API needed).
-    // Use `AppEnvironment.development` to connect to a local backend API.
-    // Use `AppEnvironment.production` to connect to a live backend API.
-    const appEnvironment = AppEnvironment.demo; 
-    ```
+    The web dashboard uses compile-time variables to configure its environment. This allows you to easily switch between mock data, a local API, or a live production API without changing the code.
+
+    You can specify the environment by passing a `--dart-define` flag to the `flutter run` command.
+
+    -   **Demo (Default):** Runs the dashboard with in-memory mock data. No backend API is required, making it perfect for focusing on UI changes and component testing.
+        ```bash
+        flutter run -d chrome
+        ```
+    -   **Development:** Connects the dashboard to a locally running instance of the API server.
+        ```bash
+        flutter run -d chrome --dart-define=APP_ENVIRONMENT=development
+        ```
+    -   **Production:** Connects the dashboard to your live, deployed backend API. You must also provide the base URL for your API.
+        ```bash
+        flutter run -d chrome --dart-define=APP_ENVIRONMENT=production --dart-define=BASE_URL=https://your.api.com
+        ```
 
     <Aside>
     For the `development` environment, you must have the [API Server running locally](/docs/api-server/local-setup/) first.
@@ -58,12 +59,14 @@ This guide will walk you through setting up and running the Flutter News App Web
 
 5.  **Run the Development Server**
 
-    Start the Flutter development server, targeting the Chrome browser:
+    Start the application using one of the commands from the previous step, targeting the Chrome browser.
+
+    For example, to run in `demo` mode:
 
     ```bash
     flutter run -d chrome
     ```
 
-    The web dashboard will now be running and accessible in your Chrome browser.
+    The web dashboard will now be running and accessible in your Chrome browser. The `<Aside>` about connecting from a physical device has been removed as it is not relevant for a web-only dashboard.
 
 </Steps>

From 24fb5c6b0402359251a5f657de98661207de3c75 Mon Sep 17 00:00:00 2001
From: fulleni <fulleni@hotmail.com>
Date: Fri, 24 Oct 2025 22:07:49 +0100
Subject: [PATCH 2/2] docs(vscode): add guide for configuring VS Code launch
 environments

- Created new documentation page for configuring VS Code launch environments
- Added tips to mobile-client and web-dashboard local setup guides
- Included important security note about sensitive information in launch.json
- Provided step-by-step instructions for creating and using launch.json
---
 .../docs/mobile-client/local-setup.mdx        |  4 ++
 .../docs/vscode-launch-configurations.mdx     | 64 +++++++++++++++++++
 .../docs/web-dashboard/local-setup.mdx        |  4 ++
 3 files changed, 72 insertions(+)
 create mode 100644 src/content/docs/vscode-launch-configurations.mdx

diff --git a/src/content/docs/mobile-client/local-setup.mdx b/src/content/docs/mobile-client/local-setup.mdx
index 93d571d..6d30928 100644
--- a/src/content/docs/mobile-client/local-setup.mdx
+++ b/src/content/docs/mobile-client/local-setup.mdx
@@ -48,6 +48,10 @@ This guide will walk you through setting up and running the Flutter News App Mob
         flutter run --dart-define=APP_ENVIRONMENT=production --dart-define=BASE_URL=https://your.api.com
         ```
 
+    <Aside type="tip">
+        For an even easier workflow, you can configure your editor to run these commands for you. Check out the [Configuring VS Code Launch Environments](/docs/vscode-launch-configurations/) guide.
+    </Aside>
+
     <Aside>
     For the `development` environment, you must have the [API Server running locally](/docs/api-server/local-setup/) first.
     </Aside>
diff --git a/src/content/docs/vscode-launch-configurations.mdx b/src/content/docs/vscode-launch-configurations.mdx
new file mode 100644
index 0000000..02e9fcd
--- /dev/null
+++ b/src/content/docs/vscode-launch-configurations.mdx
@@ -0,0 +1,64 @@
+---
+title: Configuring VS Code Launch Environments
+description: A guide to setting up VS Code launch configurations for different app environments.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+To streamline the development process, you can configure Visual Studio Code to easily run your Flutter application in different environments (`demo`, `development`, or `production`) directly from the "Run and Debug" panel. This avoids the need to manually type the `flutter run` command with the correct `--dart-define` arguments each time.
+
+<Aside type="caution" title="Important Security Note">
+  The `launch.json` file can contain sensitive information, such as production API URLs or other secrets. To prevent accidentally exposing these values, it is strongly recommended to add `.vscode/launch.json` to your project's `.gitignore` file.
+
+  This ensures it remains a local-only configuration and is not committed to your version control system.
+</Aside>
+
+
+### Create a `launch.json` File
+
+1.  In your project's root directory, create a folder named `.vscode` if it doesn't already exist.
+2.  Inside the `.vscode` folder, create a new file named `launch.json`.
+3.  Copy and paste the following JSON configuration into your `launch.json` file.
+
+```json title=".vscode/launch.json"
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Demo - Flutter News App",
+            "request": "launch",
+            "type": "dart",
+            "program": "lib/main.dart",
+            "args": [
+                "--dart-define=APP_ENVIRONMENT=demo"
+            ]
+        },
+        {
+            "name": "Development - Flutter News App",
+            "request": "launch",
+            "type": "dart",
+            "program": "lib/main.dart",
+            "args": [
+                "--dart-define=APP_ENVIRONMENT=development",
+                "--dart-define=BASE_URL=http://localhost:8080"
+            ]
+        },
+        {
+            "name": "Production - Flutter News App",
+            "request": "launch",
+            "type": "dart",
+            "program": "lib/main.dart",
+            "args": [
+                "--dart-define=APP_ENVIRONMENT=production",
+                "--dart-define=BASE_URL=https://api.your-production-domain.com"
+            ]
+        }
+    ]
+}
+```
+
+### How to Use
+
+After saving the file, open the "Run and Debug" panel in VS Code (you can use the shortcut `Ctrl+Shift+D`). You will now see a dropdown menu at the top with the launch configurations: "Demo - Flutter News App", "Development - Flutter News App", and "Production - Flutter News App".
+
+Simply select the environment you want to run and press the green play button (or `F5`) to launch the application with the correct settings.
diff --git a/src/content/docs/web-dashboard/local-setup.mdx b/src/content/docs/web-dashboard/local-setup.mdx
index a8470de..9460c7c 100644
--- a/src/content/docs/web-dashboard/local-setup.mdx
+++ b/src/content/docs/web-dashboard/local-setup.mdx
@@ -49,6 +49,10 @@ This guide will walk you through setting up and running the Flutter News App Web
         flutter run -d chrome --dart-define=APP_ENVIRONMENT=production --dart-define=BASE_URL=https://your.api.com
         ```
 
+    <Aside type="tip">
+        For an even easier workflow, you can configure your editor to run these commands for you. Check out the [Configuring VS Code Launch Environments](/docs/vscode-launch-configurations/) guide.
+    </Aside>
+
     <Aside>
     For the `development` environment, you must have the [API Server running locally](/docs/api-server/local-setup/) first.
     </Aside>