Images

Overview

The SCAYLE Storefront Application provides a comprehensive image optimization solution that ensures fast loading times and smooth user experiences. The system builds on top of the Nuxt Image module, extended with SCAYLE-specific features through the @scayle/nuxt-image-provider package.

This solution automatically optimizes images through lazy loading, format selection, and responsive resizing. It maintains consistent image dimensions through global aspect ratio configuration while allowing component-level customization when needed.

The image optimization solution improves Core Web Vitals scores and provides a polished user experience across all devices. This documentation covers configuration, component usage, aspect ratio management, and best practices for optimal image delivery.

How It Works

The image optimization automatically processes images during the build process and at runtime. Images load lazily by default, improving initial page load performance. The optimization serves images in the best format supported by each browser, including AVIF, WebP, or the original format.

The solution maintains consistent image dimensions through a global aspect ratio configuration. This prevents layout shifts and ensures a uniform appearance across product listings. Components can override the global aspect ratio when specific design requirements demand different proportions.

Images are delivered through the SCAYLE CDN, which provides fast global distribution. The solution automatically generates appropriately sized images for different viewports based on responsive breakpoints. This ensures users receive optimally sized images for their device and connection speed.

Technical Architecture

The Storefront Application's image architecture uses a layered approach with clear separation of concerns. The base layer handles image optimization and format conversion, while the provider layer adds SCAYLE-specific transformations and CDN integration. Components sit on top of this architecture, providing a developer-friendly API for image usage.

The @nuxt/image Module

Nuxt Image is a Nuxt module that simplifies and optimizes image handling within the application. It integrates directly into the Nuxt build process, automatically optimizing images at build time or on demand.

It provides:

• Lazy loading: Images load only when needed, improving initial page load performance.
• Automatic format selection: Serves WebP, AVIF, or other modern formats when supported by the browser.
• Responsive resizing: Automatically generates appropriately sized images for different viewports.
• CDN integration: Seamlessly works with CDN providers for fast global delivery.

By integrating directly into the Nuxt build process, Nuxt Image streamlines the image workflow. This results in significant performance improvements and better Core Web Vitals scores.

SCAYLE's Enhanced Image Provider

The @scayle/nuxt-image-provider package extends Nuxt Image with SCAYLE-specific features. Unlike standard @nuxt/image, this provider is specifically designed to integrate with SCAYLE's infrastructure.

It provides:

• SCAYLE-specific image transformations: Supports SCAYLE CDN modifiers like brightness and trim.
• Automatic height calculation: When both width and aspect ratio are provided, height is automatically calculated.
• Pre-configured optimal settings: Components come with sensible defaults for SCAYLE CDN.
• Seamless integration: Works out of the box with SCAYLE product images and media assets.

These features ensure optimal image delivery tailored for SCAYLE-powered applications.

Implementation Guide

The Storefront Application provides two main image components that extend the standard Nuxt Image components with SCAYLE-specific optimizations. These components handle all image optimization automatically.

"ScayleImg" Component

ScayleImg is a wrapper around NuxtImg with pre-configured settings for the SCAYLE CDN. Use this component for simple image display scenarios where responsive behavior is not required.

Basic Usage

vue

Copy

Props

The ScayleImg component accepts the following props:

Example with Aspect Ratio

vue

Copy

When width and aspectRatio are provided together, the height is automatically calculated. Any manually passed height will be ignored in this case.

"ScaylePicture" Component

ScaylePicture is a wrapper around NuxtPicture that provides responsive image support with multiple sources. Use this component for images that need different sizes or formats for different viewports.

Basic Usage

vue

Copy

Props

The ScaylePicture component accepts all props from ScayleImg, plus:

Example

vue

Copy

Both components accept standard HTML attributes such as aria properties and Vue-specific event listeners. This ensures full compatibility with accessibility requirements and event handling.

Configuration

The SCAYLE image provider requires configuration in your nuxt.config.ts file. This configuration enables the image optimization features and sets up responsive breakpoints.

Provider Configuration

Configure the SCAYLE image provider in your nuxt.config.ts:

typescript

Copy

The screens configuration defines responsive breakpoints that match your Tailwind CSS configuration. This ensures consistent responsive behavior across your application.

Global Aspect Ratio Configuration

The Storefront Application defines a global default aspect ratio for product images in config/ui.ts. This constant ensures consistent image dimensions across the application.

typescript

Copy

This constant is used throughout the application as the default aspect ratio for product images. The format is [width, height], where [3, 4] represents a 3:4 (portrait) aspect ratio.

Why This Matters

The global aspect ratio configuration provides several benefits:

• Consistency - All product images use the same aspect ratio by default.
• Layout Stability - Prevents Cumulative Layout Shift (CLS) issues that impact Core Web Vitals.
• Easy Customization - Change one value to update all product images globally.

Tailwind Integration

The global aspect ratio is integrated into Tailwind CSS configuration, allowing you to use it in utility classes:

