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.

npm

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

Yarn

 yarn add @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.

npm

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

Yarn

yarn add @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

Prop	Type	Default	Description	Status	Support Status
source	string		Image source	required	✅
alt	string		Image alt text	required	✅
width	number		Image width	required	✅
height	number		Image height	required	✅
priority	boolean		Image priority	-	✅
placeholder	string		Image placeholder	-	✅
style	object		Image style	-	✅
onError	function		Error function	-	✅
onLoad	function		Load function	-	✅
contentFit	cover | contain | fill | none | scale-down		Fill the image container in a variety of ways	-	✅
contentFitPosition	string	-	An equivalent of the CSS object-position property.	-	✅