moko-resources

0.26.4indexed

Accesses resources like strings, colors, images, and fonts with system localization support across platforms. Offers Compose Multiplatform integration and handles raw files, assets, and runtime localization.

AndroidJSJVMNativeWasm·icerockdev/moko-resources

1.3k

Stars

Used by

dependents

Health

/ 100

moko-resources
kotlin-version badge badge badge badge badge badge badge badge badge

Mobile Kotlin resources

This is a Kotlin MultiPlatform library (and Gradle plugin) that provides access to the resources on macOS, iOS, Android the JVM and JS/Browser with the support of the default system localization.

Also MOKO resources supports Compose Multiplatform so you can implement all your UI in Kotlin with Jetpack Compose and MOKO resources.

Features
Requirements
Versions

Features

Requirements

Gradle version 8.4+
Kotlin 2.1.0+
Android Gradle Plugin 8.3.0+
Android API 16+
iOS version 12.0+
Compose Multiplatform 1.6.0+

Installation

Gradle setup

root build.gradle

buildscript {
    repositories {
        gradlePluginPortal()
    }

    dependencies {
        classpath "dev.icerock.moko:resources-generator:0.26.4"
    }
}


allprojects {
    repositories {
        mavenCentral()
    }
}

project build.gradle

apply plugin: "dev.icerock.mobile.multiplatform-resources"

dependencies {
    commonMainApi("dev.icerock.moko:resources:0.26.4")
    commonMainApi("dev.icerock.moko:resources-compose:0.26.4") // for compose multiplatform

    commonTestImplementation("dev.icerock.moko:resources-test:0.26.4")
}

multiplatformResources {
    resourcesPackage.set("org.example.library") // required
    resourcesClassName.set("SharedRes") // optional, default MR
    resourcesVisibility.set(MRVisibility.Internal) // optional, default Public
    iosBaseLocalizationRegion.set("en") // optional, default "en"
    iosMinimalDeploymentTarget.set("11.0") // optional, default "9.0"
}

Custom resource sourceSet

If you need custom path for source of resources, you need add in plugin configuration resourcesSourceSets option: project build.gradle

multiplatformResources {
    resourcesPackage.set("org.example.library.customResource") // required
    resourcesSourceSets {
        getByName("jvmMain").srcDirs(
            File(projectDir, "customResources")
        )
    }  
}

On next step, you must create inside of project directory folder with name: customResources, and moved your resources there.

- projectDirectory
-- customResources
--- assets
--- base
--- image

Example of custom sourceSet in: resources-gallery sample, inside jvm-app

Export classes to Swift

To use toUIColor(), toUIImage(), desc() and other iOS extensions from Swift - you should add export declarations:

framework {
    export("dev.icerock.moko:resources:0.26.4")
    export("dev.icerock.moko:graphics:0.10.0") // toUIColor here
}

Multi-module Gradle projects

If you have multiple gradle modules and resources stored not in module that compiles into framework for iOS, for example:

- shared
-- resources
-- feature-1
-- feature-2

You should enable moko-resources gradle plugin in resources module, that contains resources, AND in shared module, that compiles into framework for iOS (same for jvm, JS, macos targets. Only android will works without this).

Android Host Tests (Unit Tests)

If you use the new Android Multiplatform Library plugin (com.android.kotlin.multiplatform.library), enabling Android resources for host tests (Unit tests) depends on your AGP version. This is required for moko-resources to access generated R classes during testing.

For AGP 8.8.0 and higher Use the native DSL directly inside the androidLibrary block:

kotlin {
    androidLibrary {
        // ... base configuration (namespace, compileSdk, etc.)

        withHostTest {
            isIncludeAndroidResources = true
        }
        
        // OR if you use builder for advanced configuration:
        /*
        withHostTestBuilder {
            // your builder config
        }.configure {
            isIncludeAndroidResources = true
        }
        */
    }
}

For AGP 8.2.0 - 8.7.x The withHostTest DSL is not yet available.

As a workaround, enable Android resources using the legacy android block::

android {
    testOptions {
        unitTests.isIncludeAndroidResources = true
    }
}

