diff --git a/.changeset/silent-shirts-knock.md b/.changeset/silent-shirts-knock.md
new file mode 100644
index 000000000..b80621c7c
--- /dev/null
+++ b/.changeset/silent-shirts-knock.md
@@ -0,0 +1,5 @@
+---
+'@verdaccio/config': patch
+---
+
+fix config builder erroring when passed partial config
diff --git a/packages/config/README.md b/packages/config/README.md
index b1838c6e3..c61c4ae18 100644
--- a/packages/config/README.md
+++ b/packages/config/README.md
@@ -1,5 +1,74 @@
 # @verdaccio/config
 
+## Overview
+
+The `@verdaccio/config` package provides a powerful configuration builder constructor for programmatically creating configuration objects for Verdaccio, a lightweight private npm proxy registry. With this package, users can easily manage various configuration aspects such as package access, uplinks, security settings, authentication, logging, and storage options.
+
+## Installation
+
+You can install via npm:
+
+```bash
+npm install @verdaccio/config
+```
+
+## Usage
+
+To start using `@verdaccio/config`, import the `ConfigBuilder` class and begin constructing your configuration object:
+
+## `ConfigBuilder` constructor
+
+The `ConfigBuilder` class is a helper configuration builder constructor used to programmatically create configuration objects for testing or other purposes.
+
+```typescript
+
+import { ConfigBuilder } from '@verdaccio/config';
+
+// Create a new configuration builder instance
+const config = ConfigBuilder.build({ security: { api: { legacy: false } } });
+
+// Add package access configuration
+configBuilder.addPackageAccess('@scope/*', { access: 'read', publish: 'write' });
+
+// Add an uplink configuration
+configBuilder.addUplink('npmjs', { url: 'https://registry.npmjs.org/' });
+
+// Add security configuration
+configBuilder.addSecurity({ allow_offline: true });
+
+// Get the configuration object
+const config = configBuilder.getConfig();
+
+// Get the configuration yaml text
+const config = configBuilder.getAsYaml();
+```
+
+### Methods
+
+- `addPackageAccess(pattern: string, pkgAccess: PackageAccessYaml)`: Adds package access configuration.
+- `addUplink(id: string, uplink: UpLinkConf)`: Adds an uplink configuration.
+- `addSecurity(security: Partial<Security>)`: Adds security configuration.
+- `addAuth(auth: Partial<AuthConf>)`: Adds authentication configuration.
+- `addLogger(log: LoggerConfItem)`: Adds logger configuration.
+- `addStorage(storage: string | object)`: Adds storage configuration.
+- `getConfig(): ConfigYaml`: Retrieves the configuration object.
+- `getAsYaml(): string`: Retrieves the configuration object as YAML format.
+
+## `getDefaultConfig`
+
+This method is available in the package's index and retrieves the default configuration object.
+
+```typescript
+import { getDefaultConfig } from '@verdaccio/config';
+
+const defaultConfig = getDefaultConfig();
+```
+
+## Other Methods
+
+- `fromJStoYAML(config: ConfigYaml): string`: Converts a JavaScript configuration object to YAML format.
+- `parseConfigFile(filePath: string): ConfigYaml`: Parses a configuration file from the specified path and returns the configuration object.
+
 ### License
 
 Verdaccio is [MIT licensed](https://github.com/verdaccio/verdaccio/blob/master/LICENSE)
diff --git a/packages/config/src/builder.ts b/packages/config/src/builder.ts
index d7db0caf5..fed673f64 100644
--- a/packages/config/src/builder.ts
+++ b/packages/config/src/builder.ts
@@ -19,8 +19,7 @@ export default class ConfigBuilder {
   private config: ConfigYaml;
 
   public constructor(config?: Partial<ConfigYaml>) {
-    // @ts-ignore
-    this.config = config ?? { uplinks: {}, packages: {}, security: {} };
+    this.config = merge(config, { uplinks: {}, packages: {}, security: {} });
   }
 
   public static build(config?: Partial<ConfigYaml>): ConfigBuilder {
diff --git a/packages/config/test/builder.spec.ts b/packages/config/test/builder.spec.ts
index 85d44d83c..b0c17094f 100644
--- a/packages/config/test/builder.spec.ts
+++ b/packages/config/test/builder.spec.ts
@@ -67,5 +67,58 @@ describe('Config builder', () => {
       .addStorage('/tmp/verdaccio')
       .addSecurity({ api: { legacy: true } });
     expect(config.getAsYaml()).toMatchSnapshot();
+
+    expect(config.getConfig()).toEqual({
+      uplinks: {
+        upstream: {
+          url: 'https://registry.verdaccio.org',
+        },
+        upstream2: {
+          url: 'https://registry.verdaccio.org',
+        },
+      },
+      packages: {
+        'upstream/*': {
+          access: 'public',
+          publish: 'foo, bar',
+          unpublish: 'foo, bar',
+          proxy: 'some',
+        },
+      },
+      security: {
+        api: {
+          legacy: true,
+        },
+      },
+      log: {
+        level: 'info',
+        type: 'stdout',
+        format: 'json',
+      },
+      storage: '/tmp/verdaccio',
+    });
+  });
+
+  test('should merge configurations', () => {
+    // @ts-expect-error
+    const config = ConfigBuilder.build({ security: { api: { legacy: false } } });
+    config.addSecurity({ web: { verify: {}, sign: { algorithm: 'ES256' } } });
+    config.addStorage('/tmp/verdaccio');
+    expect(config.getConfig()).toEqual({
+      security: {
+        api: {
+          legacy: false,
+        },
+        web: {
+          verify: {},
+          sign: {
+            algorithm: 'ES256',
+          },
+        },
+      },
+      uplinks: {},
+      packages: {},
+      storage: '/tmp/verdaccio',
+    });
   });
 });