Importing and processing static images

The RSG 2.0 SDK image import and processing feature manages the static images in your app. It provides TypeScript-native imports, automatic dimension calculation, multi-resolution handling, and optional build-time optimization.

You import an image in a TypeScript file with an import statement. At build time, the build system copies the image, calculates its width and height, and exports an object that contains the image uri and dimensions. You pass the uri to components such as Poster.

The feature does the following:

Eliminates the need to provide full static paths to your images
Provides a TypeScript method for importing assets
Enables you to import images from anywhere in your app's source folder (for example, the same directory as the .tsx files that use the images)
Enables you to refer to both full high definition (FHD) and high definition (HD) versions of image assets from a single import statement
Calculates the width and height of images and passes them to the components that use them (for example, Poster components)
Optimizes images at build time by generating HD images from FHD versions and by compressing PNG and JPEG images to WebP (a more efficient image format)

The RSG 2.0 SDK image import and processing feature is optional. You can store images in the static directory directly and then refer to them by their paths (for example, pkg:/images/...).

Configuring image processing

You configure image processing in the app.images object of your roku-config.ts file. The following example shows the available options with their default values:

import type { RokuConfig } from "@roku-sdk/rsg-ts/roku-config";

const configuration: RokuConfig = {
    app: {
        entryPoint: "src/index.ts",
        images: {
            convertToWebp: true, // Default: true; converts images to WebP format
            generateHd: false, // Default: false; generates HD versions automatically
            pathPrefix: "pkg:/images/" // Default: "pkg:/images/"; path prefix for image URIs
        }
    }
};

export default configuration;

Configuration options

You can set the following options to customize image processing:

convertToWebp: Converts PNG and JPEG images to WebP format to improve compression (default is true).
generateHd: Automatically generates HD versions of images (default is false).
pathPrefix: Specifies the path prefix to be added to image URIs imported in the app (default is "pkg:/images/"). This is useful if images are loaded from a directory other than the default (for example, dynamic content loading setup). See the next section for more information.

Using custom image path prefixes

By default, the build prefixes the URIs of all imported images with pkg:/images/. You can customize this path prefix with the pathPrefix configuration option to load images from a different directory structure (for example, when setting up dynamic content loading).

The following example sets a custom image path with the pathPrefix option:

const configuration: RokuConfig = {
    app: {
        entryPoint: "src/index.ts",
        images: {
            pathPrefix: "pkg:/assets/images/" // Custom path instead of default "pkg:/images/"
        }
    }
};

You can then import images. The resulting uri uses the pathPrefix value (pkg:/assets/images/ in this example):

import heroImage from "./hero.png";
console.log(heroImage);
// Output: {
//   uri: "pkg:/assets/images/hero.png",
//   dimensions: {
//     fhd: { width: 1920, height: 1080 }
//   }
// }

Importing images

You can import images directly in your TypeScript files; the build system processes them automatically and provides structured metadata. The following statement shows the import syntax:

import <imgVar> from "<relative-path-to-image>/<filename>.<ext>"

At build time, the import statement does the following:

Copies the image to the pkg:/images folder
Gets the width and height of the image
Exports an imgVar object with the following structure:

{
  uri: "pkg:/images/<filename>.<ext>",
  dimensions: {
    fhd: {
      width: <width>,
      height: <height>
    }
  }
}

The build treats imports without resolution substitutes as FHD. You can read the uri, width, and height and pass them to components. The texture manager scales the image to a lower resolution as needed. The following example shows the output for an import without a resolution substitute:

import heroImage from "./hero.png";
console.log(heroImage);
// Output: {
//   uri: "pkg:/images/hero.png",
//   dimensions: {
//     fhd: { width: 1920, height: 1080 }
//   }
// }

Using imported images with components

When you use imported images with components such as Poster, you only need to pass the uri property to the component's uri field. You can use the dimensions object to perform calculations in your TypeScript code, if needed.

Using a single imported image

You can import a single image and use its URI with a Poster component. You can also use its dimensions for aspect ratio calculations or layout logic. The following example shows both:

import nature from "./nature.png";

// Use the uri property with Poster component
<poster width={200} height={200} uri={nature.uri} />

// Dimensions are available for calculations
const aspectRatio = nature.dimensions.fhd.width / nature.dimensions.fhd.height;

Using resolution substitutes with components

You can use the Roku texture manager to select the appropriate resolution automatically at runtime. The following example passes only the uri to the Poster component and reads the dimensions for both resolutions:

import mountains from "./mountains-*.png";

// Pass only the uri; Roku's texture manager handles resolution selection
<poster width={200} height={200} uri={mountains.uri} />

// Access dimensions for both resolutions
console.log(mountains.dimensions.fhd); // { width: 1920, height: 1080 }
console.log(mountains.dimensions.hd);  // { width: 1280, height: 720 }

Destructuring imported image objects for cleaner code

You can destructure the imported image object for more convenient access. The following example destructures the uri and dimensions properties:

import { uri as badgeUri, dimensions as badgeDims } from "./badge-*.9.png";

// Use destructured values
<poster width={200} height={200} uri={badgeUri} />

// Calculate properties based on dimensions
const scaledWidth = badgeDims.fhd.width * 0.5;
const scaledHeight = badgeDims.fhd.height * 0.5;

