Skip to main content

Next.js Cache & Image Configuration

Use this page to configure cache clearing for your frontend and to define allowed external image domains for Next.js pre-rendering.

Part of production-site setup

This is deploy-time configuration that complements the Next.js Integration Guide, which covers installing and wiring the SDK.

Vercel Cache Configuration​

Basic Cache Setup​

  • Vercel Cache Domain: The base domain for your Vercel project cache API (e.g., https://your-vercel-cache.example.com).
  • Vercel Cache API Key: Token used to authenticate cache purge requests.
  • Cache Targets: Labels used by your application to scope and clear cache entries when saving new scheduled content (e.g., HOMEPAGE, CMS).

Vercel Data Cache Clearing by Tags​

The Visual Experience Engine can automatically clear Vercel Data Cache based on configured tags when content changes occur. This feature is particularly useful for:

  • Replication Events: When content is replicated from staging to production
  • Content Updates: When scheduled content, categories, components, or specifications are updated
  • Environment-Specific Caching: Different cache configurations for staging vs production

Setup Instructions​

  1. Access Configuration:

    • Open your VEE instance and select the web instance you want to configure
    • Go to the Configuration section

  2. Configure Vercel Data Cache:

    • Select "NextJS Config" tab
    • Add your Vercel data cache endpoint
    • Configure cache tags for your application

  3. Test Configuration:

    • Schedule a replication to test cache clearing
    • Monitor cache invalidation events

Cache Clearing Triggers​

The Visual Experience Engine will automatically clear Vercel Data Cache when:

  • Replication occurs (automatic or manual duplication)
  • Scheduled content is updated (create, update, delete)
  • Categories are modified
  • Components are changed
  • Asset is updated
  • Specifications are modified

Environment Considerations​

  • Staging Environment: Actively modified, cache clearing happens frequently
  • Production Environment: Only modified during replication, cache can be more persistent
  • Warning: Enabling cache clearing for production will clear Vercel Data Cache when editing production content

Example Purge Contract​

{
  "targets": ["HOMEPAGE", "CMS"],
  "reason": "banner.updated",
  "timestamp": "2025-01-15T18:12:03.341Z"
}

Ensure your cache API accepts authenticated POST requests and performs idempotent purges per target.

Image Configuration (next.config.js)​

Provide the following images.remotePatterns in your Next.js next.config.js so the site can pre-render HTML with remote images safely. Replace the hostnames with the image hosts your scheduled content actually uses.

{
  "remotePatterns": [
    {
      "protocol": "https",
      "hostname": "your-image-cdn.example.com",
      "pathname": "/**"
    },
    {
      "protocol": "https",
      "hostname": "storage.googleapis.com",
      "pathname": "/**"
    }
  ]
}

Steps​

  1. Open your project's next.config.js.
  2. Add or merge the images.remotePatterns configuration above.
  3. Redeploy so the configuration is available during build and runtime.

Best Practices​

Cache Configuration​

  • Use descriptive cache targets that map cleanly to pages/routes
  • Keep purges granular (avoid global purges) to reduce CDN churn
  • Secure your cache API with token auth and rate limits
  • Monitor purge success/failure and retry on transient errors

Vercel Data Cache Management​

  • Configure environment-specific settings: Different cache strategies for staging vs production
  • Test cache clearing: Verify that cache invalidation works correctly after configuration
  • Monitor cache performance: Track cache hit rates and invalidation frequency
  • Use appropriate tags: Tag your cache entries with meaningful labels that match your Visual Experience Engine configuration
  • Consider production impact: Be aware that enabling cache clearing for production will affect production-site performance

Troubleshooting Cache Issues​

  • Verify endpoint configuration: Ensure your Vercel cache endpoint is accessible and properly configured
  • Check authentication: Verify that API keys and tokens are valid and have proper permissions
  • Monitor logs: Review cache clearing logs to identify any failed invalidation attempts
  • Test with replication: Use the replication feature to test cache clearing functionality