Xcode setup

For correct work of plugin tasks you need disable ENABLE_USER_SCRIPT_SANDBOXING in .xcodeproj file: Xcode > Build Settings > Build Options > User Script Sandbox set NO

In iOS/macOS Info.plist need to add localizations, to use localizations strings.


<key>CFBundleLocalizations</key><array>
<string>en</string>
<string>ru</string>
</array>

in array should be added all used languages.

Android build types

If your project includes a build type, for example staging which isn't in moko-resources. That isn't an issue. Use matchingFallbacks to specify alternative matches for a given build type, as shown below

buildTypes {
    staging {
        initWith debug
        matchingFallbacks = ['debug']
    }
}

JS Webpack

JS/Browser generates json files which is included in webpack by default. For more details about JS see samples/resources-gallery/web-app sample

iOS/macOS static kotlin frameworks support

Static framework can't have own resources, so we should setup additional Build Phase in Xcode that will copy resources to application.

⚠ Warning

This phase should be placed after Kotlin Framework Compilation phase.

Please replace :yourframeworkproject to kotlin project gradle path, and set correct relative path ($SRCROOT/../ in example).

With org.jetbrains.kotlin.native.cocoapods

In Xcode add Build Phase (at end of list) with script:

"$SRCROOT/../gradlew" -p "$SRCROOT/../" :yourframeworkproject:copy`YourFrameworkName`FrameworkResourcesToApp \
    -Pmoko.resources.BUILT_PRODUCTS_DIR="$BUILT_PRODUCTS_DIR" \
    -Pmoko.resources.CONTENTS_FOLDER_PATH="$CONTENTS_FOLDER_PATH" \
    -Pkotlin.native.cocoapods.platform="$PLATFORM_NAME" \
    -Pkotlin.native.cocoapods.archs="$ARCHS" \
    -Pkotlin.native.cocoapods.configuration="${KOTLIN_FRAMEWORK_BUILD_TYPE:-$CONFIGURATION}"

YourFrameworkName is name of your project framework. Please, see on a static framework warning for get correct task name.

Without org.jetbrains.kotlin.native.cocoapods

In Xcode add Build Phase (at end of list) with script:

"$SRCROOT/../gradlew" -p "$SRCROOT/../" :yourframeworkproject:copyFrameworkResourcesToApp \
    -Pmoko.resources.PLATFORM_NAME="$PLATFORM_NAME" \
    -Pmoko.resources.CONFIGURATION="${KOTLIN_FRAMEWORK_BUILD_TYPE:-$CONFIGURATION}" \
    -Pmoko.resources.ARCHS="$ARCHS" \
    -Pmoko.resources.BUILT_PRODUCTS_DIR="$BUILT_PRODUCTS_DIR" \
    -Pmoko.resources.CONTENTS_FOLDER_PATH="$CONTENTS_FOLDER_PATH"

Disable warning about static framework usage

To disable warnings about static framework in gradle.properties:

moko.resources.disableStaticFrameworkWarning=true

iOS executable

When you use executable kotlin target you should add custom build phase to xcode, after kotlin compilation:

"$SRCROOT/../gradlew" -p "$SRCROOT/../" :shared:copyResourcesDebugExecutableIosSimulatorArm64 \
    -Pmoko.resources.BUILT_PRODUCTS_DIR=$BUILT_PRODUCTS_DIR \
    -Pmoko.resources.CONTENTS_FOLDER_PATH=$CONTENTS_FOLDER_PATH

copyResourcesDebugExecutableIosSimulatorArm64 should be configured depends on target.

Configured sample you can see in samples/kotlin-ios-app

Creating Fat Framework with resources

Just use FatFrameworkTask from kotlin plugin .

Creating XCFramework with resources

Just use XCFramework from kotlin plugin .

But if you use static frameworks required additional setup - add to Xcode build phase (at end):

"$SRCROOT/../gradlew" -p "$SRCROOT/../" :shared:copyResourcesMultiPlatformLibraryReleaseXCFrameworkToApp \
    -Pmoko.resources.BUILT_PRODUCTS_DIR=$BUILT_PRODUCTS_DIR \
    -Pmoko.resources.CONTENTS_FOLDER_PATH=$CONTENTS_FOLDER_PATH

