diff --git a/codeSnippets/snippets/_misc_client/InstallOrReplacePlugin.kt b/codeSnippets/snippets/_misc_client/InstallOrReplacePlugin.kt
new file mode 100644
index 000000000..2729b4192
--- /dev/null
+++ b/codeSnippets/snippets/_misc_client/InstallOrReplacePlugin.kt
@@ -0,0 +1,8 @@
+import io.ktor.client.*
+import io.ktor.client.engine.cio.*
+
+val client = HttpClient(CIO) {
+ installOrReplace(ContentNegotiation) {
+ // ...
+ }
+}
\ No newline at end of file
diff --git a/topics/client-default-request.md b/topics/client-default-request.md
index 56a067a85..fb6e7f2e7 100644
--- a/topics/client-default-request.md
+++ b/topics/client-default-request.md
@@ -34,7 +34,7 @@ val client = HttpClient(CIO) {
}
```
-Or call the `defaultRequest` function and [configure](#configure) required request parameters:
+Or call the `defaultRequest()` function and [configure](#configure) required request parameters:
```kotlin
import io.ktor.client.*
@@ -48,6 +48,30 @@ val client = HttpClient(CIO) {
}
```
+### Replace existing configuration {id="default_request_replace"}
+
+If `DefaultRequest` has already been installed, you can replace its existing configuration in one of the following ways:
+
+- Use the `replace` parameter of `defaultRequest()`:
+
+```kotlin
+val client = HttpClient(CIO) {
+ defaultRequest(replace = true) {
+ // this: DefaultRequestBuilder
+ }
+}
+```
+
+- Use the generic `installOrReplace()` function:
+
+```kotlin
+val client = HttpClient(CIO) {
+ installOrReplace(DefaultRequest) {
+ // this: DefaultRequestBuilder
+ }
+}
+```
+
## Configure DefaultRequest {id="configure"}
### Base URL {id="url"}
diff --git a/topics/client-plugins.md b/topics/client-plugins.md
index 26b0a5772..ae467765a 100644
--- a/topics/client-plugins.md
+++ b/topics/client-plugins.md
@@ -1,35 +1,60 @@
[//]: # (title: Client plugins)
-Get acquainted with plugins that provide common functionality, for example, logging, serialization, authorization, etc.
+Learn how to use client plugins to add common functionality, such as logging, serialization, and authorization.
-Many applications require common functionality that is out of scope of the application logic. This could be things like [logging](client-logging.md), [serialization](client-serialization.md), or [authorization](client-auth.md). All of these are provided in Ktor by means of what we call **Plugins**.
-
+Many applications require common functionality that is not part of the core application logic, such as
+[logging](client-logging.md), [serialization](client-serialization.md), or [authorization](client-auth.md). In Ktor,
+this functionality is provided by client _plugins_.
## Add plugin dependency {id="plugin-dependency"}
-A plugin might require a separate [dependency](client-dependencies.md). For example, the [Logging](client-logging.md) plugin requires adding the `ktor-client-logging` artifact in the build script:
+
+Some plugins require an additional [dependency](client-dependencies.md). For example, to use the [Logging](client-logging.md) plugin, you need to add the
+`ktor-client-logging` artifact in your build script:
-You can learn which dependencies you need from a topic for a required plugin.
-
+Each plugin’s documentation specifies any required dependencies.
## Install a plugin {id="install"}
-To install a plugin, you need to pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client). For example, installing the `Logging` plugin looks as follows:
+
+To install a plugin, pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client).
+
+For example, installing the `Logging` plugin looks as follows:
```kotlin
```
-{src="snippets/_misc_client/InstallLoggingPlugin.kt"}
+{src="snippets/_misc_client/InstallLoggingPlugin.kt" include-lines="1-7"}
+
+### Install or replace a plugin {id="install_or_replace"}
+In some cases, a plugin may already be installed — for example, by shared client configuration code. In such cases, you
+can replace its configuration using `installOrReplace()`:
+
+```kotlin
+```
+{src="snippets/_misc_client/InstallOrReplacePlugin.kt" include-symbol="client"}
+
+This function installs the plugin if it is not present or replaces its existing configuration if it has already been
+installed.
## Configure a plugin {id="configure_plugin"}
-You can configure a plugin inside the `install` block. For example, for the [Logging](client-logging.md) plugin, you can specify the logger, logging level, and condition for filtering log messages:
+
+Most plugins expose configuration options that can be set inside the `install` block.
+
+For example, the [Logging](client-logging.md) plugin allows you to specify the logger, logging level, and condition for filtering log
+messages:
+
```kotlin
```
-{src="snippets/client-logging/src/main/kotlin/com/example/Application.kt" include-lines="12-20"}
+{src="snippets/client-logging/src/main/kotlin/com/example/Application.kt" include-symbol="client"}
## Create a custom plugin {id="custom"}
-To learn how to create custom plugins, refer to [](client-custom-plugins.md).
+
+If the existing plugins do not meet your needs, you can create your own custom client plugins. Custom plugins allow you
+to intercept requests and responses and implement reusable behavior.
+
+To learn more, see [](client-custom-plugins.md).
diff --git a/topics/whats-new-340.md b/topics/whats-new-340.md
index 4658cf82b..be5db29b4 100644
--- a/topics/whats-new-340.md
+++ b/topics/whats-new-340.md
@@ -288,3 +288,39 @@ val client = HttpClient(Apache5) {
The new `configureConnectionManager {}` function keeps Ktor in control while allowing you to adjust parameters such as
maximum connections per route (`maxConnPerRoute`) and total maximum connections (`maxConnTotal`).
+
+
+### Plugin and default request configuration replacement
+
+Ktor client configuration now provides more control over replacing existing settings at runtime.
+
+#### Replace plugin configuration
+
+The new `installOrReplace()` function installs a client plugin or replaces its existing configuration if the plugin is
+already installed. This is useful when you need to reconfigure a plugin without manually removing it first.
+
+```kotlin
+val client = HttpClient {
+ installOrReplace(ContentNegotiation) {
+ json()
+ }
+}
+```
+
+In the above example, if `ContentNegotiation` is already installed, its configuration is replaced with the new one
+provided in the block.
+
+#### Replace default request configuration
+
+The `defaultRequest()` function now accepts an optional `replace` parameter (default is false). When set to `true`,
+the new configuration replaces any previously defined default request settings instead of being merged with them.
+
+```kotlin
+val client = HttpClient {
+ defaultRequest(replace = true) {
+ // Configure default request parameters
+ }
+}
+```
+
+This allows you to explicitly override earlier default request configuration when composing or reusing client setups.
\ No newline at end of file