Page Caching

EcoPages includes a built-in caching system that supports Static, Dynamic, and Incremental Static Regeneration (ISR) strategies. This allows you to serve fresh content with the performance of static pages.

Caching Strategies

You can define the caching behavior for any page using the cache property in the eco.page configuration.

Static (Default)

By default, pages are cached indefinitely. This is perfect for content that rarely changes.

export default eco.page({
	cache: 'static',
	render: () => html`<h1>Hello World</h1>`,
});

These pages are generated once and served from the cache until the server restarts or the cache is manually invalidated.

Dynamic

Dynamic pages are never cached. They are rendered fresh for every request. Use this for personalized content or real-time data.

export default eco.page({
	cache: 'dynamic',
	render: () => html`<h1>Current Time: ${new Date().toISOString()}</h1>`,
});

Incremental Static Regeneration (ISR)

ISR allows you to cache pages for a specific duration ("revalidate" time).

1. First Request: The page is rendered and cached.
2. Subsequent Requests: The cached page is served immediately.
3. After Revalidation Time: The next request still gets the cached (stale) version, but it triggers a background regeneration. Future requests will see the updated content.

export default eco.page({
	cache: {
		revalidate: 60, // Seconds
		tags: ['blog', 'posts'],
	},
	render: () => html`<h1>Latest Updates</h1>`,
});

This strategy uses the Stale-While-Revalidate pattern, ensuring visitors always get instant responses.

Global Configuration

You can configure global cache settings in your eco.config.ts file provided by the Config Builder.

// eco.config.ts
const config = await new ConfigBuilder()
	.setCacheConfig({
		enabled: true,
		defaultStrategy: 'static',
		maxEntries: 1000,
	})
	.build();

Configuration Options

On-Demand Invalidation

You can manually invalidate cached pages locally or via an API handler using tags or specific paths. This is useful for "purging" content when data updates (e.g., from a CMS webhook).

API Handler Example

// src/api/revalidate.ts
app.post('/api/revalidate', async ({ request, services }) => {
	const { tags, paths } = await request.json();
 
	// Invalidate by tags
	if (tags) await services.cache.invalidateByTags(tags);
 
	// Invalidate by path
	if (paths) await services.cache.invalidateByPaths(paths);
 
	return Response.json({ revalidated: true });
});

Headers

EcoPages automatically sets appropriate headers based on the chosen strategy.