Web to Mobile conversion

What is platform conversion?

Emergent lets you convert a web app to mobile through a preview-panel toggle. When you convert, the platform forks your project into a new job and rebuilds the mobile side using Expo/React Native, translating UI frameworks, layout patterns, navigation, and platform-specific idioms, while sharing the same backend between both platforms.

Info

Web → mobile conversion forks your project into a new job where both the web and mobile apps share the same backend, managed in one project. Mobile → web conversion is not supported, if you need a web version of a mobile-only project, you will need to rebuild.

Warning

Web → mobile conversion is a feature-flagged capability still rolling out. It does not support Next.js projects.

When to add a mobile app

Validated web MVP: you've validated a web MVP and want native distribution through app stores, without rebuilding or duplicating your backend.
Expanding platform reach: you need a native mobile presence alongside your existing web app, managed in one project.

How conversion works

Find the conversion toggle in the preview panel

Open your web app's preview panel. If web → mobile conversion is available for your project, you will see an option to Add Mobile App (or a platform toggle). This is not in a Publish dropdown, look in the preview panel directly.

The platform forks a new job

Emergent creates a new forked job. Both the web and mobile sides share the same backend going forward. The mobile side is built as an Expo/React Native app.

Agent rebuilds the UI for mobile

A conversion job runs, rewriting components, restructuring navigation, swapping frameworks (React web → React Native), and adjusting layout for the mobile form factor.

Review and test the converted app

The converted app opens in preview mode. Use the embedded preview, Expo Go QR code, or cloud device streaming to test on device. Test thoroughly before publishing live.

Publish when satisfied

When everything works, use the Publish button to publish. If issues arise, iterate in chat or continue refining in the preview.

Conversion is a Job

Like any build task, conversion runs as a job and consumes credits. You can watch progress, pause, or cancel if needed.

What happens to my data and settings during conversion?

Because web → mobile conversion forks into a new job, you should not assume automatic carry-over of data, environment variables, sessions, or uploaded files. Review each of the following carefully after conversion:

Database schema and data: Verify that data is accessible in the new forked job, carry-over is not guaranteed.
Environment variables and secrets: Check that any env vars or secrets you rely on are present in the new job, they are not automatically transferred.
Authentication and user sessions: Login flows and user sessions should be re-tested end-to-end after conversion.
Uploaded files and assets: Uploaded assets should be verified as accessible from the new job context. Note that deletion of uploaded assets is not currently supported (uploads are permanent).

Note

The agent rebuilds the UI and navigation for mobile while the backend is shared. Business logic and API routes continue working through the shared backend, but always verify after a fork.

What’s shared vs. what’s separate

Component	Behavior
Database & collections	Shared, both platforms use the same MongoDB instance; schema and data are common
Backend / API	Shared, both platforms share the same backend; it is not regenerated or duplicated
User accounts & auth	Shared, login works across both platforms
Environment variables	Shared, API keys and secrets are common to both
UI components	Separate, the mobile UI is built in Expo/React Native; the web UI remains as-is
Published app	Independent, each platform is published separately, but managed within one project
Third-party integrations	Reviewed, some integrations differ by platform (e.g., Stripe and Paystack are hidden on Expo projects; Razorpay and PayPal remain)

What adapts during web → mobile conversion

Rebuilt automatically

UI components: buttons, forms, modals, and lists rebuild using React Native patterns (e.g. web
```
<button>
```
→
```
<Pressable>
```
).
Navigation: URL-based web routing converts to mobile navigation stacks and tabs.
Responsive layout: desktop/web layouts condense to mobile-friendly single-column or tabbed views.
Form inputs: HTML5 inputs map to appropriate mobile keyboard types and pickers.

What may require adjustment

Platform-specific features need review

Capabilities unique to the web platform, browser APIs, OS-level integrations, may not translate directly to mobile. Test these carefully after conversion.

Feature	Web → Mobile notes
Camera/microphone	Native mobile APIs available; permission prompts may need adding
Push notifications	Needs mobile push service (FCM/APNs) configured
Geolocation	Native mobile APIs are faster/more reliable
File system access	Mobile uses app-sandboxed storage
Print/PDF export	Not a standard mobile pattern; may need redesign
Right-click menus	Replaced with touch-and-hold patterns
Hover states	Touch doesn't have hover; replaced with press/active states

Info

If your app relies heavily on a specific feature, mention it explicitly in chat during conversion: "Keep the QR scanner working on mobile" or "Preserve the file export button."

Common conversion scenarios

If web → mobile conversion is available for your project (and it is not a Next.js project), yes. Multi-column layouts will condense to scrollable single-column or tabbed views. Charts and tables adapt to smaller screens, the agent may introduce horizontal scroll for wide tables or summary cards for dense data.

Mobile → web conversion is not supported. If you need a web version of a mobile-only project, you will need to start a new web project and rebuild.

Because conversion forks into a new job, you should check your environment variables after conversion and re-enter any that are missing. Do not paste secrets into chat, use the Secrets panel (Preview → Manage → Secrets) or ask the agent to add them to

.env

, then re-publish.

Your original web project is unaffected, conversion creates a new forked job. You can continue working on the original. There is no automated rollback of the conversion itself.

Best practices for smooth conversion

Test on real devices: Use Expo Go or cloud device streaming to test on real iOS/Android devices, simulators catch some but not all platform quirks.
Check authentication flows: Login, signup, and OAuth redirects must work on mobile.
Review navigation: Make sure every screen is reachable and back/close buttons behave correctly.
Verify data access: Confirm your app can read and write data as expected after the fork.
Test edge cases: Empty states, long text, and landscape orientation on mobile.

Tip

After conversion, open the app in preview and click through every major user flow. If something feels off, describe the issue in chat, the agent can fine-tune layout, navigation, or component behavior.