Registry / devops / cdn-cache-control

cdn-cache-control

library1.3.1jsnpmunverified

A subclass of the fetch Headers class that simplifies setting Cache-Control and CDN-specific cache headers for modern CDNs. Version 1.3.1 supports Netlify, Vercel, Cloudflare, and Akamai with automatic platform detection. It provides a chainable API with sensible defaults (CDN cache for 1 year, browser revalidation) and methods like `ttl()`, `swr()`, and `immutable()`. Unlike raw header manipulation, it abstracts CDN-specific quirks and promotes best practices like stale-while-revalidate and surrogate keys. Ships TypeScript types. Released as an npm package and JSR module.

devops

npm install cdn-cache-control

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CDN-CACHE-CONTROL

cdn-cache-control

devopsjavascriptv1.3.1

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.

CacheHeaders

✓ import { CacheHeaders } from 'cdn-cache-control'

✗ const CacheHeaders = require('cdn-cache-control')

ESM-only since v1.0.0. CommonJS require will throw an error.

CacheHeaders (with JSR)

✓ import { CacheHeaders } from 'jsr:@ascorbic/cdn-cache-control'

✗ import { CacheHeaders } from '@ascorbic/cdn-cache-control'

For Deno users, the package is available via JSR import. The npm package and JSR package are separate.

ONE_HOUR, ONE_DAY, etc.

✓ import { ONE_HOUR } from 'cdn-cache-control'

Named duration constants are exported as UPPER_SNAKE_CASE. Available: ONE_MINUTE, ONE_HOUR, ONE_DAY, ONE_WEEK, ONE_YEAR.

CacheHeaders type

✓ import type { CacheHeaders } from 'cdn-cache-control'

✗ import { CacheHeaders } from 'cdn-cache-control' // when only using type for type annotations

TypeScript users can import the class type for annotations. The class is both a value and a type.

Shows how to create CacheHeaders with TTL and stale-while-revalidate, and log the resulting headers. Includes type-safe usage.

import { CacheHeaders, ONE_HOUR, ONE_WEEK } from 'cdn-cache-control'; import { unstable_cache } from 'next/cache'; // For a page that should be cached by CDN for 1 hour, // serve stale content for up to 1 week while revalidating, // and require browser to always revalidate const headers = new CacheHeaders() .ttl(ONE_HOUR) .swr(ONE_WEEK); // Use in a Next.js App Router response // export async function GET() { return new Response(..., { headers }) } console.log(headers.get('CDN-Cache-Control')); // 'public, s-maxage=3600, stale-while-revalidate=604800, must-revalidate' console.log(headers.get('Cache-Control')); // 'public, max-age=0, must-revalidate'

Debug

Known issues

deprecatedThe `cdn` option in constructor is deprecated in favour of platform auto-detection.

fix

Remove the second argument to `new CacheHeaders()` or use `setPlatform('netlify')` method.

affects: >=1.0.0

breakingIn version 1.0.0, the package switched to ESM-only. CommonJS `require()` will fail.

fix

Use `import` or update your bundler to handle ESM. If you cannot use ESM, stick to 0.x.

affects: >=1.0.0

gotchaThe `swr()` method defaults to 1 week stale-while-revalidate time, which may be too long for dynamic content.

fix

Explicitly pass an argument to `swr()`, e.g., `.swr(ONE_HOUR)`.

affects: >=1.0.0

gotchaAuto-detection of CDN platform may not work in all environments, causing generic `CDN-Cache-Control` header to be used instead of CDN-specific headers like `Netlify-CDN-Cache-Control`.

fix

Manually set the CDN via the second constructor argument or the `setPlatform()` method.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Class extends value undefined is not a constructor or null

The fetch Headers class is not available (usually in older Node.js or browser polyfill issues).

fix

Upgrade Node to 18+ or add a polyfill like `node-fetch` and import `Headers` globally.

Cannot find module 'cdn-cache-control' or its corresponding type declarations.

Package not installed or TypeScript cannot resolve types.

fix

Run `npm install cdn-cache-control`. If still failing, ensure your tsconfig.json includes `node_modules/@types` or has `skipLibCheck: false`.

SyntaxError: The requested module 'cdn-cache-control' does not provide an export named 'CacheHeaders'

Using CommonJS `require()` with an ESM-only package.

fix

Change to `import { CacheHeaders } from 'cdn-cache-control'` or use dynamic `import()`.

Upgrade

Version history

1.3.1latest on npm

Audit

Dependencies

nodeoptionalUses the fetch Headers class available in Node 18+, or requires a polyfill in older versions.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/ascorbic/cdn-cache-control ↗

packagecdn-cache-control ↗

homepagehttps://github.com/ascorbic/cdn-cache-control ↗