Skip to content

Unitools | <Image /> | By GeekyAnts

This document provides a comprehensive guide on configuring & using the official @unitools/image package. This configuration is tailored for Expo and Next.js applications, enabling seamless image usage across both frameworks.

For Next.js

Install @unitools/image and @unitools/image-next.

Terminal window
npm i @unitools/image @unitools/image-next

Add module resolver to your next.config.js file.

next.config.js
module.exports = {
webpack(config) {
config.resolve.alias["@unitools/image"] = "@unitools/image-next";
return config;
},
};

For Expo

Install @unitools/image, @unitools/image-expo and expo-image.

Terminal window
npm i @unitools/image @unitools/image-expo expo-image

Add module resolver to your babel.config.js file.

const path = require("path");
module.exports = function (api) {
api.cache(true);
return {
presets: ["babel-preset-expo"],
plugins: [
[
"module-resolver",
{
alias: {
"@unitools/image": "@unitools/image-expo",
},
},
],
],
};
};

Why Use Path Aliases?

Using path aliases allows you to create shorter and more readable import paths for your assets and modules. This helps maintain cleaner and more manageable code, especially in larger projects. By setting up a path alias, you ensure that asset paths are correctly resolved across different framework, such as Next.js and Expo.

Setting Up Path Aliases

To set up path aliases, you’ll need to modify your tsconfig.json file. This setup ensures that asset paths are resolved correctly, regardless of the platform you are working on.

Add path aliases to tsconfig.json:

{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/assets/*": ["./assets/*"]
}
}
}

Benefits of Using Path Aliases

  1. Simplified Imports: Instead of writing long relative paths, you can use concise and intuitive aliases. For example, instead of ../../../../assets/logo.png, you can use @/assets/logo.png.

  2. Cross-Platform Consistency: Path aliases ensure that the asset paths remain consistent across different framework (e.g., Next.js and Expo), reducing the chances of errors due to incorrect path resolutions.

  3. Enhanced Readability: Using aliases makes your code more readable and easier to navigate, which is especially beneficial in large codebases.

Usage (Unified Image Path Resolution)

In Next.js, image paths are typically specified using strings, while in Expo, the require function is used to resolve image paths. To unify the approach across platforms, the @unitools/image package standardizes the use of require for all framework. This ensures that your codebase remains consistent and eliminates the need to handle different image path formats for different platforms.

import Image from "@unitools/image";
export default function Home() {
return (
<View>
<Image
source={require("@/assets/logo.png")}
alt="Logo"
width={200}
height={200}
/>
</View>
);
}

Note: If you forgot to add the alias path for assets, images might not be displayed correctly. Make sure to set up path aliases as described in the previous section.

Props

PropTypeDefaultDescriptionStatusSupport Status
sourcestringImage sourcerequired
altstringImage alt textrequired
widthnumberImage widthrequired
heightnumberImage heightrequired
prioritybooleanImage priority-
placeholderstringImage placeholder-
styleobjectImage style-
onErrorfunctionError function-
onLoadfunctionLoad function-
contentFitcover | contain | fill | none | scale-downFill the image container in a variety of ways-
contentFitPositionstring-An equivalent of the CSS object-position property.-