📘
Important
You must pass only the uri property to component fields that accept URIs, not the entire imported object. Use the dimensions property for layout calculations in your TypeScript code, and do not pass it to components.

Using resolution substitutes

You can use a single import statement that includes a resolution substitute (a placeholder that replaces the resolution suffix in the file name) to reference both the FHD and HD versions of an image asset located in your app's source folder. To use a resolution substitute, complete the following steps:

Import the image using a resolution substitute in place of the resolution suffix:
```
import <imgVar> from "<relative-path-to-image>/<filename><resolution-substitute>.<ext>"
```

Configure the matching uriResolutionSubstitutions in your roku-config.ts:

const configuration: RokuConfig = {
    app: {
        entryPoint: "src/index.ts",
        images: {
            uriResolutionSubstitutions: {
                placeholder: "<resolution-substitute>", // for example, "$$RES$$" or "*"
                sdSubstitution: "<sd-value>", // for example, "sd"
                hdSubstitution: "<hd-value>", // for example, "hd" or "720p"
                fhdSubstitution: "<fhd-value>" // for example, "fhd" or "1080p"
            }
        }
    }
};

When you use uriResolutionSubstitutions, the build automatically generates the uri_resolution_autosub manifest entry; therefore, you do not need to include it in manifestEntries. If you use a static manifest file, you can set uri_resolution_autosub=$CONFIG to avoid build-time warnings.

Understanding import processing behavior

This section describes what the build does when an import statement includes a resolution substitute. At build time, the import statement does the following:

Replaces the resolution substitute with the FHD value and the HD value from your configuration
Copies those images to the pkg:/images folder
Gets the width and height of each image
Exports an imgVar object with the following structure:

{
  uri: "pkg:/images/<filename><resolution-substitute>.<ext>",
  dimensions: {
    fhd: {
      width: <width>,
      height: <height>
    },
    hd: {
      width: <width>,
      height: <height>
    }
  }
}

The URI contains the resolution substitute placeholder (for example, *) as it appears in the import statement. At runtime, the Roku texture manager automatically resolves the placeholder to the appropriate resolution-specific file.

Importing an image with resolution substitutes

This section shows an import statement and its output for a specific set of resolution substitutions.

The following configuration defines the URI resolution substitutions:

app: {
    entryPoint: "src/index.ts",
    images: {
        uriResolutionSubstitutions: {
            placeholder: "*",
            sdSubstitution: "sd",
            hdSubstitution: "hd",
            fhdSubstitution: "fhd"
        }
    }
}

The following files must be in the source folder:

hero-fhd.png
hero-hd.png

You can then use the following import statement:

import heroImage from "./hero-*.png";
console.log(heroImage);
// Output: {
//   uri: "pkg:/images/hero-*.png",
//   dimensions: {
//     fhd: { width: 1920, height: 1080 },
//     hd: { width: 1280, height: 720 }
//   }
// }

Importing nine-patch images

You can import nine-patch images the same way as regular images. The system automatically detects nine-patch images by the .9. pattern in the filename and handles them appropriately. The following example imports nine-patch images:

import buttonBackground from "./button.9.png";
// Works with resolution substitutes too
import multiResolutionButtonBackground from "./button*.9.png";

Reference

This section describes the image processing features, configuration options, filename conventions, supported formats, and error handling.

Generating HD images automatically

You can enable automatic HD image generation so that the build system creates 2/3-scale versions of your FHD images without manual intervention. When you set generateHd: true, the build system can generate HD versions of your FHD images. The following example enables automatic HD generation:

const configuration: RokuConfig = {
    app: {
        entryPoint: "src/index.ts",
        images: {
            generateHd: true // Enable automatic HD generation
        }
    }
};

Converting images to WebP

You can enable automatic WebP conversion to improve image compression and runtime performance. When you set convertToWebp: true, the build converts images to WebP format automatically. In the following example, the source image is a PNG and the output is a WebP image:

import heroImage from "./hero.png";
// Even though the source is PNG, the output is WebP:
// {
//   uri: "pkg:/images/hero.webp",
//   dimensions: {
//     fhd: { width: 1920, height: 1080 }
//   }
// }

Filename handling

The build constructs the final image URI from your import statement and configuration. The URI consists of the following parts:

The configured path prefix (default: pkg:/images/)
The exact filename from the import statement
The placeholder (for example, *) when you use resolution substitutes
The file extension, which may change if WebP conversion is enabled (for example, .png becomes .webp)

Supported image formats

You can import images in the following standard formats:

PNG (.png)
JPEG (.jpg, .jpeg)
WebP (.webp)

Error handling

The build process reports an error with a descriptive message for each of the following image-related issues:

Missing HD images when using nine-patch with resolution substitutes
Unsupported image formats
File access errors
Image processing failures

Configuring image processing

Configuration options

Using custom image path prefixes

Importing images

Using imported images with components

Using a single imported image

Using resolution substitutes with components

Destructuring imported image objects for cleaner code

Important

Using resolution substitutes

Understanding import processing behavior

Importing an image with resolution substitutes

Importing nine-patch images

Reference

Generating HD images automatically

Converting images to WebP

Filename handling

Supported image formats

Error handling

Related documentation