typescript

Copy

This enables you to use the aspect-product utility class in your templates:

vue

Copy

Code Examples

The following examples demonstrate common image usage patterns in the Storefront Application. These examples use real components from the codebase.

Using the Global Aspect Ratio

The SFProductImage component automatically uses the global aspect ratio:

vue

Copy

The component uses PRODUCT_IMAGE_ASPECT_RATIO as its default, ensuring all product images maintain consistent proportions unless explicitly overridden.

Common Aspect Ratio Examples

The following examples show different aspect ratio configurations:

html

Copy

Real-World Examples

Sibling Product Selection (Square Images)

The SFSiblingSelection component uses square images for variant selection:

html

Copy

This provides a compact, consistent display for variant selection.

Product Cards (Default Aspect Ratio)

Product cards use the default PRODUCT_IMAGE_ASPECT_RATIO (3:4):

html

Copy

This ensures consistency across product listings.

CMS Image Aspect Ratios

For CMS-managed images (Contentful and Storyblok), aspect ratios can be configured per image through the CMS interface. The Storefront Application supports the following aspect ratio options:

• original: Uses the image's original aspect ratio.
• 1:1: Square.
• 16:9: Landscape (widescreen).
• 4:3: Landscape (standard).

These can be set independently for desktop and mobile views:

ts

Copy

CMS images use CSS custom properties to apply responsive aspect ratios:

html

Copy

Customizing Aspect Ratios

You can customize aspect ratios at both the global and component levels. The global configuration affects all product images, while component-level overrides allow specific customization when needed.

Changing the Global Product Image Aspect Ratio

To change the default aspect ratio for all product images across the application, follow these steps:

1. Open config/ui.ts:
   Copy

   export const PRODUCT_IMAGE_ASPECT_RATIO = [3, 4] // Change to your desired ratio
2. Update the value:
   typescript

   Copy
3. Restart your development server:
   The Tailwind CSS configuration automatically uses the updated value since it imports from config/ui.ts. After changing the global aspect ratio, restart your development server for Tailwind changes to take effect.

Overriding Aspect Ratio in Specific Components

Override the aspect ratio by passing the aspect-ratio prop directly to the component:

vue

Copy

You can also use a computed property for dynamic aspect ratios based on component state or props.

Image Optimization Features

The SCAYLE image provider includes several optimization features that improve performance and user experience. These features work automatically when using the SCAYLE image components.

Automatic Format Selection

The SCAYLE image provider automatically serves images in the best format supported by the browser:

• AVIF: Modern, highly efficient format (when supported).
• WebP: Widely supported, efficient format.
• Original format: Fallback for older browsers.

Quality Control

Control image quality to balance file size and visual quality:

html

Copy

Default quality is 75, which provides a good balance. Increase for hero images, decrease for thumbnails.

Image Transformations

Trimming

Remove whitespace from images:

html

Copy

Brightness Adjustment

Adjust image brightness:

html

Copy

Responsive Images

The Storefront Application supports responsive images through the sizes attribute and consistent breakpoints. This ensures users receive optimally sized images for their device.

Sizes Attribute

Use the sizes attribute to tell the browser which image size to load for different viewports:

html

Copy

This example configuration:

• Uses full width on extra small and small screens.
• Uses half width on medium screens.
• Uses one-third width on large screens.
• Uses fixed 320px on extra large screens.

Breakpoints

The application uses consistent breakpoints defined in config/ui.ts:

typescript

Copy

These breakpoints are used for both image optimization and Tailwind CSS responsive classes.

Best Practices

Follow these best practices to ensure optimal image delivery and user experience across your Storefront Application.

Always Provide Alt Text

Accessibility is crucial. Always provide descriptive alt text:

html

Copy

Use Appropriate Aspect Ratios

• Use the global aspect ratio for consistency.
• Override only when necessary for specific design requirements.
• Consider the visual hierarchy when choosing aspect ratios.

Optimize Image Sizes

• Use responsive sizes attributes.
• Set appropriate quality values.
• Leverage lazy loading for below-the-fold images.

Preload Critical Images

Preload hero images and above-the-fold product images:

html

Copy

Use ScaylePicture for Responsive Images

Use ScaylePicture instead of ScayleImg when you need responsive behavior:

html

Copy

Maintain Aspect Ratio Consistency

Stick to the global aspect ratio for product images unless you have a specific design requirement. This ensures:

• Consistent visual appearance.
• Better layout stability.
• Easier maintenance.

Migration from "NuxtImg"/"NuxtPicture"

If you're migrating from standard NuxtImg or NuxtPicture components, follow these steps:

1. Replace imports:

vue

Copy

2. Add aspect ratio prop:

html

Copy

3. Update provider references:

The provider="scayle" prop is no longer needed as it's the default for SCAYLE components.

For further migration details please check out our Migration Guide.

Troubleshooting