dot CMS
Developers

Image Resizing and Processing in dotCMS with Angular and Next.js

Image Resizing and Processing in dotCMS with Angular and Next.js
Author image

Nicolas Molina

Senior Software Developer

Share this article on:

Managing images efficiently is crucial for web performance, especially in applications that rely on dynamic content. dotCMS, provides powerful image resizing and processing capabilities that can be integrated seamlessly into both Angular and Next.js applications.

Why is Image Optimization Important?

Efficient image loading is key to improving Largest Contentful Paint (LCP), a Core Web Vital metric that Google uses to evaluate page speed and user experience. Slow LCP can negatively impact conversion rates, user engagement, and SEO rankings. By using dotCMS Image Resizing and Processing, we can:

  • Serve appropriately sized images for different devices.

  • Reduce unnecessary bandwidth consumption.

  • Improve perceived load times, ensuring users see content faster.

dotCMS provides an Image Resizing and Processing service that dynamically adjusts images based on requested parameters, ensuring that only the necessary resolution and quality are loaded. This means users on mobile devices receive smaller images, while desktop users get higher-resolution versions without compromising speed.

Understanding the dotCMS Image API with HTML

Before integrating dotCMS images into frameworks like Angular or Next.js, it is useful to understand how the dotCMS Image API works. The API allows developers to modify images dynamically by adding parameters directly to the URL. This enables on-the-fly transformations such as resizing, format conversion, and compression.

Basic Usage of dotCMS Images

In dotCMS, images are stored with a unique identifier and can be accessed via the /dA/ path. A simple image request looks like this:

<img
  src="/dA/4694d40b-d9be-4e09-b031-64ee3e7c9642"
  alt="Basic image from dotCMS" />

Resizing Images

You can resize images by appending the width as a parameter:

<img
   src="/dA/4694d40b-d9be-4e09-b031-64ee3e7c9642/370w"
   alt="Resized image" />

This ensures that the image is only as large as necessary, improving performance and reducing bandwidth usage.

Changing Image Format (e.g., WebP for Better Compression)

To serve the image in WebP format, you can append the format type:

<img
   src="/dA/4694d40b-d9be-4e09-b031-64ee3e7c9642/270w/webp"
   alt="WebP formatted image" />

Using WebP results in smaller file sizes with the same quality, enhancing page load speed.

Adjusting Quality for Better Performance

You can modify the quality of an image using the q parameter, which helps optimize file size further:

<img
   src="/dA/4694d40b-d9be-4e09-b031-64ee3e7c9642/100w/50q"
   alt="Low quality optimized image" />

This is useful for serving lighter images when high fidelity is not required.

Using srcset for Responsive Images

For a responsive website, you can use srcset to serve different image sizes based on the device's screen resolution:

<img
  src="/dA/4694d40b-d9be-4e09-b031-64ee3e7c9642/webp/"
  srcset="
    /dA/4694d40b-d9be-4e09-b031-64ee3e7c9642/webp/1200w 1200w,
    /dA/4694d40b-d9be-4e09-b031-64ee3e7c9642/webp/600w 600w,
    /dA/4694d40b-d9be-4e09-b031-64ee3e7c9642/webp/300w 300w
  "
  alt="Responsive image with srcset"
/>

With this setup, browsers automatically select the most appropriate image size based on the user's screen resolution and device type.

For more information on all the parameters and configurations allowed by the API, visit: DotCMS Image and resizing filter

Image Optimization in Angular

Angular introduced the ngSrc directive as part of its NgOptimizedImage feature to automate best practices for image loading. This directive enhances performance by:

  • Automatically generating responsive srcset attributes.

  • Prioritizing Largest Contentful Paint (LCP) images with fetchpriority.

  • Lazy loading images by default to improve page performance.

  • Preventing layout shifts by enforcing explicit width and height attributes.

  • Providing automatic placeholders for improved perceived performance.

Using ngSrc, Angular applications can easily integrate with dotCMS Image Resizing and Processing, ensuring that images are always optimized for the best possible user experience.

Example usage of ngSrc:

<img
   ngSrc="banner.jpg"
   width="800"
   height="400"
   priority />

For using in your components you need to import NgOptimizedImage to use properly.

import { Component } from '@angular/core';
import { NgOptimizedImage } from '@angular/common';
@Component({
  selector: 'app-root',
  imports: [NgOptimizedImage],
  template: '<img ngSrc="banner.jpg" width="800" height="400" priority>',
})
export class AppComponent {}

With this simple declaration, Angular will automatically handle all optimizations, reducing the complexity of managing image performance manually.

Implementing a Manual Image Loader in Angular

