Environment variables

Environment variables configure managed setup, process-wide serialization and logging, and the observability dashboard.

For every observability variable the order is: an explicit constructor option wins, then the environment variable, then the built-in default. One variable breaks that rule, and it is called out below.

How observability values are parsed

The parsing is strict. A variable that does not match is treated as unset, or as false, with no warning.

So LAZY_OBS_ENABLED=yes does not enable anything, and LAZY_OBS_ENABLED=TRUE does.

Managed setup

Use an explicit namespace for instances that must share a cache. See setup options.

Serialization

CACHE_COMPRESSION

The variable is read once when the serializer is imported. A later configureCompression call replaces the process default. Explicit levels.L1.codec.compression and levels.L2.codec.compression override it for their layer.

For custom size bands:

CACHE_COMPRESSION='[{"maxBytes":256,"codec":"none"},{"maxBytes":4096,"codec":"lz4"},{"codec":"zstd"}]'

Malformed JSON or an invalid tier array is ignored. Log getCompressionTiers() at startup to inspect the active process default. See serialization configuration for tier validation rules.

The JSON debug switches

CACHE_FORMAT=json and CACHE_DEBUG_SERIALIZATION=true each select uncompressed JSON for writes without an explicit format. These comparisons are case-sensitive. CACHE_FORMAT=JSON and CACHE_DEBUG_SERIALIZATION=1 do not enable JSON.

A layer's explicit format: 'msgpack' overrides these switches. Explicit format: 'json' selects JSON without environment variables. JSON follows JSON value semantics, so Date, Map, and typed arrays do not retain their JavaScript types.

Reads continue to use the stored tag. Changing a write policy does not rewrite existing values, and readers need the codec required by each stored value.

Logging

Two things about this one.

It is read once, when the logging module is first imported. Mutating process.env.NODE_ENV after your application has loaded changes nothing.

It is a default, not a floor. logging.env overrides it, and logging.enabled overrides both. That configuration is process-wide and applied by every cache and every event bus you construct, so the last one constructed wins for the whole process.

Observability

Every dashboard setting has a variable, so you can turn the dashboard on in staging without shipping a code change.

These are resolved in the cache constructor, so they have to be set before you construct the cache. Changing one at runtime does nothing.

The one exception to precedence

LAZY_OBS_NO_SERVER is not overridden by an option. The standalone server is skipped when observability.server === false or the variable is true, so setting LAZY_OBS_NO_SERVER=true disables a server your code asked for.

The reverse does not hold. LAZY_OBS_NO_SERVER=false cannot bring back a server that server: false turned off, because only the value true participates.

Settings with no variable

observability.server.autoStart has no environment equivalent. Neither does observability.enabled at the level of a single cache instance: LAZY_OBS_ENABLED applies to every cache in the process that does not set enabled explicitly.

Precedence in practice

import { LazyLayersCache, RedisStore } from 'lazy-layers-cache'
import { redis } from './redis.js'

export const cache = new LazyLayersCache({
  ttlMs: 5 * 60 * 1000,
  l2: new RedisStore(redis, { prefix: 'app:cache:' }),

  observability: {
    // Left to LAZY_OBS_ENABLED, so staging can turn this on without a deploy.
    // Pinned in code, so no environment can move the dashboard somewhere
    // your reverse proxy is not expecting.
    route: '/internal/cache',
    // Credentials stay in the environment. Never in the repository.
  },
})

Anything you set in code is fixed for every environment. Anything you leave out is yours to move per environment. Credentials belong in the second group.

Variables the library does not read

These appear throughout the documentation because they are the conventional place to keep connection details. Nothing in the library looks them up. You pass them yourself.

INSTANCE_ID is the one worth wiring carefully, because three separate things break when two servers share a value.

As source, it is how a server recognises its own broadcasts. Two servers sharing it means each ignores the other's invalidations, so deletes silently stop propagating between them.

As a RabbitMQ queueName in durable mode, it names the queue that server consumes from. Two servers sharing it means they consume from one queue and each invalidation reaches only one of them.

As a NATS JetStream durableName, the same thing happens through a shared durable consumer: the stream is split between the servers rather than delivered to both.

Under Node clustering, every worker is a separate server for all three purposes. Derive the value from the worker id, not just the host.

Where to next