> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Native builds and packages

> What a native build is, what makes one happen, how long it takes and which packages are already installed.

In Newly v2, at app.newly.app and in Newly for Mac, the cloud simulators normally run a development build of your own app, with your app's native code inside it. Newly makes these builds for you in the cloud. You don't need an Expo account or EAS.

Most changes don't need a new build. This page explains when one happens and what to do if it fails.

## Packages that are already installed

New projects start from a prepared base that already includes many native packages. Examples:

* video and audio
* SQLite
* secure storage
* Skia (drawing and graphics)
* Reanimated (animations)
* bottom sheets
* MMKV (fast key-value storage)

The agent can use these without a native build. Because new projects start from this prepared base, the first preview is often ready quickly.

## What triggers a native build

Your app is built again when its native part changes:

* **Adding a native package** that isn't already installed.
* **Changing `app.json`** in almost any way: the bundle ID, Android package name, version, icon, orientation, plugins, permissions or URL scheme.

Changing only the app's display name doesn't need a new build. For more about names, icons and versions, see [App name, icon, bundle ID and version](/publish/app-identity).

When you ask for a change like this, the agent should tell you that the next preview will take several minutes to build.

JavaScript changes, such as screens, styles and logic, don't need a build. They usually reach your simulator within seconds, or when the agent finishes its turn.

## iOS and Android together

When the agent builds, it builds for both iOS and Android, whichever platform you're looking at. If nothing native has changed since the last build, it reuses that build instead of making a new one.

When a new build is ready while your simulator is running, you see "The agent changed native code. Update to install the new build." Press **Update**. See [Using the cloud simulators](/preview/simulators).

## How long a build takes

The simulator card shows how long the build has been running. While the agent builds, its progress in the chat includes an estimate of the time left, for example "Building the app - less than a minute left". The estimate is based on recent builds. If a build runs past it, the progress reads "Building the app - taking longer than usual".

Android builds may wait for a free build worker first: "Waiting for an available Android build worker. Your build will start automatically."

## When a build fails

If a build fails, the simulator card shows "Couldn't build your app".

<Steps>
  <Step title="Let the agent try first">
    The agent looks at the build error itself and tries to fix it. You may see "The app build hit a problem. I’m fixing it and retrying automatically." If the same failure happens 3 times in a row, the agent stops and tells you what's wrong instead of retrying forever. If you stopped the agent, it doesn't start a fix on its own.
  </Step>

  <Step title="Build again">
    Press **Build again** on the simulator card to start a new build.
  </Step>

  <Step title="Tell the agent what you saw">
    If it still fails, describe the problem in the chat. Mention the package or setting you changed last.
  </Step>
</Steps>

**In Newly for Mac:** in Remote chats, open **App Logs** at the bottom-right of the preview pane and choose the **Native Build** tab to see the build output.

If you contact support and a failure card in the chat has a **Copy debug info** button, copy it and include the result. See [Getting help](/help/getting-help).

## Builds and credits

Native builds don't draw down credits. The agent's work in the chat does, including the turns where it fixes a failed build automatically. See [How credits work](/billing/how-credits-work).

## Preview builds stay in the cloud

Preview builds install only on Newly's cloud simulators. You can't download them or install them on a phone. To try your iOS app on an iPhone, use TestFlight. See [Testing on a real phone](/preview/test-on-a-phone).

## Related

<CardGroup cols={2}>
  <Card title="Using the cloud simulators" icon="mobile-screen" href="/preview/simulators">
    Card states, updates and controls.
  </Card>

  <Card title="App name, icon, bundle ID and version" icon="id-card" href="/publish/app-identity">
    Settings that change your native build.
  </Card>

  <Card title="Testing on a real phone" icon="mobile" href="/preview/test-on-a-phone">
    Get your app onto an iPhone.
  </Card>

  <Card title="Messages explained" icon="message" href="/help/messages">
    What build and preview messages mean.
  </Card>
</CardGroup>