From 9680cae7ee0759e3f8b611e24ef9ee2c490a3ec9 Mon Sep 17 00:00:00 2001 From: Garry Trinder Date: Mon, 27 Apr 2026 09:38:25 +0100 Subject: [PATCH 1/5] Add v2.2.0 best practices content Adds guidance for new v2.2.0 features: - YAML config support (devproxyrc.yaml/yml) - Config validation (devproxy config validate) - @dynamic=initialvalue for GenericRandomErrorPlugin - --no-watch flag to disable hot reload - Detached mode with random ports, asSystemProxy false, and devproxy status - Updated curl section to reference actual port --- assets/best-practices.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/assets/best-practices.md b/assets/best-practices.md index dccb9e5..71015b1 100644 --- a/assets/best-practices.md +++ b/assets/best-practices.md @@ -3,6 +3,8 @@ ## Configuration files - Dev Proxy configuration file is named devproxyrc.json or devproxyrc.jsonc (if you want to include comments) +- Dev Proxy also supports YAML configuration files named devproxyrc.yaml or devproxyrc.yml (v2.2.0+). When creating a YAML config, use `devproxy config new --format yaml`. +- To validate a configuration file before starting Dev Proxy, use `devproxy config validate` (v2.2.0+). - For clarity, store all Dev Proxy files in the .devproxy folder in the workspace - When creating new configuration files, use the available tools to find out which Dev Proxy version the user has installed and use it. Schema version must match the installed Dev Proxy version. - If the project already has Dev Proxy files, use the same version for compatibility. @@ -35,6 +37,7 @@ - When defining mock responses or CrudApiPlugin actions, put entries with the longest (most specific) URLs first. Entries are matched in the order they're defined, so you don't want a generic pattern like /{id} to override a more specific one like /category/{name}. - Mocks with the nth property should be defined first, because they're considered more specific than mocks without that property. - To return dynamic Retry-After header value in mock responses, use `@dynamic` as the header's value +- To return a dynamic Retry-After header value with a specific initial value, use `@dynamic=initialvalue` (e.g. `@dynamic=120`). Supported in GenericRandomErrorPlugin (v2.2.0+). - When simulating APIs and their responses, consider using the LatencyPlugin to make the API responses feel more realistic. - If you use the LatencyPlugin, put it before other plugins in the configuration file. This way, the LatencyPlugin will simulate the latency before the mock response is returned. @@ -48,7 +51,16 @@ - Hot reload works for the main configuration file (devproxyrc.json/devproxyrc.jsonc) and plugin-specific configuration files (mock files, CRUD API data files, etc.). - You don't need to manually restart Dev Proxy after making configuration changes - just save the file and the changes take effect automatically. - Hot reload helps you iterate faster when developing and testing different proxy configurations. +- To disable hot reload (e.g. in CI/CD or automated environments), use the `--no-watch` flag (v2.2.0+). + +## Detached mode + +- Dev Proxy can run in detached (background) mode (v2.2.0+). This is useful for CI/CD pipelines, automated testing, and agent-driven workflows where Dev Proxy needs to run without an interactive terminal. +- When running in detached mode, use `--output json` to get structured, machine-readable output that can be parsed by scripts and agents. +- For detached mode and CI/CD scenarios, set `port` to `0` in the configuration file (or use `--port 0` on the command line) to let the OS assign a random available port. This avoids port conflicts when running multiple Dev Proxy instances in parallel. Similarly, use `--api-port 0` for the Dev Proxy API port. +- Combine random ports with `asSystemProxy` set to `false` in the configuration file (or `--as-system-proxy false` on the command line) to prevent Dev Proxy from modifying system proxy settings. This way, each instance runs in isolation and only intercepts requests from applications explicitly configured to use its address and port. +- When using random ports, use `devproxy status` to find the actual assigned port, API URL, PID, and other details of the running instance. ## curl -- When asked for `curl` commands, include `-ikx http://127.0.0.1:8000` so that curl will ignore SSL certificate errors and use Dev Proxy, eg. `curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts/1`. \ No newline at end of file +- When asked for `curl` commands, include `-ikx http://127.0.0.1:` so that curl will ignore SSL certificate errors and use Dev Proxy. Use the actual port Dev Proxy is running on (default: 8000), eg. `curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts/1`. \ No newline at end of file From 03e27d90db691ceee27c9303c3e9c681966ed3a2 Mon Sep 17 00:00:00 2001 From: Garry Trinder Date: Mon, 27 Apr 2026 09:56:46 +0100 Subject: [PATCH 2/5] Add v2.3.0 best practices: multi-instance support and proxy URL output --- assets/best-practices.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/assets/best-practices.md b/assets/best-practices.md index 71015b1..36d920a 100644 --- a/assets/best-practices.md +++ b/assets/best-practices.md @@ -59,7 +59,9 @@ - When running in detached mode, use `--output json` to get structured, machine-readable output that can be parsed by scripts and agents. - For detached mode and CI/CD scenarios, set `port` to `0` in the configuration file (or use `--port 0` on the command line) to let the OS assign a random available port. This avoids port conflicts when running multiple Dev Proxy instances in parallel. Similarly, use `--api-port 0` for the Dev Proxy API port. - Combine random ports with `asSystemProxy` set to `false` in the configuration file (or `--as-system-proxy false` on the command line) to prevent Dev Proxy from modifying system proxy settings. This way, each instance runs in isolation and only intercepts requests from applications explicitly configured to use its address and port. +- When `asSystemProxy` is `false`, multiple Dev Proxy instances can run in parallel on the same machine (v2.3.0+). Each instance should use its own random port and configuration file. - When using random ports, use `devproxy status` to find the actual assigned port, API URL, PID, and other details of the running instance. +- In detached mode, the proxy URL is printed in the startup output (v2.3.0+). Parse this from the JSON output when using `--output json`. ## curl From bdf79d31433aa6efb453c2a702e33d4c73cb7419 Mon Sep 17 00:00:00 2001 From: Garry Trinder Date: Mon, 27 Apr 2026 10:09:02 +0100 Subject: [PATCH 3/5] Fix contradictions and improve clarity in best practices - Replace three conflicting plugin ordering rules with single definitive order - Remove duplicate $schema rule (already covered in Configuration section) - Update hot reload to cover all config types (JSON, JSONC, YAML) - Remove fluff line about hot reload iterating faster - Simplify LatencyPlugin guidance to reference plugin ordering - Clarify curl section wording - Fix proxy URL bullet to be more actionable --- assets/best-practices.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/assets/best-practices.md b/assets/best-practices.md index 36d920a..2df3105 100644 --- a/assets/best-practices.md +++ b/assets/best-practices.md @@ -25,12 +25,14 @@ ## Plugins - Before you add a plugin to the configuration, use the `FindDocs` tool to verify that it exists and get the latest plugin documentation and understand how to configure it properly. -- The order of plugins in the configuration file matters. Dev Proxy executes plugins in the order that they are listed. Plugins that can simulate a response should be put last, right before reporters. -- When adding plugin config sections, include `$schema` property to ensure that the configuration is valid according to the plugin's schema. +- The order of plugins in the configuration file matters. Dev Proxy executes plugins in the order they are listed. Use this order (top to bottom): + 1. RetryAfterPlugin (if simulating throttling — must be first to verify client backs off) + 2. LatencyPlugin (if simulating realistic response times — adds delay before responses) + 3. Other analysis/guidance plugins (e.g. GraphMinimalPermissionsGuidancePlugin) + 4. Response-simulating plugins (e.g. MockResponsePlugin, CrudApiPlugin) + 5. Reporter plugins (always last) - If you need to simulate different scenarios, for example simulating latency for an LLM vs. a regular API, you can use multiple instances of the same plugin. -- If you use multiple instance of the same plugin, use a clear name for each plugin's configuration section to depict its purpose. -- Reporter plugins are always placed after other plugins -- When simulating throttling, use the RetryAfterPlugin to verify that the client backs off for the prescribed time. Put the RetryAfterPlugin as the first plugin in the configuration. +- If you use multiple instances of the same plugin, use a clear name for each plugin's configuration section to depict its purpose. ## Mocking @@ -38,8 +40,7 @@ - Mocks with the nth property should be defined first, because they're considered more specific than mocks without that property. - To return dynamic Retry-After header value in mock responses, use `@dynamic` as the header's value - To return a dynamic Retry-After header value with a specific initial value, use `@dynamic=initialvalue` (e.g. `@dynamic=120`). Supported in GenericRandomErrorPlugin (v2.2.0+). -- When simulating APIs and their responses, consider using the LatencyPlugin to make the API responses feel more realistic. -- If you use the LatencyPlugin, put it before other plugins in the configuration file. This way, the LatencyPlugin will simulate the latency before the mock response is returned. +- When simulating APIs and their responses, consider using the LatencyPlugin to make the API responses feel more realistic. See the Plugins section for the correct plugin ordering. ## File paths @@ -47,10 +48,9 @@ ## Hot reload -- Dev Proxy supports hot reload of configuration files (v2.1.0+). When you modify the configuration file while Dev Proxy is running, it automatically detects the changes and restarts with the new configuration. -- Hot reload works for the main configuration file (devproxyrc.json/devproxyrc.jsonc) and plugin-specific configuration files (mock files, CRUD API data files, etc.). +- Dev Proxy supports hot reload of configuration files (v2.1.0+). When you modify a configuration file while Dev Proxy is running, it automatically detects the changes and restarts with the new configuration. +- Hot reload works for all configuration file types: the main configuration file (JSON, JSONC, or YAML) and plugin-specific configuration files (mock files, CRUD API data files, etc.). - You don't need to manually restart Dev Proxy after making configuration changes - just save the file and the changes take effect automatically. -- Hot reload helps you iterate faster when developing and testing different proxy configurations. - To disable hot reload (e.g. in CI/CD or automated environments), use the `--no-watch` flag (v2.2.0+). ## Detached mode @@ -61,8 +61,8 @@ - Combine random ports with `asSystemProxy` set to `false` in the configuration file (or `--as-system-proxy false` on the command line) to prevent Dev Proxy from modifying system proxy settings. This way, each instance runs in isolation and only intercepts requests from applications explicitly configured to use its address and port. - When `asSystemProxy` is `false`, multiple Dev Proxy instances can run in parallel on the same machine (v2.3.0+). Each instance should use its own random port and configuration file. - When using random ports, use `devproxy status` to find the actual assigned port, API URL, PID, and other details of the running instance. -- In detached mode, the proxy URL is printed in the startup output (v2.3.0+). Parse this from the JSON output when using `--output json`. +- The proxy URL is printed in the startup output (v2.3.0+). When using `--output json`, parse the proxy URL from the JSON output to configure your application. ## curl -- When asked for `curl` commands, include `-ikx http://127.0.0.1:` so that curl will ignore SSL certificate errors and use Dev Proxy. Use the actual port Dev Proxy is running on (default: 8000), eg. `curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts/1`. \ No newline at end of file +- When asked for `curl` commands, include `-ikx http://127.0.0.1:` to ignore SSL certificate errors and route through Dev Proxy. Replace `` with the actual port Dev Proxy is running on (default: 8000). Example: `curl -ikx http://127.0.0.1:8000 https://jsonplaceholder.typicode.com/posts/1`. \ No newline at end of file From e4edc8486b44938e86dd1a67297e9d2cb4cd982e Mon Sep 17 00:00:00 2001 From: Garry Trinder Date: Mon, 27 Apr 2026 10:10:37 +0100 Subject: [PATCH 4/5] Remove version tags from best practices Assume users are on the latest version. Version tags add noise without providing actionable value for coding agents. --- assets/best-practices.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/assets/best-practices.md b/assets/best-practices.md index 2df3105..26d5d97 100644 --- a/assets/best-practices.md +++ b/assets/best-practices.md @@ -3,8 +3,8 @@ ## Configuration files - Dev Proxy configuration file is named devproxyrc.json or devproxyrc.jsonc (if you want to include comments) -- Dev Proxy also supports YAML configuration files named devproxyrc.yaml or devproxyrc.yml (v2.2.0+). When creating a YAML config, use `devproxy config new --format yaml`. -- To validate a configuration file before starting Dev Proxy, use `devproxy config validate` (v2.2.0+). +- Dev Proxy also supports YAML configuration files named devproxyrc.yaml or devproxyrc.yml. When creating a YAML config, use `devproxy config new --format yaml`. +- To validate a configuration file before starting Dev Proxy, use `devproxy config validate`. - For clarity, store all Dev Proxy files in the .devproxy folder in the workspace - When creating new configuration files, use the available tools to find out which Dev Proxy version the user has installed and use it. Schema version must match the installed Dev Proxy version. - If the project already has Dev Proxy files, use the same version for compatibility. @@ -39,7 +39,7 @@ - When defining mock responses or CrudApiPlugin actions, put entries with the longest (most specific) URLs first. Entries are matched in the order they're defined, so you don't want a generic pattern like /{id} to override a more specific one like /category/{name}. - Mocks with the nth property should be defined first, because they're considered more specific than mocks without that property. - To return dynamic Retry-After header value in mock responses, use `@dynamic` as the header's value -- To return a dynamic Retry-After header value with a specific initial value, use `@dynamic=initialvalue` (e.g. `@dynamic=120`). Supported in GenericRandomErrorPlugin (v2.2.0+). +- To return a dynamic Retry-After header value with a specific initial value, use `@dynamic=initialvalue` (e.g. `@dynamic=120`). Supported in GenericRandomErrorPlugin. - When simulating APIs and their responses, consider using the LatencyPlugin to make the API responses feel more realistic. See the Plugins section for the correct plugin ordering. ## File paths @@ -48,20 +48,20 @@ ## Hot reload -- Dev Proxy supports hot reload of configuration files (v2.1.0+). When you modify a configuration file while Dev Proxy is running, it automatically detects the changes and restarts with the new configuration. +- Dev Proxy supports hot reload of configuration files. When you modify a configuration file while Dev Proxy is running, it automatically detects the changes and restarts with the new configuration. - Hot reload works for all configuration file types: the main configuration file (JSON, JSONC, or YAML) and plugin-specific configuration files (mock files, CRUD API data files, etc.). - You don't need to manually restart Dev Proxy after making configuration changes - just save the file and the changes take effect automatically. -- To disable hot reload (e.g. in CI/CD or automated environments), use the `--no-watch` flag (v2.2.0+). +- To disable hot reload (e.g. in CI/CD or automated environments), use the `--no-watch` flag. ## Detached mode -- Dev Proxy can run in detached (background) mode (v2.2.0+). This is useful for CI/CD pipelines, automated testing, and agent-driven workflows where Dev Proxy needs to run without an interactive terminal. +- Dev Proxy can run in detached (background) mode. This is useful for CI/CD pipelines, automated testing, and agent-driven workflows where Dev Proxy needs to run without an interactive terminal. - When running in detached mode, use `--output json` to get structured, machine-readable output that can be parsed by scripts and agents. - For detached mode and CI/CD scenarios, set `port` to `0` in the configuration file (or use `--port 0` on the command line) to let the OS assign a random available port. This avoids port conflicts when running multiple Dev Proxy instances in parallel. Similarly, use `--api-port 0` for the Dev Proxy API port. - Combine random ports with `asSystemProxy` set to `false` in the configuration file (or `--as-system-proxy false` on the command line) to prevent Dev Proxy from modifying system proxy settings. This way, each instance runs in isolation and only intercepts requests from applications explicitly configured to use its address and port. -- When `asSystemProxy` is `false`, multiple Dev Proxy instances can run in parallel on the same machine (v2.3.0+). Each instance should use its own random port and configuration file. +- When `asSystemProxy` is `false`, multiple Dev Proxy instances can run in parallel on the same machine. Each instance should use its own random port and configuration file. - When using random ports, use `devproxy status` to find the actual assigned port, API URL, PID, and other details of the running instance. -- The proxy URL is printed in the startup output (v2.3.0+). When using `--output json`, parse the proxy URL from the JSON output to configure your application. +- The proxy URL is printed in the startup output. When using `--output json`, parse the proxy URL from the JSON output to configure your application. ## curl From a16a6c0790e7000d8f9be89a4c8199689bd9fd3a Mon Sep 17 00:00:00 2001 From: Garry Trinder Date: Mon, 27 Apr 2026 10:20:48 +0100 Subject: [PATCH 5/5] Reinstate version tags for consistency --- assets/best-practices.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/assets/best-practices.md b/assets/best-practices.md index 26d5d97..2df3105 100644 --- a/assets/best-practices.md +++ b/assets/best-practices.md @@ -3,8 +3,8 @@ ## Configuration files - Dev Proxy configuration file is named devproxyrc.json or devproxyrc.jsonc (if you want to include comments) -- Dev Proxy also supports YAML configuration files named devproxyrc.yaml or devproxyrc.yml. When creating a YAML config, use `devproxy config new --format yaml`. -- To validate a configuration file before starting Dev Proxy, use `devproxy config validate`. +- Dev Proxy also supports YAML configuration files named devproxyrc.yaml or devproxyrc.yml (v2.2.0+). When creating a YAML config, use `devproxy config new --format yaml`. +- To validate a configuration file before starting Dev Proxy, use `devproxy config validate` (v2.2.0+). - For clarity, store all Dev Proxy files in the .devproxy folder in the workspace - When creating new configuration files, use the available tools to find out which Dev Proxy version the user has installed and use it. Schema version must match the installed Dev Proxy version. - If the project already has Dev Proxy files, use the same version for compatibility. @@ -39,7 +39,7 @@ - When defining mock responses or CrudApiPlugin actions, put entries with the longest (most specific) URLs first. Entries are matched in the order they're defined, so you don't want a generic pattern like /{id} to override a more specific one like /category/{name}. - Mocks with the nth property should be defined first, because they're considered more specific than mocks without that property. - To return dynamic Retry-After header value in mock responses, use `@dynamic` as the header's value -- To return a dynamic Retry-After header value with a specific initial value, use `@dynamic=initialvalue` (e.g. `@dynamic=120`). Supported in GenericRandomErrorPlugin. +- To return a dynamic Retry-After header value with a specific initial value, use `@dynamic=initialvalue` (e.g. `@dynamic=120`). Supported in GenericRandomErrorPlugin (v2.2.0+). - When simulating APIs and their responses, consider using the LatencyPlugin to make the API responses feel more realistic. See the Plugins section for the correct plugin ordering. ## File paths @@ -48,20 +48,20 @@ ## Hot reload -- Dev Proxy supports hot reload of configuration files. When you modify a configuration file while Dev Proxy is running, it automatically detects the changes and restarts with the new configuration. +- Dev Proxy supports hot reload of configuration files (v2.1.0+). When you modify a configuration file while Dev Proxy is running, it automatically detects the changes and restarts with the new configuration. - Hot reload works for all configuration file types: the main configuration file (JSON, JSONC, or YAML) and plugin-specific configuration files (mock files, CRUD API data files, etc.). - You don't need to manually restart Dev Proxy after making configuration changes - just save the file and the changes take effect automatically. -- To disable hot reload (e.g. in CI/CD or automated environments), use the `--no-watch` flag. +- To disable hot reload (e.g. in CI/CD or automated environments), use the `--no-watch` flag (v2.2.0+). ## Detached mode -- Dev Proxy can run in detached (background) mode. This is useful for CI/CD pipelines, automated testing, and agent-driven workflows where Dev Proxy needs to run without an interactive terminal. +- Dev Proxy can run in detached (background) mode (v2.2.0+). This is useful for CI/CD pipelines, automated testing, and agent-driven workflows where Dev Proxy needs to run without an interactive terminal. - When running in detached mode, use `--output json` to get structured, machine-readable output that can be parsed by scripts and agents. - For detached mode and CI/CD scenarios, set `port` to `0` in the configuration file (or use `--port 0` on the command line) to let the OS assign a random available port. This avoids port conflicts when running multiple Dev Proxy instances in parallel. Similarly, use `--api-port 0` for the Dev Proxy API port. - Combine random ports with `asSystemProxy` set to `false` in the configuration file (or `--as-system-proxy false` on the command line) to prevent Dev Proxy from modifying system proxy settings. This way, each instance runs in isolation and only intercepts requests from applications explicitly configured to use its address and port. -- When `asSystemProxy` is `false`, multiple Dev Proxy instances can run in parallel on the same machine. Each instance should use its own random port and configuration file. +- When `asSystemProxy` is `false`, multiple Dev Proxy instances can run in parallel on the same machine (v2.3.0+). Each instance should use its own random port and configuration file. - When using random ports, use `devproxy status` to find the actual assigned port, API URL, PID, and other details of the running instance. -- The proxy URL is printed in the startup output. When using `--output json`, parse the proxy URL from the JSON output to configure your application. +- The proxy URL is printed in the startup output (v2.3.0+). When using `--output json`, parse the proxy URL from the JSON output to configure your application. ## curl