and add in your build.gradle config:

multiplatformResources {
    configureCopyXCFrameworkResources("MultiPlatformLibrary")
}

replace "MultiPlatformLibrary" with name that you use in XCFramework creation.

Details you can check in sample samples/ios-static-xcframework.

Usage

Example 1 - simple localization string

The first step is a create a file strings.xml in commonMain/moko-resources/base with the following content:

<?xml version="1.0" encoding="UTF-8" ?>
<resources>
    <string name="my_string">My default localization string</string>
</resources>

Next - create a file strings.xml with localized strings in commonMain/moko-resources/<languageCode>. Here's an example of creating commonMain/moko-resources/ru for a Russian localization:

<?xml version="1.0" encoding="UTF-8" ?>
<resources>
    <string name="my_string">Моя строка локализации по умолчанию</string>
</resources>

After adding the resources we can call a gradle sync or execute a gradle task generateMRcommonMain. This will generate a MR class containing MR.strings.my_string, which we can use in commonMain:

fun getMyString(): StringDesc {
    return StringDesc.Resource(MR.strings.my_string)
}

After this we can use our functions on the platform side:
Android:

val string = getMyString().toString(context = this)

iOS:

let string = getMyString().localized()

JS:

val strings = MR.stringsLoader.getOrLoad() // loading localization from a remote file
val string = getMyString().localized(strings)

Note: StringDesc is a multiple-source container for Strings: in StringDesc we can use a resource, plurals, formatted variants, or raw string. To convert StringDesc to String on Android call toString(context) (a context is required for the resources usage), on iOS - call localized().

Compose Multiplatform

with compose you can just call in commonMain

val string: String = stringResource(MR.strings.my_string)

MR directly from native side

Android:

val string = MR.strings.my_string.desc().toString(context = this)

iOS:

let string = MR.strings().my_string.desc().localized()

Get resourceId for Jetpack Compose / SwiftUI

Android:

val resId = MR.strings.my_string.resourceId

for example in Compose:

text = stringResource(id = MR.strings.email.resourceId)

iOS SwiftUI:

let resource = MR.strings().email
Text(
    LocalizedStringKey(resource.resourceId),
    bundle: resource.bundle
)

Note: more info in issue #126.

Example 2 - formatted localization string

In commonMain/moko-resources/base/strings.xml add:

<?xml version="1.0" encoding="UTF-8" ?>
<resources>
    <string name="my_string_formatted">My format \'%s\'</string>
</resources>

Then add the localized values for other languages like in example #1. Now create the following function in commonMain:

fun getMyFormatDesc(input: String): StringDesc {
    return StringDesc.ResourceFormatted(MR.strings.my_string_formatted, input)
}

To create formatted strings from resources you can also use extension format:

fun getMyFormatDesc(input: String): StringDesc {
    return MR.strings.my_string_formatted.format(input)
}

Now add support on the platform side like in example #1:
Android:

val string = getMyFormatDesc("hello").toString(context = this)

iOS:

let string = getMyFormatDesc(input: "hello").localized()

Warning: Do no mix positioned placeholders with unpositioned ones within a string, as this may lead to different behaviour on different platforms. Stick to one style for each string.

Example 3 - plural string

The first step is to create a file plurals.xml in commonMain/moko-resources/base with the following content:

Then add the localized values for other languages like in example #1.
Next, create a function in commonMain:

fun getMyPluralDesc(quantity: Int): StringDesc {
    return StringDesc.Plural(MR.plurals.my_plural, quantity)
}

Now add support on the platform side like in example #1:
Android:

val string = getMyPluralDesc(10).toString(context = this)

iOS:

let string = getMyPluralDesc(quantity: 10).localized()

Example 4 - plural formatted string

The first step is to create file plurals.xml in commonMain/moko-resources/base with the following content:

Then add the localized values for other languages like in example #1.
Next, create a function in commonMain:

fun getMyPluralFormattedDesc(quantity: Int): StringDesc {
    // we pass quantity as selector for correct plural string and for pass quantity as argument for formatting
    return StringDesc.PluralFormatted(MR.plurals.my_plural, quantity, quantity)
}

To create formatted plural strings from resources you can also use extension format:

fun getMyPluralFormattedDesc(quantity: Int): StringDesc {
    // we pass quantity as selector for correct plural string and for pass quantity as argument for formatting
    return MR.plurals.my_plural.format(quantity, quantity)
}

And like in example #1, add the platform-side support:
Android:

val string = getMyPluralFormattedDesc(10).toString(context = this)

iOS:

let string = getMyPluralFormattedDesc(quantity: 10).localized()

Compose:

With compose, you can simply use pluralStringResource

Text(
    text = pluralStringResource(
        MR.plurals.runtime_format,
        quantity,
        quantity
    )
)

Example 5 - pass raw string or resource

If we already use some resources as a placeholder value, we can use StringDesc to change the string source:

fun getUserName(user: User?): StringDesc {
    if (user != null) {
        return StringDesc.Raw(user.name)
    } else {
        return StringDesc.Resource(MR.strings.name_placeholder)
    }
}

And just like in example 1 usage on platform side:
Android:

val string1 = getUserName(user).toString(context = this) // we got name from User model
val string2 = getUserName(null).toString(context = this) // we got name_placeholder from resources

iOS:

let string1 = getUserName(user: user).localized() // we got name from User model
let string2 = getUserName(user: null).localized() // we got name_placeholder from resources

Example 6 - Select localization in runtime

You can force StringDesc to use preferred localization in common code:

StringDesc.localeType = StringDesc.LocaleType.Custom("es")

and return to system behaviour (when localization depends on device settings):

StringDesc.localeType = StringDesc.LocaleType.System

Android:

Add this to your app's build.gradle to keep all locales in resulting App Bundle if you want them all to be available in runtime (Otherwise, when the user downloads the app from PlayMarket, resources for his system locale only will be available).

android {
    bundle {
        language {
            enableSplit = false
        }
    }
}

Example 7 - Shared Images

Place images in the commonMain/moko-resources/images directory. Nested directories are also supported.

png and jpg

Image names should end with one of:

@0.75x - android ldpi;
@1x - android mdpi, ios 1x;
@1.5x - android hdpi;
@2x - android xhdpi, ios 2x;
@3x - android xxhdpi, ios 3x;

If we add the following files to commonMain/moko-resources/images:

home_black_18@1x.png
home_black_18@2x.png

Then we get an autogenerated MR.images.home_black_18 ImageResource in code. Usage:

Android: imageView.setImageResource(image.drawableResId)
iOS: imageView.image = image.toUIImage()

dark mode

To support Dark Mode images, you can add -dark and optionally -light to the name of an image. Make sure the rest of the name matches the corresponding light mode image:

car.svg
car-dark.svg

svg

The Image generator also supports svg files.

If we add the following file to commonMain/moko-resources/images:

car_black.svg

Then we get an autogenerated MR.images.car_black ImageResource in code. Usage:

Android: imageView.setImageResource(image.drawableResId)
iOS: imageView.image = image.toUIImage()

On Android it is a VectorDrawable,

On iOS iOS 13 or later it is a UIImage in the Assets catalog with preserves-vector-representation set to true.

images by name

You can get images by their name, too.

In commonMain create a Resources.kt file with the content below.

fun getImageByFileName(name: String): ImageResource {
    val fallbackImage = MR.images.transparent
    return MR.images.getImageByFileName(name) ?: fallbackImage
}

Usage:

Android: imageView.setImageResource(getImageByFileName("image_name"))
iOS: imageView.image = ResourcesKt.getImageByFileName(name: "image_name").toUIImage()!

Compose Multiplatform

With compose, you can simply use a painterResource in commonMain

val painter: Painter = painterResource(MR.images.home_black_18)

SwiftUI

For SwiftUI, create this Image extension:

