From Hybrid to Native: Handling Web App Assets During Migration

You’ve made the decision. The hybrid wrapper served its purpose, but now you’re going native. The architecture is mapped out, the team is aligned, and the sprint planning is done. Then someone asks: “What about all the assets?” That question stops developers cold more often than it should, and the reason is simple: asset migration looks manageable until you’re actually doing it.

Config files, icons, splash screens, manifest data, fonts, and static resources all carry assumptions baked in from your web or hybrid context. Those assumptions do not travel cleanly into a native build. This article walks through the practical steps of getting your assets sorted, adapted, and properly placed before you close the door on your hybrid setup for good.

Why Asset Migration Catches Developers Off Guard

Most migration guides focus on the code. That makes sense. Logic, state management, API calls, and navigation patterns take up the bulk of the work and carry the most visible risk. But assets create silent failures. An icon that ships at the wrong resolution, a splash screen that flickers or crops badly on a specific device, a missing font that falls back to a system default and throws off your entire design. These problems surface at the worst possible time, usually right before a release deadline.

The deeper issue is that hybrid frameworks abstract a lot of the asset pipeline for you. Cordova, Capacitor, Ionic, and React Native each have their own conventions for handling assets, and those conventions do not match what Xcode or Android Studio expect. When you pull those assets out of their original context, the abstractions disappear. You’re left with raw files that need to be reorganized and, in some cases, regenerated entirely.

This is not a reason to panic. It is a reason to plan. The more methodical you are about the audit phase, the fewer surprises you get later in the process.

Taking Stock of Everything You Have Before Touching a File

Before you move, delete, or convert anything, do a full inventory. Open your hybrid project and list every non-code asset: images, icons, splash screens, fonts, JSON config files, environment files, and anything else that ships with the build. Include files that feel obvious, because obvious files are the ones that get overlooked.

For each asset, note three things. Its current format and resolution. Where it is referenced in the codebase. Whether it was auto-generated by a tool or manually created. Auto-generated assets often have a source file somewhere, which makes regeneration easier. Manually created assets may need to be rebuilt from scratch if the source files are missing.

This inventory doesn’t have to be elaborate. A plain spreadsheet or a markdown file works fine. The goal is to have a complete picture before you start making changes, not to build a documentation system.

Updating Your App’s Identity Layer

The identity layer is the collection of assets and metadata that define how your app presents itself to the operating system and to users. It includes your app icon, splash screen, display name, bundle identifier, and the metadata that describes your app’s capabilities and permissions. Getting this right early matters because these values feed directly into Xcode target configuration and Android build variants.

Icons and Splash Screens for Each Platform

Native iOS and Android builds require icons at specific sizes, in specific formats, placed in specific directories. iOS expects a full set of PNG assets ranging from 20×20 all the way up to 1024×1024, organized in an asset catalog. Android requires adaptive icon support starting from API level 26, which means a foreground layer, a background layer, and a legacy fallback.

Your hybrid project probably had a single high-resolution icon that a framework tool resized automatically during the build. In a native project, you handle this yourself. Export your icon from its original source at the highest available resolution, then use a platform-specific tool or a service that produces all required sizes from that master file. The same logic applies to splash screens, though the complexity scales up because splash screen behavior differs between iOS and Android.

On iOS, newer apps use the UILaunchScreen keys in Info.plist rather than a storyboard. On Android, the recommended approach uses the SplashScreen API introduced in API 31, with a theme-based fallback for older devices. Neither of these patterns has a direct equivalent in most hybrid frameworks, so you’re building them from scratch.

Manifest Files and App Metadata

In a web or hybrid project, your app’s metadata often lives in a manifest.json file. This file defines properties like the app’s name, short name, theme color, background color, icons list, and display mode. It was designed for Progressive Web Apps and browser-based install experiences.

When you’re migrating, this file gives you a useful reference point. The field values inside it represent decisions you’ve already made about your app’s identity. Before you adapt or strip those values for native use, running them through a web app manifest generator lets you validate that the structure is correct and gives you a clean, spec-compliant baseline to work from. That baseline becomes your checklist as you translate each field into native config.