To avoid manual configurations and duplicate code in Angular, it is possible to define a function that takes the image source and dynamically constructs a URL to serve optimized images

Step 1: Define a Custom Image Loader

Image loader is a function used by the NgOptimizedImage directive to produce a full image URL based on the image name and its width. For more information: ImageLoader

The manual implementation requires creating a provider for IMAGE_LOADER with a custom function:


import { IMAGE_LOADER, ImageLoaderConfig } from '@angular/common';
import { environment } from '../environments/environment';

export const appConfig = {
  providers: [
    {
      provide: IMAGE_LOADER,
      useValue: (config: ImageLoaderConfig) => {
        const { loaderParams, src, width } = config;
        const isOutsideSRC = loaderParams?.['isOutsideSRC'];

        if (isOutsideSRC) return src;

        const languageId = loaderParams?.['languageId'] || '1';
        const dotcmsHost = new URL(environment.dotcmsUrl).origin;
        const imageSRC = src.includes('/dA/') ? src : `/dA/${src}`;

        return `${dotcmsHost}${imageSRC}/${width}w?&language_id=${languageId}`;
      },
    },
  ],
};

Step 2: Use the Loader in Angular Components

Once the provider is set up, you can use the ngSrc directive to optimize images dynamically

<img
   ngSrc="banner.jpg"
   width="800"
   height="400"
   [loaderParams]="{ languageId: '2' }" />

While this approach works well, managing custom logic for different use cases can be cumbersome. Fortunately, dotCMS has introduced an optimized built-in solution.

Simplifying with provideDotCMSImageLoader in Angular

The Angular SDK library provided by dotCMS offers the provideDotCMSImageLoader() function, which already contains all the necessary settings to render your images hosted on your dotCMS instance.

Step 1: Import and Configure the Built-in Loader

Instead of manually implementing an image loader, you can now leverage the built-in provider.

import { provideDotCMSImageLoader } from '@dotcms/angular';
import { environment } from '../environments/environment';

export const appConfig = {
  providers: [
    provideDotCMSImageLoader(environment.dotcmsUrl),
  ],
};

Step 2: Use the Built-in Loader in Components

With this setup, you can directly use the ngSrc directive without needing additional parameters for basic use cases.

<img ngSrc="banner.jpg" width="800" height="400">

The provideDotCMSImageLoader automatically handles:

  • Image resizing based on specified width.

  • URL transformations for dotCMS images.

  • Language-based variations if needed.

  • Automatically select the most appropriate image size based on the user's screen

Image Optimization in Next.js

Next.js provides an Image Optimization API, which allows serving optimized images with a built-in <Image>component. dotCMS images can be integrated into this setup using a custom loader.

Implementing a Custom Image Loader in Next.js

To use dotCMS as an image source in Next.js, create a custom image loader:


import { useDotcmsPageContext } from '@dotcms/react';

const ImageLoader = ({ src, width }) => {
  const dotcmsURL = new URL(process.env.NEXT_PUBLIC_DOTCMS_HOST).origin;

  const context = useDotcmsPageContext();
  const languageId = context?.pageAsset.viewAs.language.id ?? 1;

  const imageSRC = src.includes('/dA/') ? src : `/dA/${src}`; // Check if the image is a dotCMS asset

  return `${dotcmsURL}${imageSRC}/${width}w?language_id=${languageId}`;
};

export default ImageLoader;

Using the Custom Loader in Next.js Components

Once the custom loader is implemented, use it within Next.js’s <Image> component:

import Image from 'next/image';
import ImageLoader from '../utils/imageLoader';

const Banner = () => {
  return (
    <Image
      loader={ImageLoader}
      src="banner.jpg"
      width={800}
      height={400}
      alt="Banner Image"
    />
  );
};

export default Banner;

Configuring the Custom Loader in next.config.js

Instead of adding a loader function in every component, you can configure it globally in the next.config.js file:

/** @type {import('next').NextConfig} */

const url = new URL(process.env.NEXT_PUBLIC_DOTCMS_HOST);

const nextConfig = {
    images: {
        remotePatterns: [
            {
                protocol: url.protocol.replace(":", ""),
                hostname: url.hostname,
                port: url.port || "",
            },
        ],
        loader: "custom",
        loaderFile: "./src/utils/imageLoader.js",
    },
};

module.exports = nextConfig;

By configuring the custom loader in next.config.js, you ensure that all images across the application are automatically optimized through dotCMS.

Conclusion

By leveraging dotCMS’s image API, developers ensure that their applications serve the right image at the right time, reducing load times and enhancing performance. Whether you're working with Angular or Next.js, integrating dotCMS for image handling is a powerful solution for improving Core Web Vitals and providing a better user experience.

Recommended Reading