extension Image {
    init(resource: KeyPath<MR.images, ImageResource>) {
        let imageResource = MR.images()[keyPath: resource]
        self.init(imageResource.assetImageName, bundle: imageResource.bundle)
    }
}

Then, you can refer to ImageResources directly by their key path, which provides compiler errors for typos or missing resources:

Image(resource: \.home_black_18)

Example 8 - pass font

Fonts resources directory is commonMain/moko-resources/fonts. Supported type of resources:

ttf
otf

If we add to commonMain/moko-resources/fonts files:

Raleway-Bold.ttf
Raleway-Regular.otf
Raleway-Italic.ttf

We got autogenerated:

MR.fonts.raleway_italic,
MR.fonts.raleway_regular,
MR.fonts.raleway_bold_italic

in code, that we can use:

Android: textView.typeface = font.getTypeface(context = this)
iOS: textView.font = font.uiFont(withSize: 14.0)

Compose Multiplatform

with compose you can just call in commonMain

val fontFamily: FontFamily = fontFamilyResource(MR.fonts.Raleway.italic)

or you can get Font

val font: Font = MR.fonts.Raleway.italic.asFont(
  weight = FontWeight.Normal, // optional
  style = FontStyle.Normal // optional
)

SwiftUI

For SwiftUI, create this Font extension:

extension Font {
    init(resource: KeyPath<MR.fonts, FontResource>, withSize: Double = 14.0) {
        self.init(MR.fonts()[keyPath: resource].uiFont(withSize: withSize))
    }
}

Then, you can refer to FontResources directly by their key path, which provides compiler errors for typos or missing resources:

 Text("Text displayed resource font")
   .font(Font(resource: \.raleway_regular, withSize: 14.0))

Example 9 - pass colors

Colors resources directory is commonMain/moko-resources/colors.
Colors files is xml with format:

If you want use one color without light/dark theme selection:


<color name="valueColor">#B02743FF</color>

If you want use value of other color - use references:


<color name="referenceColor">@color/valueColor</color>

If you want different colors in light/dark themes:


<color name="themedColor">
    <light>0xB92743FF</light>
    <dark>7CCFEEFF</dark>
</color>

Also themed colors can be referenced too:


<color name="themedReferenceColor">
    <light>@color/valueColor</light>
    <dark>@color/referenceColor</dark>
</color>

Colors available in common code insode MR.colors.** as ColorResource.
ColorResource can be read from platform side:

android:

val color: Int = MR.colors.valueColor.getColor(context = this)

iOS:

val color: UIColor = MR.colors.valueColor.getUIColor()

macOS:

val color: NSColor = MR.colors.valueColor.getNSColor()

jvm:

val light: Color = MR.colors.valueColor.lightColor
val dark: Color = MR.colors.valueColor.darkColor

web:

val light: Color = MR.colors.valueColor.lightColor
val dark: Color = MR.colors.valueColor.darkColor

Compose Multiplatform

with compose you can just call in commonMain

val color: Color = colorResource(MR.colors.valueColor)

Example 10 - plain file resource access

The first step is a create a resource file test.txt for example, in commonMain/moko-resources/files After gradle sync we can get file by id MR.files.test Moko-resources has out of box implementation function for read text files from common code - readText()

Usage on Android:

val text = MR.files.test.getText(context = this)

Usage on Apple:

val text = MR.files.test.readText()

If you want to read files not as text, add your own implementation to expect/actual FileResource

Compose Multiplatform

with compose you can just call in commonMain

val fileContent: String? by MR.files.test.readTextAsState()

Example 11 - assets access

Assets allow you save directories hierarchy (in files structure is plain). Locate files to commonMain/moko-resources/assets and access to it by MR.assets.*

Compose Multiplatform

with compose you can just call in commonMain

val assetContent: String? by MR.assets.test.readTextAsState()

Known issues

iOS shows key instead of localized text

Samples

In samples directory you can find multiple projects showed different usages.

Set Up Locally

In root of repository contains moko-resources gradle project - libraries and gradle plugin. You can just open project in IDE and develop. Then for tests in samples you should run run ./gradlew publishToMavenLocal gradle task. After this you can open any sample from samples in IDE and test your local version of moko-resources.

