mongo-uri-builder

library4.0.0jsnpmunverified

mongo-uri-builder is a zero-dependency Node.js module that creates MongoDB connection strings (URIs) from a JavaScript configuration object. Version 4.0.0 is the latest stable release as of 2023. The package is maintained on GitHub with an active issue tracker. It abstracts tedious URI construction, handling hosts, ports, replicas, authentication, and query options. Unlike manual string concatenation, it enforces correct URI encoding and structure. Requires Node.js >=12.

database

npm install mongo-uri-builder

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-URI-BUILDER

mongo-uri-builder

databasejavascriptv4.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import mongoUriBuilder from 'mongo-uri-builder'

✗ const mongoUriBuilder = require('mongo-uri-builder')

ESM import works since v4. CommonJS require also works for backward compatibility.

default

✓ const mongoUriBuilder = require('mongo-uri-builder')

✗ const { mongoUriBuilder } = require('mongo-uri-builder')

The module exports a single function as default. Named destructure will result in undefined.

build

✓ import { build } from 'mongo-uri-builder'

✗ import build from 'mongo-uri-builder'

Named export available since v4 for tree-shaking. Default export still works.

Creates a MongoDB connection string with authentication, host, port, database, and query options.

import mongoUriBuilder from 'mongo-uri-builder'; const uri = mongoUriBuilder({ username: 'admin', password: 'secret', host: 'cluster0.example.mongodb.net', port: 27017, database: 'mydb', options: { retryWrites: true, w: 'majority' } }); console.log(uri); // mongodb://admin:secret@cluster0.example.mongodb.net:27017/mydb?retryWrites=true&w=majority

Debug

Known issues

breakingIn v4, default export is now a named export 'build' alongside default. CJS require still works but ESM users must use default import from the module.

fix

Use import mongoUriBuilder from 'mongo-uri-builder' for default, or import { build } from 'mongo-uri-builder' for named.

affects: >=4.0.0

deprecatedThe 'user' option is deprecated in favor of 'username'. Using 'user' still works but prints a deprecation warning.

fix

Replace 'user' with 'username' in the configuration object.

affects: >=4.0.0

gotchaPort is optional; if omitted, the URI will not include a port. This might not connect to default MongoDB port 27017 automatically.

fix

Always specify port explicitly if connecting to non-default port or to ensure default port is used.

affects: >=1.0.0

gotchaOptions are not URL-encoded automatically for special characters. If an option value contains '&' or '=', the resulting URI may be malformed.

fix

Ensure option values do not contain '&' or '='. For complex values, consider manual encoding.

affects: >=1.0.0

gotchaReplica set order in URI is deterministic based on the array order. Changing array order changes the URI, which may affect connection behavior.

fix

Maintain consistent order in replicas array across environments to avoid connection string differences.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: mongoUriBuilder is not a function

Using named destructure on default export: const { mongoUriBuilder } = require('mongo-uri-builder')

fix

Use const mongoUriBuilder = require('mongo-uri-builder') or import mongoUriBuilder from 'mongo-uri-builder'

Error: The 'user' option is deprecated. Use 'username' instead.

Using deprecated 'user' property in configuration object.

fix

Replace 'user' with 'username' in the configuration.

Warning: No database specified, connection string will not include a database name.

Omitting the 'database' property in the configuration object.

fix

Add 'database' property, even if empty string, or provide a database name.

TypeError: Cannot read properties of undefined (reading 'host')

Passing an object with missing 'host' property for a replica entry.

fix

Ensure each replica object has a 'host' property.

SyntaxError: Invalid URI (options contain invalid character)

Option value contains unescaped '&' or '=' causing malformed query string.

fix

Encode or remove special characters from option values.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/lmammino/mongo-uri-builder ↗

packagemongo-uri-builder ↗

homepagehttps://github.com/lmammino/mongo-uri-builder#readme ↗