Skip to content

@unitools/image (alpha)

This is the official documentation of the @unitools/image package.

For Next.js


Terminal window
npm install @unitools/image


Terminal window
yarn add @unitools/image

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

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

For Expo


Terminal window
npm install @unitools/image expo-image


Terminal window
yarn add @unitools/image expo-image

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

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

Alias path for assets

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.


Unified Image Path Resolution

In Next.js, image paths are typically specified using strings, while in React Native and 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 (

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.


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.-