To check your changes before pull request run:

# check lib & plugin
./local-check.sh
# check samples
./local-samples-check.sh

Contributing

All development (both new features and bug fixes) is performed in the develop branch. This way master always contains the sources of the most recently released version. Please send PRs with bug fixes to the develop branch. Documentation fixes in the markdown files are an exception to this rule. They are updated directly in master.

The develop branch is pushed to master on release.

For more details on contributing please see the contributing guide.

License

Copyright 2019 IceRock MAG Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance  the License.
You may obtain a copy of the License at

   http:

Unless   applicable law  agreed to  writing, software
distributed under the License  distributed  an  BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express  implied.
See the License  the specific language governing permissions 
limitations under the License.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

libres★ 221

skeptickGenerates and manages resources such as strings and images, supporting various formats and localization options. Integrates with Jetpack Compose, handles platform-specific image processing, and ensures seamless resource access across platforms.Shared: resources

kotlinx-resources★ 143

goncalossilvaPlugin and library facilitate reading test resources using a unified API. Provides `Resource` class for checking existence, reading text, and reading bytes from designated resource folders.Shared: resources

Atlas★ 43

Ares-Defence-LabsComprehensive SDK enables development of scalable, maintainable applications by integrating MVVM architecture, navigation, CLI tools, and IoC container. Features include compile-time dependency injection and resource generation.Shared: resources

kmp-flagkit★ 38

acarlsenOffers ImageVector format flag icons for easy integration in projects, inspired by existing flag libraries. Supports referencing by Alpha-2 country codes and includes additional regional flags.Shared: resources

coil-resvg★ 33

hash-sequenceSVG decoder for Coil, rendering vector images to pixel-perfect bitmaps via resvg Rust FFI, with system font support, consistent rendering and no browser dependency.Shared: resources

compose-phosphor-icon★ 29

adamglin0Enables seamless integration of Phosphor Icons into UI projects, offering a script for generating icon paths and supporting multiple platforms including Android, iOS, Desktop, and Web.Shared: resources

moko-resources

Mobile Kotlin resources

Table of Contents

Features

Requirements

Installation

Gradle setup

Custom resource sourceSet

Export classes to Swift

Multi-module Gradle projects

Android Host Tests (Unit Tests)

Xcode setup

Android build types

JS Webpack

iOS/macOS static kotlin frameworks support

With org.jetbrains.kotlin.native.cocoapods

Without org.jetbrains.kotlin.native.cocoapods

Disable warning about static framework usage

iOS executable

Creating Fat Framework with resources

Creating XCFramework with resources

Usage

Example 1 - simple localization string

Compose Multiplatform

MR directly from native side

Get resourceId for Jetpack Compose / SwiftUI

Example 2 - formatted localization string

Example 3 - plural string

Example 4 - plural formatted string

Example 5 - pass raw string or resource

Example 6 - Select localization in runtime

Example 7 - Shared Images

png and jpg

dark mode

svg

images by name

Compose Multiplatform

SwiftUI

Example 8 - pass font

Compose Multiplatform

SwiftUI

Example 9 - pass colors

Compose Multiplatform

Example 10 - plain file resource access

Compose Multiplatform

Example 11 - assets access

Compose Multiplatform

Known issues

iOS shows key instead of localized text

Samples

Set Up Locally

Contributing

License

Related libraries

Mobile Kotlin resources

Table of Contents

Features

Requirements

Installation

Gradle setup

Custom resource sourceSet

Export classes to Swift

Multi-module Gradle projects

Android Host Tests (Unit Tests)

Xcode setup

Android build types

JS Webpack

iOS/macOS static kotlin frameworks support

With org.jetbrains.kotlin.native.cocoapods

Without org.jetbrains.kotlin.native.cocoapods

Disable warning about static framework usage

iOS executable

Creating Fat Framework with resources

Creating XCFramework with resources

Usage

Example 1 - simple localization string

Compose Multiplatform

MR directly from native side

Get resourceId for Jetpack Compose / SwiftUI

Example 2 - formatted localization string