# How to Enable or Disable JSAR Resource Caching in the JSAR Runtime

> Easily enable or disable JSAR resource caching in JSAR runtime. Learn how to configure cache settings and TTL with simple environment variables for optimal performance.

- Repository: [M Creative Lab/jsar-runtime](https://github.com/m-creativelab/jsar-runtime)
- Tags: how-to-guide
- Published: 2026-03-06

---

**You can disable JSAR resource caching by setting the environment variables `JSAR_DEBUG_ENABLED=yes` and `JSAR_RESOURCES_CACHING=no`, or enable it by leaving these variables unset to maintain the default 24-hour cache, and optionally override the TTL with `JSAR_RESOURCES_CACHE_EXPIRATION_TIME` measured in milliseconds.**

The m-creativelab/jsar-runtime controls resource caching entirely through environment variables read at startup, allowing developers to toggle network efficiency without modifying source code. Understanding how to enable or disable JSAR resource caching is essential for debugging, CI/CD pipelines, and optimizing application performance.

## Understanding the Environment Variable Controls

Three specific environment variables govern the caching layer:

- **`JSAR_DEBUG_ENABLED`**: Must be set to `yes` to unlock the ability to disable caching. Defaults to `no`.
- **`JSAR_RESOURCES_CACHING`**: When set to `no` (and only when debug mode is active), disables the cache completely. Any other value leaves caching enabled.
- **`JSAR_RESOURCES_CACHE_EXPIRATION_TIME`**: Overrides the default 24-hour TTL (86,400,000 ms) with a custom expiration time in milliseconds.

The runtime evaluates these settings in [`lib/bindings/env.ts`](https://github.com/m-creativelab/jsar-runtime/blob/main/lib/bindings/env.ts) through the `isResourcesCachingDisabled()` and `getResourceCacheExpirationTime()` functions.

## Enabling JSAR Resource Caching

Caching is **enabled by default**. When `JSAR_RESOURCES_CACHING` is unset or set to any value other than `no`, the `CacheStorage` class (defined in [`lib/runtime2/ResourceLoader.ts`](https://github.com/m-creativelab/jsar-runtime/blob/main/lib/runtime2/ResourceLoader.ts)) initializes a cache directory at `${applicationCacheDirectory}/.res_cache` and stores fetched resources with a 24-hour expiration window.

To ensure caching remains active, simply avoid setting the disable flag:

```bash

# Default behavior - caching enabled

unset JSAR_RESOURCES_CACHING
unset JSAR_DEBUG_ENABLED

```

In a Node.js application, you can explicitly ensure caching by removing these variables from `process.env`:

```javascript
// Ensure default caching behavior
delete process.env.JSAR_RESOURCES_CACHING;
delete process.env.JSAR_DEBUG_ENABLED;

```

## Disabling JSAR Resource Caching

To force every resource fetch to bypass the cache and hit the network—critical for debugging or CI validation—you must satisfy two conditions simultaneously:

1. Enable debug mode: `JSAR_DEBUG_ENABLED=yes`
2. Disable caching: `JSAR_RESOURCES_CACHING=no`

When both conditions are met, `isResourcesCachingDisabled()` returns `true`, causing `CacheStorage` to short-circuit all cache operations (`open`, `get`, `put`, `requestWithCache`) as implemented in the constructor: `#disabled: boolean = isResourcesCachingDisabled();`.

Configure via a `.env` file:

```env
JSAR_DEBUG_ENABLED=yes
JSAR_RESOURCES_CACHING=no

```

Or set programmatically in TypeScript or JavaScript:

```typescript
process.env.JSAR_DEBUG_ENABLED = 'yes';
process.env.JSAR_RESOURCES_CACHING = 'no';

// Now instantiate the loader
import { ResourceLoaderOnTransmute } from '@transmute/runtime2';
const loader = new ResourceLoaderOnTransmute();
// All subsequent fetches will bypass the cache

```

## Customizing Cache Expiration Time

To modify how long cached resources remain valid, set `JSAR_RESOURCES_CACHE_EXPIRATION_TIME` to a custom value in milliseconds. This overrides the default 86,400,000 ms (24 hours) that `CacheStorage` uses when creating the cache directory.

```env

# Set cache TTL to 2 hours (7,200,000 milliseconds)

JSAR_RESOURCES_CACHE_EXPIRATION_TIME=7200000

```

The `getResourceCacheExpirationTime()` function in [`lib/bindings/env.ts`](https://github.com/m-creativelab/jsar-runtime/blob/main/lib/bindings/env.ts) parses this integer and passes it to the `CacheStorage` instance as `#localExpirationTime`.

## Verifying Caching Configuration at Runtime

You can inspect the current caching state using utility functions exported from the environment bindings to confirm your configuration before executing resource operations:

```typescript
import { isResourcesCachingDisabled, getResourceCacheExpirationTime } from '@transmute/env';

console.log('Caching disabled:', isResourcesCachingDisabled()); // true or false
console.log('Cache TTL (ms):', getResourceCacheExpirationTime()); // e.g., 86400000 or custom value

```

## Summary

- **JSAR resource caching** is enabled by default and stores data in `${applicationCacheDirectory}/.res_cache` with a 24-hour TTL (86,400,000 ms).
- **Disable caching** by setting both `JSAR_DEBUG_ENABLED=yes` and `JSAR_RESOURCES_CACHING=no` to force network-only fetches; the runtime requires debug mode as a safety guard.
- **Customize expiration** by providing `JSAR_RESOURCES_CACHE_EXPIRATION_TIME` in milliseconds to override the default 24-hour window.
- **Verify settings** at runtime using `isResourcesCachingDisabled()` and `getResourceCacheExpirationTime()` from [`lib/bindings/env.ts`](https://github.com/m-creativelab/jsar-runtime/blob/main/lib/bindings/env.ts).

## Frequently Asked Questions

### Why do I need to enable debug mode to disable caching?

The JSAR runtime requires `JSAR_DEBUG_ENABLED=yes` as a safety mechanism to prevent accidental cache disabling in production environments. This two-step verification ensures that disabling the cache is an intentional debugging decision, not a configuration error, as enforced by the logic in [`lib/bindings/env.ts`](https://github.com/m-creativelab/jsar-runtime/blob/main/lib/bindings/env.ts).

### Where does JSAR store cached resources?

When enabled, the `CacheStorage` class creates a directory at `${applicationCacheDirectory}/.res_cache` within your application's cache folder. This path is initialized in [`lib/runtime2/ResourceLoader.ts`](https://github.com/m-creativelab/jsar-runtime/blob/main/lib/runtime2/ResourceLoader.ts) and managed entirely by the runtime without requiring manual intervention.

### Can I disable caching for specific requests only?

No, the current implementation in m-creativelab/jsar-runtime applies caching controls globally through environment variables. The `CacheStorage` class checks `isResourcesCachingDisabled()` once during instantiation, meaning you cannot toggle caching on a per-request basis without restarting the runtime with different environment settings.

### What happens if I set JSAR_RESOURCES_CACHING=no without enabling debug mode?

If `JSAR_DEBUG_ENABLED` is not set to `yes`, the `isResourcesCachingDisabled()` function returns `false` regardless of the `JSAR_RESOURCES_CACHING` value. Consequently, the cache remains active because the runtime ignores the disable flag when not in debug mode to prevent unintentional performance degradation.