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

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 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) 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:

# 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:

// 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:

JSAR_DEBUG_ENABLED=yes
JSAR_RESOURCES_CACHING=no

Or set programmatically in TypeScript or JavaScript:

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.

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

JSAR_RESOURCES_CACHE_EXPIRATION_TIME=7200000

The getResourceCacheExpirationTime() function in 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:

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.

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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}