Once you have a valid manifest, the actual task is translating its fields into native formats. On Android, metadata like your app name and theme color goes into strings.xml and styles.xml inside your res directory. On iOS, the equivalent lives in Info.plist. The fields don’t map one-to-one, but they’re close enough that the manifest acts as a reliable starting point. The Web App Manifest specification from W3C is worth bookmarking during this phase, because it defines exactly what each field means and helps you decide which properties have a meaningful native counterpart and which can be dropped entirely.

How Web Manifest Fields Map to Native Metadata

Web Manifest Properties and Their Platform-Specific Counterparts

Manifest Field	iOS Native Equivalent	Android Native Equivalent
name	CFBundleDisplayName in Info.plist	android:label in AndroidManifest.xml
short_name	CFBundleName in Info.plist	app_name in strings.xml
theme_color	NavigationBar tint (UIKit) or toolbar color (SwiftUI)	colorPrimary in themes.xml
background_color	LaunchScreen background color	windowBackground in styles.xml
icons	AppIcon asset catalog in Assets.xcassets	mipmap directories in res/
display	Not directly applicable (full screen is the default)	Not directly applicable (full screen is the default)
start_url	Not applicable in native builds	Not applicable in native builds

Config Files, Environment Variables, and Build Settings

Config files are a common source of confusion during migration. Hybrid projects often use .env files, config.xml, or framework-specific config formats to manage build-time settings, API endpoints, and feature flags. None of these translate directly into a native project.

On iOS, build configuration lives in .xcconfig files and the project’s build settings inside Xcode. On Android, configuration goes into build.gradle and gradle.properties, with secrets sometimes managed through a local properties file that stays out of version control. Both platforms support build variants or schemes that let you manage development, staging, and production differences cleanly.

Go through your existing config files field by field. Ask which values are genuinely needed at the native layer, which ones were only relevant for the web renderer, and which ones belong in a separate backend or secrets management system. This is a good time to clean up configuration debt that accumulated during the hybrid phase.

Static Assets, Fonts, and the Path Problem

Static assets in a hybrid project are often served through a local web server running inside the WebView. Paths are written as URL strings, often starting with /assets/ or a similar web-style prefix. Those paths mean nothing in a native context.

In native builds, assets are bundled and accessed differently across platforms:

• On iOS, assets go into the app bundle and are accessed through Bundle.main.url(forResource:withExtension:) in Swift or equivalent Objective-C methods.
• On Android, assets placed in the assets/ directory are accessed through AssetManager, while drawable resources live in the res/drawable directories.
• Custom fonts on iOS are declared in Info.plist under UIAppFonts and placed inside the app bundle. On Android, fonts live in res/font/ and are referenced in XML layouts or via the Fonts API.
• Any asset referenced by a hardcoded URL string in your hybrid code needs to be located and updated to use the platform’s native asset loading mechanism.

Search your codebase for string patterns like /assets/, ./img/, and similar path prefixes before you finalize the migration. These are the references most likely to break silently at runtime rather than throwing a visible error at build time. A thorough grep pass at this stage saves hours of debugging later.

Your Assets Are the Foundation, Not the Finishing Touch

There’s a temptation to treat asset migration as the last item on the checklist, the part you handle once everything else is working. That approach creates more work, not less. When your icons aren’t in place, you can’t do a proper device test. When your config files aren’t migrated, you can’t connect to real APIs. When your fonts are missing, your UI looks broken even if the logic is perfect.

Treat asset migration as a first-class part of the project. Run the inventory before the code rewrite starts. Handle the identity layer early, because icons and splash screens affect how you configure Xcode targets and Android build variants. Get your config files sorted before you write environment-specific logic. Deal with static asset paths as you migrate each screen, not all at once at the end.

Migration projects succeed or fail on details. The asset layer is full of them. Give it the attention it deserves from the start, and the rest of the process becomes noticeably cleaner.