# @mimik/configuration

> Common configuration for mimik services

Latest version **6.3.0** (published 2026-09-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mimik/configuration
pnpm add @mimik/configuration
yarn add @mimik/configuration
bun add @mimik/configuration
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 6.3.0 |
| Published | 2026-09-18 |
| First published | 2018-06-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 3 |
| Unpacked size | 65.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | mimik technology inc |
| Maintainers | mimik-npm-editor, hofachiang, miburger, mimikopensource, sasan.raisdana |
| Keywords | mimik, microservice, config |

## Links

- npm: https://www.npmjs.com/package/@mimik/configuration
- Repository: https://bitbucket.org/mimiktech/configuration
- Homepage: https://bitbucket.org/mimiktech/configuration#readme
- Issues: https://bitbucket.org/mimiktech/configuration/issues
- npm.io page: https://npm.io/package/@mimik/configuration

## Dependencies (3)

- [@mimik/user-filters](https://npm.io/package/@mimik/user-filters.md) ^2.1.1
- [@mimik/request-helper](https://npm.io/package/@mimik/request-helper.md) ^2.0.8
- [@mimik/sumologic-winston-logger](https://npm.io/package/@mimik/sumologic-winston-logger.md) ^2.3.1

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 6.3.0 (latest) — 2026-09-18
- 6.2.1 — 2026-07-08
- 6.1.0 — 2026-06-05
- 6.0.11 — 2026-03-22
- 6.0.10 — 2026-03-18
- 6.0.9 — 2026-02-28
- 6.0.8 — 2026-02-25
- 6.0.7 — 2026-02-25
- 6.0.6 — 2025-08-13
- 6.0.5 — 2025-08-13
- 6.0.4 — 2025-07-18
- 6.0.3 — 2025-07-18
- 6.0.2 — 2025-03-25
- 6.0.1 — 2025-03-25
- 6.0.0 — 2025-03-12
- … 42 more at https://npm.io/package/@mimik/configuration/versions

## README

<a name="module_configuration"></a>

## configuration
**Example**  
```js
import config from '@mimik/configuration';
```
**Example**  
```js
import { setConfig, isProd } from '@mimik/configuration';
```

* [configuration](#module_configuration)
    * [~isProd()](#module_configuration..isProd) ⇒ <code>boolean</code>
    * [~setConfig(pack, [options])](#module_configuration..setConfig) ⇒ <code>object</code>

<a name="module_configuration..isProd"></a>

### configuration~isProd() ⇒ <code>boolean</code>
Indicates if the environment is prod.

**Kind**: inner method of [<code>configuration</code>](#module_configuration)  
**Returns**: <code>boolean</code> - `true` if the environment is `prod` or `production`.

The following environment variables are used

| Env variable name | Description | Value | Comments |
| ----------------- | ----------- | ----- | -------- |
| NODE_ENV | environment of the microservice |  |  |  
**Category**: sync  
<a name="module_configuration..setConfig"></a>

### configuration~setConfig(pack, [options]) ⇒ <code>object</code>
Set the configuration of the micro-service.

The following environment variables are being setup:

| Env variable name | Description | Value | Comments |
| ----------------- | ----------- | ----- | -------- |
| SERVER_VERSION | version of the software for the micro-service | package.version | serverSettings.version
| SERVER_NAME | name of the micro-service | package.name | serverSettings.name
| SERVER_PACKAGE_TYPE | type of the micro-service package | package.mimik.type | serverSettings.packageType
| SERVER_TYPE | type of the micro-service instance | SERVER_PACKAGE_TYPE when not set | serverSettings.type
| SWAGGER_FILE_VERSION | version of the swagger file for the API | package.swaggerFile.version | serverSettings.swaggerFile.version
| SWAGGER_FILE_ACCOUNT | account associated with the API | package.swaggerFile.account | serverSettings.swaggerFile.account
| SWAGGER_FILE_NAME | name of the API | package.swaggerFile.name | serverSettings.swaggerFile.name
| SWAGGER_FILE_PROVIDER | provider of the API file | package.swaggerFile.provider | serverSettings.swaggerFile.provider, if not present the default is `bitbucket`
| SERVER_LOCAL_IPV4 | IP address of the micro-service | first non-internal IPv4 interface, or 127.0.0.1 | serverSettings.ip.local
| CONSOLE_LEVEL | log level for console output | debug | logInfo.level.console
| LOG_LEVEL | log level for log output | debug | logInfo.level.log
| AWS_LOCAL_PROPERTIES | internal ip address to access aws instance properties | 169.254.169.254
| MST_SET | to setup configuration without mST and oauth token setup | on | on/off

The following environment variables are being used for the configuration:

| Env variable name | Description | Default | Config property | Comments |
| ----------------- | ----------- | ------- | ----------------| -------- |
| NODE_ENV | running environment | local | nodeEnvironment |
| LOCATION_PROVIDER | location provider URL to use for ip location or `noPublic` or `environment` | noPublic | locationProvider.url or locationProvider | `see public-helper`
| LOCATION_PROVIDER_KEY | location provider key to use to access the location provider | null | locationProvider.key | see `public-helper`
| CLOUD_PROVIDER | cloud provider running the service | noCloud | cloudProvider | see `public-helper`
| SERVER_ID | service id | crypto.randomUUID() | serverSettings.id |
| CUSTOMER_CODE | customer code associated with the service instance | '' | serverSettings.customerCode | empty string
| SWAGGER_FILE_DIRECTORY | directory where the api definition is located | ../api | serverSettings.api | [1]
| BITBUCKET_USERNAME | username to access bitbucket read access on the swagger repos | ' ' | serverSettings.apiBasicAuth.username
| BITBUCKET_PASSWORD | password to access bitbucket read access on the swagger repos | ' ' | serverSettings.apiBasicAuth.password
| SWAGGERHUB_API_KEY | apiKey to access swaggerhub | | serverSettings.apiApiKey
| SERVER_SECURITY_SET | switch to enable or disable the token interpretation | on | serverSettings.securitySet | only active if environment is `local`
| INTERCEPT_ERROR | switch to use or not the errorIntercept option | on | serverSettings.interceptError | must be set to off for mID
| SERVER_PORT | port of the server |  | serverSettings.port |
| SERVER_PUBLIC_PROTOCOL | protocol used to define the domain address of the service | http: | serverSettings.public.protocol |
| SERVER_PUBLIC_DOMAIN_NAME | domain name used to define the domain address of the service | null | serverSettings.public.domainName |
| ADMIN_EXTERNAL_ID | external id of the admin role to be checked in the token | admin | security.admin.externalId |
| OAUTH_CLIENT_ID | security id of the service |  | security.server.id | [2]
| OAUTH_CLIENT_SECRET | secret of the service |  | security.server.secret | [2]
| OAUTH_CLIENT_ACCESS_KEY | key for token signature |  | security.server.accessKey | [2]
| OAUTH_CLIENT_AUDIENCE | url representing the server to mST |  | security.server.audience | [2]
| OAUTH_ISSUER | token url of mST |  | security.server.issuer | [2]
| OAUTH_GENERIC_KEY | key for token signature provided when a generic for this service type is defined | noGeneric | security.generic.key | [2]
| OAUTH_GENERIC_PREVIOUS_KEY | key for the token signature before change the public key | | security.generic.previousKey | [2]
| OAUTH_GENERIC_AUDIENCE | url representing the generic of the service type to mST | noGeneric | security.generic.audience | [2]
| API_KEYS | list of API Keys which are tested against in case of APIKey security | [] |
| LOG_MODE | collector to be used to log events | sumologic | logInfo.mode | can be `sumologic`, `awsS3`, `all`, `awsKinesis`, `none`
| NO_STACK | disable the inclusion of the stack in all logs | yes | logInfo.noStack
| FILTER_FILE | path for the filter file definition | not set | logInfo.filterFile |
| USER_DEFINITIONS_FILE | path for the custom user definitions | not set | userDefinitions.file |
| EXIT_DELAY | delay to allow the log transports to flush | 2000 | logInfo.exitDelay | in milliseconds
| CLUSTER_MANAGEMENT | switch to enable cluster communication | off | cluster.management | can be `on` or `off`
| REQUEST_TIMEOUT | timeout for intra cluster http request | 10000 | cluster.timeout | in milliseconds
| CACHE_SET | switch to enable use of cache | off | cache.set | can be `on`, `off`
| TOPIC_SET | switch to enable use of event topic | off | topic.set | can be `on`, `off`, `mock`
| SET_SNS_TOPIC_FIFO | set to yes if fifo topic | no | topic.isFifoTopic | can be `yes`, `no`
| SET_SNS_CONTENT_DEDUPLICATION | set to yes, to use content based deduplication | no | contentBasedDeduplication | when fifo topic is used and set to no, MessageDeduplicationId must be provided in message.
| ENCRYPTION_SET | switch to enable use of mongodb encryption | off | encryption.set | can be `on`, or `off`
| MIT_URL | url for reaching mIT |  | dependencies.mIT.url |
| MIT_AUDIENCE | audience of mIT |  | dependencies.mIT.audience | [2]
| REGISTRATION_SET | switch to enable use of registration | on | registration.set | can be `on` or `off`
| REGISTRATION_RETRY | retry time for registering to mIT | 3000 | registration.retry | in milliseconds
| REGISTRATION_AFTER_POSTOPS_SET | switch to set the registration after the execution of the postOps | off | registration.afterPostOpsSet | can be `on` or `off`
| `${configuration.serverSettings.type}_URL`.toUpperCase() | cluster information | self | dependencies.`(SERVER_TYPE)`.url | should not be used
| `${configuration.serverSettings.type}_AUDIENCE`.toUpperCase() | cluster information |  | dependencies.`(SERVER_TYPE)`.audience | [2], but should not be used

[1]: `/(SWAGGER_FILE_ACCOUNT)_(SWAGGER_FILE_NAME)_(SWAGGER_FILE_VERSION)_swagger.json` is added to the `serverSettings.api` property

[2]: defined when registering to mST

When MST_SET is `off`, registration and cluster should not be enabled, so configuration.cluster.management and configuration.registration.set will be set to `off`

When an instance type is given, so that two services built on the same packageType can be differentiated, the matching
`(instance type)_AUDIENCE`.toUpperCase() environment variable must be provided as well while MST_SET is `on`, otherwise the
configuration check fails with `Errors in configuration` on the `dependencies.(instance type).audience` property.

When `sumologic` or `all` is used for `LOG_MODE` the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| SUMO_LOGIC_ENDPOINT | endpoint of the sumologic collector used for logs |
| SUMO_LOGIC_COLLECTOR_CODE | id of the collector in sumologic |

When `awsS3` or `all` is used for `LOG_MODE` the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| S3_AWS_ACCESS_KEY_ID | access key id for AWS S3 |
| S3_AWS_SECRET_ACCESS_KEY | secret access key for AWS S3 |
| S3_AWS_BUCKET_NAME | name of the bucket used in S3 |
| S3_AWS_REGION | region where the bucket is |
| S3_AWS_TIMEOUT | maximum time a log can stay before being sent to S3 | 5 | in minutes
| S3_AWS_MAX_SIZE | maximum size of the block of logs before being sent to S3 | 5 | in MB
| S3_AWS_MAX_EVENTS | maximum number of logs to be in the block before being sent to S3 | 1000

When `awsKinesis` is used for `LOG_MODE` the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| KINESIS_AWS_ACCESS_KEY_ID | access key id for AWS Kinesis |
| KINESIS_AWS_SECRET_ACCESS_KEY | secret access key for AWS Kinesis |
| KINESIS_AWS_REGION | region where the stream is |
| KINESIS_AWS_STREAM_NAME_INFO | stream name for the `info` level logs |
| KINESIS_AWS_STREAM_NAME_ERROR | stream name for the `error` level logs |
| KINESIS_AWS_STREAM_NAME_OTHER | stream name for any other level |
| KINESIS_AWS_TIMEOUT | maximum time a log can stay before being sent to Kinesis | 5 | in minutes
| KINESIS_AWS_MAX_SIZE | maximum size of the block of logs before being sent to Kinesis | 5 | in MB
| KINESIS_AWS_MAX_EVENTS | maximum number of logs to be in the block before being sent to Kinesis | 1000

`awsKinesis` is not part of `all`, which covers `sumologic` and `awsS3` only.

When `on` is used for `TOPIC_SET` the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| SNS_AWS_ACCESS_KEY_ID | access key id for AWS SNS |  |
| SNS_AWS_SECRET_ACCESS_KEY | secret access key for AWS SNS |  |
| SNS_AWS_REGION | region where the topic is | ----noRegion---- |

When a database is involved

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| DATABASE_CONNECTION_TIMEOUT | the time to connect to the database before error is generated | 30 | in seconds
| DATABASE_VALIDATION_CHECK | the delay before checking for connection | 1000 | in ms
| DATABASE_RECONNECTION_OFFSET | offset for the time to reconnect to the database before error is generated | 5 | in seconds

When `mongodb` is used the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| DATABASE_NAME | name of the database to store the information |  |
| DATABASE_IP | ip address of the database | localhost |
| DATABASE_USER | user to access the database | null | if missing no user/password will be used
| DATABASE_PASSWORD | password to access the database | null | if missing no user/password will be used
| MONGO_USE_SRV | to use srv connection url set to `yes` | `no` |
| MONGO_AUTH_DATABASE | the auth database where users exist | |
| MONGO_MIN_POOL_SIZE | the minimum number of connections in the connection pool | 0 |
| MONGO_MAX_POOL_SIZE | the maximum number of connections in the connection pool | 10 |
| MONGO_MAX_IDLE_TIME | the maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed | 30000 | in milliseconds
| MONGO_RETRY_WRITES | defines if the transaction should be tried again to write set to true or false | |
| MONGO_WRITE_CONCERN | accepts a number or `majority` | |
| MONGO_SSL | uses ssl connection if `yes` | `no` |
| MONGO_SSL_VALIDATE | validates mongod server certificate against ca if set to `yes` | `yes` | `yes` if MONGO_SSL is also `yes`
| MONGO_SSL_ALLOW_INVALID_HOSTNAMES | set to yes to allow invalid hostnames | |
| MONGO_REPLICAT_SET | specifies the name of the replica set, if the mongod is a member of a replica set |  | not mandatory. The `REPLICAT`/`replicat` spelling is a legacy published contract (a misspelling of "replica") kept for backward compatibility.
| MONGO_WAIT_QUEUE_TIMEOUT | the maximum time in milliseconds that a thread can wait for a connection to become available |  | not mandatory
| MONGO_SOCKET_TIMEOUT | The time in milliseconds to attempt a send or receive on a socket before the attempt times out | 20000 | in milliseconds
| MONGO_FAMILY | IP address family | 4 | 4 -> IPV4, 6 -> IPV6
| MONGO_SERVER_SELECTION_TIMEOUT | the MongoDB driver will try to find a server to send any given operation to, and keep retrying for serverSelectionTimeoutMS milliseconds | 30000 | in milliseconds
| MONGO_HEARTBEAT_FREQUENCY | the MongoDB driver sends a heartbeat every heartbeatFrequencyMS to check on the status of the connection | 10000 | in milliseconds

When `on` is used for `ENCRYPTION_SET` the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| ENCRYPTION_DATABASE | database name where data encryption key vault exists |  | mandatory when ENCRYPTION_SET is `on`
| KEY_VAULT_TABLE | collection name which has data encryption keys |  | mandatory when ENCRYPTION_SET is `on`
| KMS_PROVIDER | Key Management service provider for master key | local |
| MASTER_KEY_AWS_REGION | if KMS is aws region where master key exists | ----noRegion---- |
| MASTER_KEY_ARN | if KMS is aws ARN of master key | |
| ENCRYPTION_ACCESS_KEY_ID | if KMS is aws, accessKeyId to connect KMS | |
| ENCRYPTION_SECRET_ACCESS_KEY | if KMS is aws, secretAccessKey to connect KMS | |
| LOCAL_MASTER_KEY | if KMS is local, masterkey to encrypt data keys | |
| ENCRYPTION_MONGOCRYPTD_URI | URI of a remote mongocryptd (e.g. Atlas-hosted). Takes precedence over ENCRYPTION_CRYPT_SHARED_LIB_PATH when both are set | | optional |
| ENCRYPTION_CRYPT_SHARED_LIB_PATH | Absolute path to the crypt_shared shared library (.dylib/.so/.dll). Avoids needing mongocryptd. Download from https://www.mongodb.com/try/download/enterprise | | optional |

When `dynamodb` is used the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| DYNAMODB_AWS_ACCESS_KEY_ID | access key id for AWS dynamodb |  |
| DYNAMODB_AWS_SECRET_ACCESS_KEY | secret access key for AWS dynamodb |  |
| DYNAMODB_AWS_REGION | region where dynamodb is | ----noRegion---- |
| DYNAMODB_LOCAL_URL | URL to access the locally deployed dynamodb | http://localhost:8000 |
| DYNAMO_THROUGHPUT_READ | throughput read for dynamodb index | 1 |
| DYNAMO_THROUGHPUT_WRITE | throughput write for dynamodb index | 1 |
| DYNAMO_SCHEMA_THROUGHPUT_READ | throughput read for dynamodb schema | 1 |
| DYNAMO_SCHEMA_THROUGHPUT_WRITE | throughput write for dynamodb schema | 1 |
| DYNAMO_SCHEMA_THROUGHPUT | throughput for dynamodb schema |

`DYNAMO_SCHEMA_THROUGHPUT` takes precedence over `DYNAMO_SCHEMA_THROUGHPUT_READ` and `DYNAMO_SCHEMA_THROUGHPUT_WRITE`. If DYNAMO_SCHEMA_THROUGHPUT is set to `ON_DEMAND` then index throughput won't apply, and if DYNAMO_SCHEMA_THROUGHPUT is not set to a number the value will be 1.

When `redis` is used the following environment variables are used for the configuration:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| CACHE_IP | domain of the redis server to use with port, a comma separated list if using cluster | localhost:6379 |
| CACHE_USER | redis user if the redis service is auth protected | null |
| CACHE_PASSWORD | redis password for the user if the redis service is auth protected | null |
| CACHE_CLUSTER_SET | set on, when using redis in a cluster. | off |
| CACHE_CLUSTER_USE_REPLICAS | When set on, distribute load by executing readonly commands (such as GET) across all cluster nodes. When false, only use master nodes | off |
| CACHE_CLUSTER_MINIMIZE_CONNECTION | When set on, .connect() will only discover the cluster topology, without actually connecting to all the nodes. Useful for short-term or Pub/Sub-only connections. | off |
| CACHE_CONNECTION_TIMEOUT | time the server will wait at start to connect to the cache | 30 | in seconds
| CACHE_VALIDATION_CHECK | the delay before checking for connection | 1000 | in ms
| CACHE_RECONNECTION_OFFSET | offset for the time to reconnect to the database before error is generated | 5 | in seconds
| CACHE_REQUEST_TTL | request time to live in cache | 10 | in seconds
| CACHE_API_ID_TTL | API request time to live for main resource | 20 | in seconds
| CACHE_API_OPTION_TTL | API request time to live for option | 5 | in seconds
| REDIS_RECONNECT_TRIES | number of tries to reestablish a connection | 100 |
| REDIS_RECONNECT_INTERVAL | time to wait before retry | 500 | in milliseconds
| REDIS_REQUEST_MAX_MEMORY | maximum memory size of the request cache | 10mb | in megabytes
| REDIS_REQUEST_MAX_MEMORY_POLICY | eviction policy of the request cache | allkeys-lru |
| REDIS_SOCKET_KEEPALIVE | keep long-running connections alive | 5000 | in milliseconds
| REDIS_DISABLE_OFFLINE_QUEUE | queuing event when not connected | no |

**Kind**: inner method of [<code>configuration</code>](#module_configuration)  
**Returns**: <code>object</code> - The configuration.  
**Category**: sync  
**Throws**:

- Will throw an error if `pack.mimik.type` or any mandatory `pack.swaggerFile` field is missing, if the `swaggerFile`
provider, the database type or the cache type is not supported, or if a mandatory configuration value is missing.

**Requires**: <code>module:@mimik/sumologic-winston-logger</code>  

| Param | Type | Description |
| --- | --- | --- |
| pack | <code>object</code> | `Package.json` object to use for the configuration. `mimik.type` and the `swaggerFile` `version`, `account` and `name` fields are mandatory; `swaggerFile.provider` is optional and defaults to `bitbucket`. |
| [options] | <code>object</code> | Options to add to the config. Defaults to an empty object. |
| [options.database] | <code>object</code> | Database options. Requires `type` (`mongodb`, `dynamodb` or `level`). For `mongodb`/`dynamodb` also `table`; for `level` `dir` and `persist`. |
| [options.cache] | <code>object</code> | Cache options. Requires `type` (`redis`). Only applied when `CACHE_SET` is `on`. |
| [options.topic] | <code>object</code> | Topic options. Requires `name`. Only applied when `TOPIC_SET` is `on`. |
| [options.encryption] | <code>object</code> | Encryption options (`keys`). Only applied when `ENCRYPTION_SET` is `on`, which is the only switch enabling encryption. |
| [options.userDefinitions] | <code>object</code> | User definitions options (`file`). |
| [options.dependencies] | <code>object</code> | Additional service dependencies keyed by service type (`url`, `audience`, `apiKey`). |
| [options.custom] | <code>object</code> | Custom properties merged at the top level of the configuration. |
| [options.security] | <code>object</code> | Security sections merged into `configuration.security`. |

---
_Source: https://npm.io/package/@mimik/configuration · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._