# CLI
Source: https://docs.newly.app/advanced/cli

Develop, provision, and deploy your Newly backend from the terminal

The `newly` CLI lets you pull your project's backend code, deploy it, and manage logs, secrets, and the database from your terminal.

<Note>
  The CLI works with **Liquid Backend** projects. Run `newly stack` to check if a project is supported.
</Note>

## Install

```bash theme={null}
npm i -g @newly/cli
```

Requires **Node ≥ 20**.

## Quick start

```bash theme={null}
newly login              # authenticate in the browser
newly pull <project-id>  # download project code + link this directory
# edit code…
newly deploy             # deploy to dev
newly deploy --env prod  # ship to prod
```

## Auth

```bash theme={null}
newly login          # opens a browser, stores a session token in ~/.newly/credentials
newly login --manual # paste the credential instead of using the browser callback
newly logout         # delete stored credentials
```

Re-run `newly login` when a command reports your session has expired.

## Project linking

Commands target the project linked to the current directory, so you don't pass `--project` every time.

* `newly pull <project-id>` and `newly create` link automatically.
* `newly link <project-id>` links a directory without downloading code.
* Pass `--project <id>` to any command to override the link.

## Dev vs prod deploys

|                           | Source                   | Notes                                                                                                                     |
| ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `newly deploy` (dev)      | **Your local code**      | Fast inner loop. Ephemeral — overwritten the next time the project is built on the Newly platform. Not a rollback target. |
| `newly deploy --env prod` | **Project code at HEAD** | Runs server-side, ignores local edits. Push your changes into the project first.                                          |

<Warning>
  `newly deploy --env prod` deploys the project's committed code, **not** your local files. Push your changes into the project before deploying to prod.
</Warning>

Prod actions prompt for confirmation. Pass `--yes` to skip it in scripts.

## Commands

### `newly pull [project-id]`

Download the project code into the current directory and link it.

| Option            | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `--branch <name>` | Pull a specific branch (default: the project's active branch). |
| `--force`         | Overwrite a non-empty directory (discards local changes).      |

### `newly create [name]`

Create a project, provision its production database, scaffold `backend/`, select
production, and deploy the starter backend. Run this in a directory with no
`backend/` and no existing project link.

| Option        | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `--no-deploy` | Provision and select production without deploying the starter backend. |

Production starts with 2 GiB of storage.

### `newly link <project-id>`

Link the current directory to a project without downloading code.

### `newly status`

Show dev and prod status, service URLs, deployed SHA, and last error. Accepts `--project <id>`.

### `newly stack`

Show which backend stack the project uses and whether it's CLI-deployable. Accepts `--project <id>`.

### `newly up`

Provision the backend (if needed) and deploy.

| Option              | Default       | Description                        |
| ------------------- | ------------- | ---------------------------------- |
| `--env <dev\|prod>` | `dev`         | Target environment.                |
| `--region <region>` | `us-central1` | GCP region for dev provisioning.   |
| `--project <id>`    | linked dir    | Target project.                    |
| `--yes`             | —             | Skip the prod confirmation prompt. |

### `newly deploy`

Deploy the backend.

| Option              | Default    | Description                        |
| ------------------- | ---------- | ---------------------------------- |
| `--env <dev\|prod>` | `dev`      | Target environment.                |
| `--project <id>`    | linked dir | Target project.                    |
| `--yes`             | —          | Skip the prod confirmation prompt. |

### `newly logs`

Tail backend service logs. **Dev only.**

| Option                          | Default    | Description                              |
| ------------------------------- | ---------- | ---------------------------------------- |
| `--service <api\|auth>`         | `api`      | Service to tail.                         |
| `-n, --lines <n>`               | `200`      | Number of lines.                         |
| `--since <duration>`            | —          | Relative window, e.g. `30s`, `5m`, `2h`. |
| `--start <iso>` / `--end <iso>` | —          | Absolute window (ISO 8601).              |
| `--project <id>`                | linked dir | Target project.                          |

### `newly secrets list`

List the secret keys set for a service (names only). **Dev only.** Accepts `--service <api|auth>` (default `api`) and `--project <id>`.

### `newly secrets set <key> <value>`

Set a backend secret. **Dev only.** Redeploy to apply. Accepts `--service <api|auth>` (default `api`) and `--project <id>`.

### `newly db url`

Print a readonly Postgres URL for the backend database. **Dev only.** Accepts `--project <id>`.

## Files

| Path                   | Purpose                                                               |
| ---------------------- | --------------------------------------------------------------------- |
| `~/.newly/credentials` | Session token (mode `600`). Override the directory with `NEWLY_HOME`. |
| `.newly/project.json`  | Per-directory project link.                                           |


# Secrets / Environment Variables
Source: https://docs.newly.app/advanced/environment-variables

Manage secrets and configuration for your app

Secrets / Environment variables let you store configuration and secrets that your app needs, without showing them to other people, just like your personal passwords.

## When to Use Secrets / Environment Variables

<CardGroup>
  <Card title="API Keys" icon="key">
    Third-party service credentials
  </Card>

  <Card title="Configuration" icon="sliders">
    Feature flags, URLs, settings
  </Card>

  <Card title="Secrets" icon="lock">
    Sensitive data that shouldn't be in code
  </Card>

  <Card title="Environment-Specific" icon="server">
    Different values for dev/staging/prod
  </Card>
</CardGroup>

### In AI Prompts

Tell the AI to use secrets / environment variables but **never add the secret to the prompt**:

**Bad example:**

```
Add weather data to the home screen, Here's the Openweather secret: nsadf98dsafjdsajnfiu
```

**Good example:**

Before prompting, we add OPENWEATHER\_API\_KEY to the backend as a secret. The name of the secret is OPENWEATHER\_API\_KEY.

```
Add weather data to the home screen. Use the OPENWEATHER_API_KEY
environment variable for the API key.
```

## Secrets / Environment Variables by Backend Type

How you manage environment variables depends on which backend system you're using.

<Note>
  **Which backend am I using?** If you see a "Database" button in the preview header, you're on Liquid Backend. Otherwise, you're using Supabase. See [Backend Systems](/features/backend).
</Note>

## Liquid Backend

With Liquid Backend, environment variables are split between frontend and backend:

### Frontend Variables

For variables used in your React Native code:

<Steps>
  <Step title="Open Settings">
    Click \*\*Database \*\*and go to **Secrets** in the project menu
  </Step>

  <Step title="Add Variable">
    Enter the variable name and value:

    * Name: `GOOGLE_MAPS_API_KEY`
    * Value: `your_api_key_here`
  </Step>

  <Step title="Save">
    Click Save to store the variable, it is now accesible by the backend services.
  </Step>
</Steps>

## Supabase Environment Variables

### Supabase

Supabase credentials are managed through OAuth:

<Steps>
  <Step title="After connecting Supabase">
    Click **More** → \*\*Environment Variables \*\*and add your secrets.
  </Step>

  <Step title="Example">
    Add name **OPENAI\_API\_KEY** and value \*\*sk-... \*\*and save.
  </Step>
</Steps>

## Using Public Secrets / Environment Variables in Frontend

### Accessing Variables

All frontend environment variables are specified in **app.json** and accessed the same way:

```tsx theme={null}
import Constants from 'expo-constants';

// Access any environment variable
const apiKey = Constants.expoConfig?.extra?.MY_API_KEY;
const baseUrl = Constants.expoConfig?.extra?.API_BASE_URL;
```

### With Default Values

```tsx theme={null}
const apiUrl = Constants.expoConfig?.extra?.API_URL ?? 'https://api.example.com';
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Never hardcode secrets">
    API keys, passwords, and tokens should always be in environment variables, not in your code.
  </Accordion>

  <Accordion title="Use descriptive names">
    Use clear names like `STRIPE_PUBLIC_KEY` instead of `KEY1`
  </Accordion>

  <Accordion title="Separate frontend and backend secrets">
    Only public keys belong in frontend environment variables. Server-side secrets go in your backend.
  </Accordion>

  <Accordion title="Document required variables">
    Keep track of which environment variables your app needs for deployment.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Variable returns undefined">
    * Check the variable name matches exactly (case-sensitive)
    * Ensure you saved after adding the variable
    * Reload the preview after changes
  </Accordion>

  <Accordion title="API key not working">
    * Verify the key is correct (copy-paste from source)
    * Check if the key has proper permissions/scopes
  </Accordion>

  <Accordion title="Secret exposed in code">
    * If its not a "public secret", contact support in Newly
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Backend Systems" icon="server" href="/features/backend">
    Understand Liquid Backend vs Supabase
  </Card>

  <Card title="Supabase Integration" icon="database" href="/integrations/supabase">
    Full Supabase setup guide
  </Card>
</CardGroup>


# Exporting Code
Source: https://docs.newly.app/advanced/exporting-code

Download and work with your code outside Newly

# Exporting Code

You own 100% of the code generated by Newly. Export it anytime to work locally, hand off to developers, or host elsewhere.

## Export Options

<CardGroup>
  <Card title="GitHub Sync" icon="github">
    Automatic sync to your repository
  </Card>

  <Card title="Download ZIP" icon="file-zipper">
    Download complete source code
  </Card>
</CardGroup>

## Downloading as ZIP

<Steps>
  <Step title="Open Menu">
    Click **More** in the project header
  </Step>

  <Step title="Download">
    Click **Download ZIP**
  </Step>

  <Step title="Extract">
    Extract the ZIP file to your preferred location
  </Step>
</Steps>

## Running Locally

<Steps>
  <Step title="Install Node.js">
    Ensure you have Node.js 18+ installed
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    cd my-app
    pnpm install
    ```
  </Step>

  <Step title="Start Expo">
    ```bash theme={null}
    pnpx expo start
    ```
  </Step>

  <Step title="Run on Device">
    * Scan QR code with Expo Go
    * Or press `i` for iOS Simulator
    * Or press `a` for Android Emulator
  </Step>
</Steps>

## Local Development Requirements

| Requirement | Version           |
| ----------- | ----------------- |
| Node.js     | 18 or higher      |
| npm         | 9 or higher       |
| Expo CLI    | Latest (via pnpx) |

### For iOS Development (Mac only)

* Xcode 15+
* iOS Simulator

### For Android Development

* Android Studio
* Android Emulator or physical device

## Customizing Exported Code

The exported code is standard React Native/Expo. You can:

<AccordionGroup>
  <Accordion title="Add native modules">
    Install and configure native packages that require additional setup
  </Accordion>

  <Accordion title="Modify build configuration">
    Customize app.json, eas.json, and native configuration
  </Accordion>

  <Accordion title="Integrate with CI/CD">
    Set up automated builds and deployments
  </Accordion>

  <Accordion title="Hand off to developers">
    Share with your development team for further work
  </Accordion>
</AccordionGroup>

## Backend Considerations

If your app uses Liquid Backend:

<Warning>
  The backend runs on Newly's infrastructure. To fully self-host, you'll need to migrate the backend to your own infrastructure.
</Warning>

### Options for Backend

1. **Keep using Newly** - Your Liquid Backend continues working
2. **Build custom backend** - Create your own API using the generated code as reference

## Maintaining After Export

If you continue development outside Newly:

<CardGroup>
  <Card title="Keep Dependencies Updated" icon="arrow-rotate-right">
    Regularly update Expo SDK and packages
  </Card>

  <Card title="Follow React Native Best Practices" icon="book">
    Learn from the generated code patterns
  </Card>

  <Card title="Monitor for Issues" icon="eye">
    Set up error tracking (Sentry, etc.)
  </Card>

  <Card title="Test on Devices" icon="mobile">
    Always test on real devices before releasing
  </Card>
</CardGroup>

## Re-importing to Newly

Currently, importing external changes back into Newly is supported via GitHub sync:

1. Connect GitHub to your Newly project
2. Push changes from your local development to created repo
3. Changes sync to Newly on next project open

<Note>
  Major structural changes made outside Newly may affect how well the AI can assist with future changes.
</Note>


# Version Control
Source: https://docs.newly.app/advanced/version-control

Track changes and revert to previous versions

# Version Control

Every change in your Newly project is saved, giving you full version history and the ability to revert if needed.

## How It Works

Each time the AI makes changes to your code:

1. **Changes are made** - Files are created or modified
2. **Build completes** - App compiles successfully
3. **Commit created** - Changes are saved with a descriptive message
4. **Preview updates** - You see the result immediately

## Reverting Changes

If something breaks, you can revert to a previous version:

<Steps>
  <Step title="Open History">
    Navigate to the version history panel
  </Step>

  <Step title="Find Working Version">
    Look for the last commit where everything worked
  </Step>

  <Step title="Revert">
    Click the revert button on that commit
  </Step>

  <Step title="Confirm">
    Your project is restored to that state
  </Step>
</Steps>

## GitHub Sync

With GitHub connected, your version history is also:

* **Backed up** to your repository
* **Accessible** via standard Git tools
* **Shareable** with collaborators

<Card title="GitHub Integration" icon="github" href="/integrations/github">
  Learn about GitHub sync
</Card>

## Best Practices

<CardGroup>
  <Card title="Test Before Moving On" icon="vial">
    Verify each change works before making more
  </Card>

  <Card title="Note Important Versions" icon="bookmark">
    Remember which commits represent major milestones
  </Card>

  <Card title="Revert Early" icon="clock-rotate-left">
    If something breaks, revert quickly rather than trying to fix forward
  </Card>

  <Card title="Read Commit Messages" icon="message">
    The AI's commit messages describe what changed
  </Card>
</CardGroup>

## Understanding Changes

### What Gets Committed

* Source code changes
* New files and assets
* Configuration updates
* Package dependency changes

### What Doesn't Get Committed

* Chat history (stored separately)
* Environment variables (stored securely)
* Build artifacts (regenerated each time)


# Changelog
Source: https://docs.newly.app/changelog/2026-03-30

Latest updates and improvements to Newly

<Update label="March 30, 2026" description="Visual Editor, Ask mode, Android push notifications, and more">
  ## New features

  * **Visual Editor** — Select and edit elements directly in the preview. Change text, colors, spacing, fonts, icons, and images without writing code. You can also make AI-powered edits by describing what you want to change in natural language. [Learn more](/features/preview)

  * **Ask mode in AI chat** — A new "Ask" mode joins Build and Plan in the chat mode selector. Use it to ask questions about your codebase, get explanations, or look things up — without triggering any code changes. [Learn more](/features/ai-chat)

  * **Google Play account connection** — Connect your Google Play account directly from the Deploy panel. Newly pulls in your Play Store listing data so you can manage Android deployments without leaving the app. [Learn more](/features/deployment)

  * **Android push notifications via OneSignal** — You can now configure push notifications for Android using Firebase Cloud Messaging (FCM). Upload your Firebase service account credentials in the OneSignal panel and send test notifications to both iOS and Android devices. [Learn more](/integrations/onesignal)

  * **Download project as ZIP** — Export your entire project as a ZIP file from the toolbar or the mobile menu. Useful for local backups or sharing your code outside of Newly. [Learn more](/advanced/exporting-code)

  * **Simulator build history** — View and manage previous simulator builds from the Deploy panel. You can reload a completed build back into the simulator, download artifacts, or delete old builds.

  * **Live Android build logs** — Watch real-time build output for Android APK and AAB builds directly in the Deploy panel. Build progress, errors, and status updates stream live as your build runs.

  ## Updates

  * **Redesigned settings** — A new settings modal replaces the previous account popup. Manage your profile, avatar, email addresses, connected accounts, active sessions, and account deletion all in one place.

  * **Improved simulator toolbar** — New controls for biometrics, media upload, location, and language. Simulator sessions now persist when switching between iOS and Android, and builds auto-install into the simulator when complete.

  * **Mobile-friendly onboarding** — The sign-up and login flow now features a cleaner OTP input for verification codes and better layouts on smaller screens.

  * **Better mobile experience** — Improved project view layout on mobile, globally visible connection status banners, and a fixed send button on mobile chat.

  * **Longer build timeouts** — Build containers now run for up to 24 hours, so large or complex builds no longer risk timing out.

  ## Bug fixes

  * Fixed inconsistent OAuth sign-in flows across providers
  * Fixed chat input not resetting its height after sending a message
  * Fixed chat history disappearing after manual commits
  * Improved socket connection stability to reduce disconnects
  * Fixed queued prompt images not uploading correctly before being sent to the AI
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-04-06

Latest updates and improvements to Newly

<Update label="April 6, 2026" description="Project cloning, guided tours, smarter AI error detection, and more">
  ## New features

  * **Clone and duplicate projects** — You can now clone any of your existing projects to quickly spin up a new one based on what you've already built. Great for experimenting with variations or starting from a working template.

  * **In-app guided tours** — Interactive walkthroughs are now available across the editor. Get step-by-step onboarding for the code editor, visual editor, database panel, logs, GitHub integration, app settings, and permissions — all without leaving Newly.

  * **Automatic runtime error detection** — The AI agent now detects runtime errors and type issues in your app automatically. When something breaks, the agent catches it and can help you fix it without needing to copy-paste error messages. [Learn more](/features/ai-chat)

  * **Integration setup flows** — Connecting Supabase, RevenueCat, and OneSignal to your project now comes with step-by-step guided flows that walk you through the setup process. [Learn more](/integrations/supabase)

  * **Delete all projects** — A new option lets you delete all of your projects at once from your account settings.

  ## Updates

  * **Redesigned agent activity panel** — The panel that shows what the AI agent is doing has been completely redesigned for better clarity and readability.

  * **AI follow-up questions in the chat input** — When the AI asks you a clarifying question, it now appears directly in the chat input area so you can respond inline without scrolling.

  * **Ask mode and Plan mode pricing** — Ask and Plan mode messages now cost 0.1 credits each, making it more affordable to explore your codebase and plan changes before building.

  * **Improved App Store Connect experience** — The credential management flow for App Store Connect has been refined with clearer UX, making it easier to connect your account and manage certificates. [Learn more](/features/deployment)

  * **Smoother preview experience** — The web preview no longer flashes white on reload. Loading states and error boundaries have been improved so you see helpful feedback instead of blank screens.

  * **Smart native module detection** — When your project uses native modules, Newly now automatically disables the web preview and Expo Go options to avoid confusing errors. [Learn more](/features/preview)

  * **Scrollable project sidebar** — The sidebar now supports infinite scrolling, so you can browse all your projects without pagination.

  * **Database panel loading states** — The database panel now shows skeleton loaders while data is being fetched, making it feel more responsive.

  * **Prompt input blocked during backend deploy** — The chat input is now disabled while a backend deployment is running, preventing accidental changes mid-deploy.

  ## Bug fixes

  * Fixed project names defaulting to the prompt text instead of generating a proper name
  * Fixed chat scroll jumping unexpectedly when loading message history or during AI streaming
  * Fixed the visual editor not properly deactivating when switching away from it
  * Fixed missing imports not being resolved correctly in certain cases
  * Fixed GitHub commits not using the correct owner token
  * Fixed stale "in progress" indicators that would persist after the AI finished working
  * Fixed tab bar scrolling not working in certain views
  * Improved ZIP export to correctly include all necessary project files
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-04-13

Latest updates and improvements to Newly

<Update label="April 13, 2026" description="Demo mode, folder management, faster Android builds, and more">
  ## New features

  * **Demo mode** — You can now try Newly without creating an account. Explore the editor, preview, and AI chat to get a feel for the platform before signing up.

  * **Folder creation and deletion** — Create and delete folders directly in the code editor. Manage your project structure without needing to use the terminal.

  * **Plan mode improvements** — The Plan mode approval flow has been redesigned. You can now review, approve, or reject the AI's proposed plan more easily before it starts building.

  ## Updates

  * **Faster Android builds** — Android builds and simulator dev builds are now significantly faster, reducing wait times when testing and deploying your app. [Learn more](/features/deployment)

  * **Resizable editor panels** — Editor panels are now adjustable, so you can resize the code editor, preview, and chat to fit your workflow.

  * **Low prompt warnings** — You now see a warning when you have 3 prompts remaining, so you're never caught off guard.

  * **File changes visible in chat** — When the AI creates or deletes files and folders, those actions now appear in the chat panel in real time so you can follow along.

  * **Screenshot editor in toolbar** — The screenshot editor has been moved to the toolbar for quicker access.

  * **Deploy panel improvements** — The deploy panel now uses consistent logic across iOS and Android, with better state tracking for when your app has changed since the last deploy.

  ## Bug fixes

  * Fixed white screen flashes in the preview when reloading or encountering errors
  * Fixed OneSignal Android setup not correctly saving the `google-services.json` file to your project
  * Fixed Android APK build state not updating correctly
  * Fixed connection lost banner not showing on all tabs
  * Fixed various login page and header UI issues
  * Fixed Supabase and RevenueCat integration edge cases
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-04-20

Latest updates and improvements to Newly

<Update label="April 20, 2026" description="Terminal access, GitHub App install, image uploads in Ask mode, and more">
  ## New features

  * **Terminal access** — You can now run terminal commands directly inside Newly. The AI agent has access to a sandboxed terminal, so it can install packages, run scripts, and debug issues without leaving the editor.

  * **GitHub App installation** — Connecting your GitHub account now uses a GitHub App install flow, making it easier to grant repository access and manage permissions. [Learn more](/integrations/github)

  * **Image uploads in Ask mode** — You can now attach images when using Ask mode in the AI chat. Share screenshots or mockups and ask the AI questions about them. [Learn more](/features/ai-chat)

  * **AI-powered docs lookup** — The AI agent can now search and reference the Newly documentation directly in your conversation, so it gives more accurate answers about platform features and setup steps.

  * **Skip prompt queue** — You can now skip queued prompts that are waiting to be processed, giving you more control over your chat workflow.

  ## Updates

  * **Improved OneSignal setup** — The OneSignal integration now automatically provisions and removes push notification credentials when you connect or disconnect, reducing manual setup steps. [Learn more](/integrations/onesignal)

  * **Better native package detection** — When your project uses unsupported native modules, the notification now includes the specific package names and links to relevant documentation. [Learn more](/guides/native-packages)

  * **GitHub disconnect modal** — Disconnecting your GitHub account now shows a confirmation modal, preventing accidental disconnects.

  * **Expo polyfills for alert and fetch** — Projects now include global polyfills for `alert()` and `fetch`, reducing common runtime errors in Expo-based apps.

  ## Bug fixes

  * Fixed mascot animation appearing over the mobile preview
  * Fixed animation dot showing on the login and signup pages
  * Fixed unauthorized users not being redirected to the login page when accessing a project
  * Fixed a client-side crash that could occur during certain interactions
  * Fixed queued prompts overlapping with the mascot UI
  * Fixed subscriptions in a past-due state not being cancellable
  * Fixed a misleading deploy banner showing after a dev build was already completed
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-04-27

Latest updates and improvements to Newly

<Update label="April 27, 2026" description="Marketing Studio launch, remixing generations, AI compliance checks, and more">
  ## New features

  * **Marketing Studio** — Generate marketing videos with Seedance 2.0, hero images with Nano Banana 2, and run Instagram influencer outreach campaigns — all from inside any Newly project. Open the Marketing Studio panel from the right-hand tool strip. [Learn more](/features/marketing-studio)

  * **Remix in Marketing Studio** — You can now remix any video or image you've generated. Tweak the prompt or settings and produce a new variation without starting from scratch. [Learn more](/features/marketing-studio)

  * **AI compliance checker** — The AI agent now validates generated code for App Store and Play Store compliance issues before you deploy, and lets you manually override findings when needed.

  ## Updates

  * **Faster Deploy to backend** — The Deploy to backend flow has been optimized for quicker, more reliable deploys. [Learn more](/features/backend)

  * **Clearer error feedback in Marketing Studio** — When a generation fails, the panel now surfaces the underlying provider failure so you know exactly what went wrong instead of seeing a silent failure.

  * **Better support widget copy** — The in-app support widget now uses clearer, friendlier wording so it's easier to get the help you need.

  ## Bug fixes

  * Fixed setup overlay getting stuck in a wedged state — it now clears as soon as the AI agent starts working
  * Fixed long user prompts overflowing horizontally in the chat panel — they now wrap correctly
  * Fixed the simulator preview not rendering correctly on the mobile layout
  * Removed a leftover cosmetic sidepanel on the mobile editor
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-05-04

Latest updates and improvements to Newly

<Update label="May 4, 2026" description="Runtime error auto-fix, Marketing Studio storyboard, browser notifications, and more">
  ## New features

  * **Runtime error auto-fix** — When your app crashes in the preview, Newly now detects the error and offers a one-click "Fix with AI" button in the chat panel. Runtime error fixes don't count against your prompt usage. [Learn more](/features/ai-chat)

  * **Browser notifications when prompts complete** — Get a desktop notification the moment the AI agent finishes a long-running prompt, so you can step away without checking the tab.

  * **OneSignal analytics dashboard** — A new analytics dashboard with charts shows push delivery, opens, and engagement for projects connected to OneSignal. [Learn more](/integrations/onesignal)

  * **Inline terminal output in chat** — When the AI agent runs terminal commands, output now renders inline in the chat thread so you can follow what's happening without expanding a separate panel.

  ## Updates

  * **Subscription cancellation guide** — Added a step-by-step guide for cancelling a subscription and requesting a refund. [Learn more](/guides/cancel-subscription)

  * **Better prompting guides** — Refreshed guidance on how to write effective prompts and save prompt usage. [Learn more](/guides/save-prompts)

  * **Updated terms and privacy policy** — Refreshed the terms of service and privacy policy. Continued use of the platform contitutes agreement with our terms of service. You can read more at newly.app/terms & newly.app/privacy.

  * **Smarter compliance checks** — The pre-deploy compliance checker now infers Support URL and Privacy Label from your live App Store Connect version, blocks on dim or undersized app icons, and uses a corrected splash screen spec. Static and AI-powered checks now run as separate phases for clearer feedback.

  * **More reliable deploy compliance step** — Fixed a flaky timeout so the compliance step no longer fails spuriously on slower runs.

  * **RevenueCat reconnect** — Disconnecting and then reconnecting RevenueCat now works as expected, and the integration is available without requiring an internal feature flag. [Learn more](/integrations/revenuecat)

  * **Apple bundle without app ID** — Apps can now be bundled for Apple submission even when an App ID hasn't been registered yet.

  * **Prompt input locks during error fixes** — While the AI agent is fixing a runtime error, the prompt input is disabled to prevent conflicting requests.

  * **Honest iPhone safe areas in web preview** — The web preview now respects iPhone safe areas, and the iPhone preview frame has tighter margins so more of your app is visible.

  ## Bug fixes

  * Fixed multi-select inputs not always showing the free-form "other" option
  * Fixed payment popover layout on mobile
  * Fixed long URLs overflowing horizontally in the chat panel
  * Fixed the deploy button vanishing when compliance reached 100%
  * Fixed an occasional double blank commit after merging
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-05-11

Latest updates and improvements to Newly

<Update label="May 11, 2026" description="Build-fix agent, faster project startup, smarter AI agent, and more">
  ## New features

  * **Build-fix agent** — When an Android or iOS build fails, Newly now analyzes the build log and offers a one-click fix in the chat panel. No more digging through gradle output to figure out what broke. [Learn more](/features/deployment)

  * **Support contact skill** — The AI agent can now point you to the right channel when you need to reach the Newly team, so getting help from inside a project is faster.

  ## Updates

  * **Faster project startup** — Starting a new project is noticeably quicker. The preview environment now spins up in parallel with the rest of the setup flow instead of waiting in sequence.

  * **Smarter system prompts** — Refreshed the AI agent's system prompts and Better Auth guidance so generated code is more accurate the first time, especially around authentication and RevenueCat.

  ## Bug fixes

  * Fixed an issue where the Expo preview's global `fetch` polyfill could conflict with app code, causing unexpected network behavior.
  * Fixed a backend deploy edge case where local changes weren't fetched before merging, leading to stale backend URLs.
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-05-18

Latest updates and improvements to Newly

<Update label="May 18, 2026" description="Screenshot editor, credit top-ups, git history graph, billing tab, and more">
  ## New features

  * **Screenshot editor with AI generation** — A new screenshot editor lets you frame your app in iPhone and iPad device mockups and generate polished App Store screenshots with GPT Image 2. [Learn more](/features/marketing-studio)

  * **Credit top-ups** — Out of credits before your next renewal? You can now buy a one-time credit top-up from the pricing page without changing your plan.

  * **Git history graph** — Branch and commit history now renders as an interactive graph so you can see how your project has evolved, which branches diverged, and where merges happened. [Learn more](/advanced/version-control)

  * **Billing tab in your profile** — A dedicated Billing tab in the profile menu puts your subscription, invoices, and payment method in one place.

  * **Auto-cancel on account delete** — Deleting your account now automatically cancels any active subscription, so you won't be charged after you leave.

  * **Shared projects in the sidebar** — Projects shared with you now appear in the project list with your role badge, and share state stays in sync across tabs. [Learn more](/integrations/github)

  * **Auto branch creation** — When you start a new prompt or open a project, Newly automatically creates a working branch if one doesn't already exist, keeping your main branch clean.

  * **GitHub health diagnostics** — Project admins get a new GitHub health panel that flags auth, branch, and source-of-truth issues at a glance, with controls to resolve them inline. [Learn more](/integrations/github)

  ## Updates

  * **"Credits" replaces "prompts"** — We've renamed prompts to credits across the app for clearer, more consistent billing language.

  * **Mobile-only requests handled gracefully** — When you ask the AI agent for a web-only feature, it now suggests the mobile equivalent instead of refusing outright.

  * **RevenueCat disconnect clarity** — The RevenueCat disconnect modal now includes an info box explaining that your paywall stays in place after disconnecting. [Learn more](/integrations/revenuecat)

  * **Smarter Supabase guidance** — The AI agent now follows updated Supabase integration rules, producing more accurate code for auth, storage, and database work on the first try. [Learn more](/integrations/supabase)

  * **Safer backend changes during builds** — The agent now refuses backend changes while a branch is still building, preventing half-applied updates.

  ## Bug fixes

  * Fixed Fix-with-AI offers triggering on harmless React DOM-prop warnings.
  * Fixed a git divergence issue that could leave branches out of sync after a merge.
  * Fixed pre-connect iOS compliance reminders incorrectly carrying over to the App Store target.
  * Fixed unsubscribe so drip emails are cancelled before audience updates, preventing one last unwanted email.
  * Fixed transient deploy alerts caused by retryable 5xx responses when checking branch build status.
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-05-25

Latest updates and improvements to Newly

<Update label="May 25, 2026" description="Per-project backends, compliance fixer, redesigned support widget, new chat bar, and more">
  ## New features

  * **Per-app marketing website generator** — Generate a polished landing page for any app to satisfy store compliance requirements, then edit it from a dedicated website chat panel. [Learn more](/features/marketing-studio)

  * **Brainstorming mode for plan mode** — The plan mode now asks deeper and better questions. [Learn more](/features/ai-chat)

  * **Redesigned in-app support widget** — The support widget has been rebuilt with a multi-ticket flow, a home/help/chat layout, and image attachments via drag, drop, or paste — making it faster to file issues and track replies.

  * **New chat bar and toolbar** — The project chat bar and tool strip have a fresh layout and design that surfaces actions more clearly and gives you more room to work. [Learn more](/features/ai-chat)

  * **Hub chat widget** — The marketing site now has a Gemini-backed Hub chat with a wandering mascot, so visitors can ask product questions and get linked to the right docs.

  ## Updates

  * **Markdown in question cards** — Clarifying-question cards in chat now render full markdown, so links, lists, and code formatting all come through.
  * **Friendlier tool errors** — When the agent hits an unknown-tool error, it now gets a recovery hint and keeps going instead of surfacing a raw error.

  ## Bug fixes

  * Fixed mascot rendering glitches in the Hub chat widget on mobile browsers.
  * Fixed activity events occasionally leaking across user sessions on shared workspaces.
  * Fixed in-flight builds racing with backend changes, which could leave a branch in a half-applied state.
  * Fixed a website-editor issue where build artifacts from one project could bleed into another.
  * Fixed the displayed average response time on the support widget to reflect the correct time.
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-06-01

Latest updates and improvements to Newly

<Update label="June 1, 2026" description="Publish screenshots to App Store Connect, redesigned website editor, sharper runtime errors, and more">
  ## New features

  * **Publish screenshots to App Store Connect** — Send screenshots straight from the screenshot editor to your App Store Connect listing, no manual upload required. [Learn more](/features/marketing-studio)

  * **Website editor workspace upgrades** — The website chat panel now has a fullscreen toggle, a resizable split between chat and preview, and a restart icon so you can reset a session without leaving the editor. [Learn more](/features/marketing-studio)

  * **Stop button for in-flight agent runs** — Cancel a website-editor generation mid-stream when you've seen enough or want to change direction. [Learn more](/features/marketing-studio)

  * **Copy chat messages** — Each message in the website-editor chat has a copy button, making it easier to reuse prompts and responses.

  * **Meaningful commit messages on website edits** — Website-editor commits are now generated by a dedicated model, so your git history reads like a changelog instead of a hash dump.

  * **Smoother reconnect when your session drops** — If the editor's connection blips, you'll get a clearer reconnect banner with consistent styling on desktop and mobile.

  * **Animated Hub mascot** — The Hub chat widget on newly.app now greets visitors with an animated Thinking mascot while it's drafting a reply.

  ## Updates

  * **Sharper runtime crash prompts** — When your app crashes, the Fix-with-AI card now shows the real error message from console errors, unhandled rejections, and error boundaries instead of a generic "Console Error" label, so you can decide whether to fix at a glance. [Learn more](/features/ai-chat)

  * **Improved support widget** — The in-app support widget now paginates your tickets, polls for new replies in the background, and renders attached images inline so you can follow a thread without leaving the panel.

  ## Bug fixes

  * Fixed upgrade-then-cancel flows that could refill prompt credits without a charge.
  * Fixed the credit anchor on the pricing page to derive from invoice state instead of stale metadata, so renewal dates are accurate.
  * Fixed the Hub chat assistant occasionally claiming Newly is free.
  * Fixed runtime errors so the source location now points to the right file and line.
  * Fixed a stale "project removed" alert that could appear after a project was deleted.
  * Fixed website-editor sessions that broke after a recent storage migration.
  * Fixed a rotation glitch in the Specular preview surface.
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-06-08

Latest updates and improvements to Newly

<Update label="June 8, 2026" description="Per-project backend viewer, dev + prod backend URLs, agent activity panel upgrades, and more">
  ## New features

  * **Top-of-page error banner** — A new banner at the top of the project view surfaces AI and project-level errors immediately, so you don't miss issues that previously only showed inside chat.

  * **Fix dev server button** - Sometimes dev servers would hang due to the bad package versions, we now have a dedicated fix button for this

  * **Improved web crawling** - The agent now returns better web crawling results

  ## Bug fixes

  * Fixed the agent occasionally suggesting actions that could harm your Newly project.
  * Fixed a spurious Apple sign-in error that appeared after a session timeout.
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-06-15

Latest updates and improvements to Newly

<Update label="June 15, 2026" description="Cancellation survey, checkout terms acknowledgment, support widget unread badge, RevenueCat reconnect, and more">
  ## New features

  * **Unread reply badge on the support widget** — The support launcher now shows an unread badge the moment a new reply lands and clears it instantly when you open the ticket, so you stop missing responses.

  * **"Get Funded"** — You can now apply for funding at newly.app/get-funded

  ## Updates

  * **Pricing and usage questions answered on newly.app** — When you ask the in-project agent about pricing, plans, or prompt usage, it now points you to the dedicated answers on newly.app instead of guessing.

  ## Bug fixes

  * Fixed Android builds that were cancelled or torn down mid-run so they now record a final terminal state instead of appearing stuck in progress.
  * Fixed RevenueCat connections so an expired session reconnects gracefully instead of throwing repeated errors.
  * Fixed prompt usage to stop deducting credits when a request fails, so you're no longer charged for negative outcomes.
  * Fixed the database viewer to hide an empty branch ID when no Specular branch is linked.
  * Fixed the YouTube handle in the marketing site footer.
</Update>


# Changelog
Source: https://docs.newly.app/changelog/2026-06-29

Latest updates and improvements to Newly

<Update label="June 29, 2026" description="Publish to TestFlight from chat, GitHub and social sign-in on the desktop app, marketing video previews, mobile companion, and more">
  ## New features

  * **Publish to TestFlight from chat** — You can now hand off an iOS build to TestFlight directly from a chat message, without leaving the conversation. See [Deployment](/features/deployment).

  * **Newly desktop app** — The new macOS desktop app picked up a big batch of capabilities this week:
    * Sign in with Clerk, including Google and other social providers.
    * Connect a [GitHub](/integrations/github) repo to push code from desktop projects.
    * A new agent activity view that visualizes workflow runs and the agent's task list inside chat.
    * A styled DMG installer with a refreshed squircle app icon.

  * **Mobile companion** — Start a chat on desktop and pick it up on your phone. Sessions now sync between the desktop app and the Newly mobile companion.

  * **Marketing video previews** — The [Marketing Studio](/features/marketing-studio) agent can now generate short marketing video previews alongside screenshots and copy.

  * **Separate account tabs for Apple, Google Play, and Expo** — The project view splits store credentials into dedicated tabs so it's clear which account is connected to which platform. See [Deployment](/features/deployment).

  * **Usage tab for free users** — Free accounts with granted prompts now see a usage tab so you can track remaining prompts at a glance.

  ## Updates

  * **Smoother first-run experience on macOS** — Fresh-Mac installs of the desktop app now ship with a self-contained toolchain, harder sidecar startup, and an Install Xcode call-to-action when Xcode is missing, so a brand-new Mac can build apps without manual setup.

  ## Bug fixes

  * Fixed TestFlight publishing on fresh desktop installs that previously failed with an `ENOENT` error.
  * Fixed Android APK builds that intermittently failed to resolve the project root.
  * Fixed the Modal status indicator to query the status page directly so operational state is reported accurately.
</Update>


# Core Concepts
Source: https://docs.newly.app/concepts

Understand how Newly works under the hood

# Core Concepts

Before diving deep into Newly, it helps to understand the key concepts and how they work together.

## The Newly Workflow

Newly follows a simple but powerful workflow:

```mermaid theme={null}
graph LR
    A[Describe in Chat] --> B[AI Generates Code]
    B --> C[Live Preview]
    C --> D[Refine & Iterate]
    D --> A
    D --> E[Deploy to Stores]
```

<Steps>
  <Step title="Describe">
    You describe what you want in natural language through the AI chat
  </Step>

  <Step title="Generate">
    The AI generates React Native code, handles dependencies, and structures your project
  </Step>

  <Step title="Preview">
    See your changes instantly in the live mobile preview
  </Step>

  <Step title="Iterate">
    Refine your app by chatting more with the AI or editing code directly
  </Step>

  <Step title="Deploy">
    When ready, deploy to iOS App Store and Google Play Store
  </Step>
</Steps>

## Projects

A **project** in Newly is your complete mobile app. Each project contains:

* **Source Code** - React Native/Expo code generated by the AI
* **Assets** - Images, fonts, and other media files
* **Configuration** - App settings, dependencies, and build configuration
* **Chat History** - Your conversation with the AI for context
* **Version History** - Commits tracking all changes made

### Project Structure

Your project follows a standard Expo project structure:

```
/app                  # Screen components (file-based routing)
  ├── index.tsx       # Home screen
  ├── profile.tsx     # Profile screen
  └── (tabs)/         # Tab navigation
/components           # Reusable UI components
/utils                # Helper functions and utilities
/assets               # Images, fonts, and static files
app.json              # Expo configuration
package.json          # Dependencies
```

## The AI Agent

The AI agent is the brain behind Newly. It understands your requests and generates appropriate code.

### What the AI Can Do

<CardGroup>
  <Card title="Generate Screens" icon="mobile">
    Create complete screens with UI components, styling, and layout
  </Card>

  <Card title="Add Features" icon="plus">
    Implement functionality like forms, navigation, and data handling
  </Card>

  <Card title="Fix Bugs" icon="bug">
    Diagnose and fix issues you describe
  </Card>

  <Card title="Refactor Code" icon="wand-magic-sparkles">
    Improve existing code structure and patterns
  </Card>

  <Card title="Create Backend" icon="server">
    Generate API endpoints and database schemas
  </Card>

  <Card title="Integrate Services" icon="plug">
    Connect to external APIs and services
  </Card>
</CardGroup>

### How the AI Works

1. **Classification** - First, the AI determines if you're asking for code changes or just asking a question
2. **Context Analysis** - It reviews your existing code and chat history
3. **Code Generation** - Generates or modifies code based on your request
4. **Linting & Validation** - Checks for errors and fixes common issues
5. **Build & Preview** - Compiles the app and updates the preview

<Note>
  The AI maintains context from your chat history, so you can reference previous conversations. "Make the button from earlier bigger" works because the AI remembers what button you were discussing.
</Note>

## Live Preview

The preview panel shows your app running in real-time. It's not a simulator—it's your actual app running in a web-based Expo environment.

### Preview Features

* **Touch Interactions** - Tap, swipe, and scroll like a real device
* **Navigation** - Move between screens and test flows
* **Data Persistence** - State persists during your session
* **Hot Reload** - Changes appear instantly without losing state
* **Device Preview** - Test on your actual phone via QR code

## Version Control

Every change you make is tracked as a **commit**. This gives you:

* **History** - See what changed and when
* **Rollback** - Revert to any previous version if something breaks
* **Context** - The AI can reference previous changes

### Commit Messages

The AI automatically generates descriptive commit messages based on what changed:

```
Added user profile screen with avatar upload
Fixed navigation bug on iOS
Implemented shopping cart with checkout flow
```

<Tip>
  You can view and restore previous versions from the version history panel accessed via the sidebar.
</Tip>

## Liquid Backend

For apps that need server-side functionality, Newly uses **Liquid Backend** to automatically generate your backend.

### What Liquid Backend Provides

* **API Endpoints** - RESTful APIs generated from natural language
* **Database** - PostgreSQL database with automatic schema management
* **Authentication** - User registration, login, and session management
* **File Storage** - Upload and serve files and images
* **Serverless** - No infrastructure to manage

### When Backend is Created

The AI automatically creates backend functionality when you request:

* User accounts and authentication
* Saving data that persists across sessions
* API integrations requiring server-side secrets
* Complex data processing or AI features

```
// Example prompt that triggers backend creation:
"Add user authentication with email and password.
Save user preferences to their account."
```

## Code Ownership

**You own 100% of the code generated by Newly.** There's no vendor lock-in.

### Export Options

* **GitHub Sync** - Automatically sync to your repository
* **Download ZIP** - Download complete source code
* **Local Development** - Clone and run on your own machine

### What You Get

```bash theme={null}
# Complete, runnable Expo project
git clone your-repo/my-app
cd my-app
npm install
npx expo start
```

The exported code is standard React Native/Expo code that any developer can understand, modify, and maintain.

## Next Steps

Now that you understand the concepts, dive into the features:

<CardGroup>
  <Card title="AI Chat" icon="message-bot" href="/features/ai-chat">
    Master the AI chat interface
  </Card>

  <Card title="Live Preview" icon="eye" href="/features/preview">
    Get the most out of the preview
  </Card>

  <Card title="Code Editor" icon="code" href="/features/code-editor">
    Edit code directly when needed
  </Card>

  <Card title="Backend" icon="server" href="/features/backend">
    Understand backend generation
  </Card>
</CardGroup>


# AI Chatbot 
Source: https://docs.newly.app/documentation/features/ai-chat

How to Build an AI-Powered Chatbot?

With **Newly’s Liquid Backend**, you’re just a few prompts away from launching an AI chatbot or any AI-powered application. Simply describe the type of chatbot or AI feature you want, and Newly builds it for you. No manual API setup. No configuration headaches. No API keys required by default.

You focus on the idea. Newly handles the intelligence behind it.

### Example Use Cases

<Note>
  * **AI-Powered History App**\
    Create an app where users can ask questions about historical events, figures, or timelines and get instant, conversational answers.
  * **Workout & Nutrition Advisor Chatbot**\
    Add an AI chatbot inside a fitness app (e.g., in the Reports section) that provides personalized workout advice and nutrition tips based on user input.
  * **AI-Driven Calorie Tracking App**\
    Build an app where users upload a photo of their meal, and the AI automatically estimates calories, carbohydrates, protein, and fat content.
</Note>

### Using a Specific AI Model

By default, Newly handles the AI setup for you. If you want to integrate a specific AI provider or model, simply add its API key in the **Database → Secrets** section, then ask Newly to build the AI functionality using that specific API.


# FAQ
Source: https://docs.newly.app/faq

Quick answers to the questions our support team hears most often.

The most common questions builders ask us, with short answers and links to the longer guides. If you don't find what you need here, the [Discord community](https://discord.com/invite/sPbqWqgcMf) and [support@newly.app](mailto:support@newly.app) are both good next steps.

## Building & iterating

<AccordionGroup>
  <Accordion title="Should I build on Android or iOS while iterating?">
    Android, in most cases. The Android simulator boots faster and doesn't go through Expo's pipeline, so it has fewer steps that can fail between you and a working app. Switch to iOS when you need to verify something iOS-specific (Apple sign-in, Apple Pay, an iPad-only layout) and when you're ready to ship to TestFlight.

    Full breakdown: [Recommended dev loop](/guides/recommended-dev-loop).
  </Accordion>

  <Accordion title="The AI broke my app – how do I undo it?">
    Use the **Restore** button next to any previous chat message. It rolls your project back to that exact point, dependencies and project state included. Restoring is almost always faster than prompting your way out of a broken state, and it costs zero credits.

    Restoring from chat history is also more reliable than pasting code from a downloaded ZIP – the chat history Restore preserves dependency versions, not just files.
  </Accordion>

  <Accordion title="The AI keeps making the same wrong fix. What can I do?">
    Switch the prompt from *"fix the bug"* to *"diagnose, then fix"*. Tell the AI to read the relevant file, run the failing action, and explain what's wrong before making any changes:

    ```
    Before changing any code, read [path] and the relevant logs, and tell me what's causing the error. Don't change anything yet.
    ```

    This usually lands a fix in one round instead of three. More on the pattern in [How to save credits](/guides/save-prompts#diagnose-first-then-fix).
  </Accordion>

  <Accordion title="When should I use Ask mode?">
    For any prompt that's a question, not a code change. "What does this error mean?" or "How does my auth flow work?" should go through Ask mode, which costs about 10× fewer credits than a build request.

    Switch via the build dropdown above the chat input.
  </Accordion>

  <Accordion title="Can I edit code directly instead of going through the AI?">
    Yes. The file viewer on the left side of the project view lets you open and edit any file. Save and your changes land on disk immediately – no AI involvement, no credit cost.

    Useful for small tweaks (a copy change, a color value) where prompting would be more work than just typing.
  </Accordion>
</AccordionGroup>

## Preview, simulator, and builds

<AccordionGroup>
  <Accordion title="Why does the feature show up in Newly preview but not in TestFlight?">
    They're different runtimes. Newly preview re-bundles your JS live as you save, so changes show up immediately. TestFlight runs a frozen native binary from your last EAS build – so any code change you made after that build isn't in TestFlight until you trigger a new build and upload it.

    Full explanation: [Preview vs builds](/guides/preview-vs-builds).
  </Accordion>

  <Accordion title="Why is the web preview stuck on 'Loading preview...'?">
    Usually a native-only package (most commonly OneSignal) that can't run in the browser. Switch to the iOS or Android simulator tab and build there.

    Walkthrough: [Preview troubleshooting](/guides/preview-troubleshooting#web-preview-stuck-on-loading-preview).
  </Accordion>

  <Accordion title="Why does iOS preview show 'Welcome to Newly, your app is currently building'?">
    Usually the AI updated your Android and web screens but missed the matching iOS ones. Ask the AI to update the iOS version of your app so it matches what you see on web and Android.
  </Accordion>

  <Accordion title="Add-member or save buttons throw 'session expired' in the web preview">
    The web preview wraps your app in an iframe, which can interfere with auth tokens on certain endpoints. Test the same action in Expo Go on a simulator or your phone – it almost always works there without any code change.

    Full context: [Preview vs builds – web preview iframe](/guides/preview-vs-builds#common-confusions-explained).
  </Accordion>

  <Accordion title="My code change is on disk but Expo Go still shows the old version">
    Force-close Expo Go on your device and re-scan the QR code. Expo Go caches a connection to the previous bundle, and a fresh QR scan picks up the new one.
  </Accordion>
</AccordionGroup>

## Deploy & ship

<AccordionGroup>
  <Accordion title="How do I get my app onto TestFlight?">
    From inside your project, open the **Deploy** tab and trigger an iOS production build. When it finishes, the Deploy tab gives you the option to send the build to App Store Connect – that's what makes it appear in TestFlight.

    Full deployment flow: [Deployment](/features/deployment).
  </Accordion>

  <Accordion title="Why is my AAB rejected by Google Play with 'wrong package name'?">
    Two things to check. First, confirm `android.package` in your `app.json` matches what Google Play expects. Second, if you recently changed the bundle ID, make sure both sides got updated – see [Changing your bundle ID](/guides/bundle-id-changes).
  </Accordion>

  <Accordion title="I renamed my bundle ID but EAS still uses the old one">
    Bundle ID changes are a two-step update – saving the new bundle in Apple Credentials updates your project, but doesn't push the new value to OneSignal's APNs config. The full sequence is in [Changing your bundle ID](/guides/bundle-id-changes).
  </Accordion>

  <Accordion title="My build keeps failing – how do I see the actual error?">
    Open the **Logs** panel in your project and look at the Build Logs section. The relevant error is usually a line with `FAILED` or `error:` near the bottom. Paste that into the chat with one line of context and the AI can usually fix it.

    Full guide: [Using logs to debug](/guides/using-logs-to-debug).
  </Accordion>
</AccordionGroup>

## Credits & subscription

<AccordionGroup>
  <Accordion title="What happened to 'prompts'? I see 'credits' everywhere now">
    Same thing, renamed. We switched the term from *prompts* to *credits* in May 2026 to match the way most builders were already thinking about usage. No change in how billing works.
  </Accordion>

  <Accordion title="I'm running out of credits before my renewal – can I top up?">
    Yes. The pricing page has a credit top-up option – a one-time purchase that adds credits to your account without changing your plan or billing cycle.

    Go to **newly.app/pricing** → **Usage** tab.
  </Accordion>

  <Accordion title="Does Ask mode use a full credit?">
    No, it costs about 10× less than a standard build request. Use it for anything that's a question rather than a code change.
  </Accordion>

  <Accordion title="Did the 'Fix with AI' button just deduct a credit?">
    The crash banner's "Fix with AI" button itself is free – that specific click doesn't cost a credit. What does cost credits is follow-up chat after that fix attempt (retries, "this still isn't right", etc.). So if you saw credits go down around the time you clicked it, the cause is usually the chat that followed, not the click.
  </Accordion>

  <Accordion title="How do I cancel my subscription?">
    See [Cancel subscription](/guides/cancel-subscription). You can self-serve from your billing page.
  </Accordion>

  <Accordion title="How do I delete my account?">
    Open the profile menu (your avatar) → **Settings** → the **Danger zone** tab, then confirm with your account email. Deletion is permanent and removes all your projects; if you have a paid plan it's cancelled automatically (no refund for unused time). Full details, and the lighter options to consider first, are in [Delete your account](/guides/delete-account).
  </Accordion>
</AccordionGroup>

## Common AI quirks

<AccordionGroup>
  <Accordion title="The AI said it made a change, but nothing happened">
    First, click **Restore** on the message right before the AI's "applied" response and try again with a more specific prompt. If the same thing happens, switch to using the file viewer directly for small edits, or ask the AI to produce a unified diff that you apply yourself:

    ```
    Do not write any files. Produce all changes as unified diffs in code blocks. I will apply them via the file viewer.
    ```

    If the issue persists across multiple sessions on the same project, send us a message at [support@newly.app](mailto:support@newly.app) with your project name and we'll take a look.
  </Accordion>

  <Accordion title="The AI keeps telling me 'this is a Newly platform issue, contact support'">
    Sometimes that's accurate. More often, it's the AI's fallback when it can't pinpoint the actual bug. Before opening a ticket, try the diagnose-first prompt:

    ```
    Read the relevant file and the logs. Tell me what specifically is failing and what line of code or config is responsible. Don't say it's a platform issue without checking first.
    ```

    If after that the AI still says it's a platform issue with specifics (an exact endpoint, a specific error in our infrastructure), that's worth a support ticket. If it just repeats the framing, it's almost always a code issue the AI hasn't found yet.
  </Accordion>

  <Accordion title="My iOS app shows up but my changes from this session aren't there">
    If you're testing in TestFlight or a previously-built iOS binary, that build doesn't contain anything you've changed since the build was triggered. Trigger a fresh iOS build from the Deploy tab and upload the new build. See [Preview vs builds](/guides/preview-vs-builds) for the full breakdown.
  </Accordion>
</AccordionGroup>

## Still stuck?

If your question isn't answered here:

* Ask in the [Discord community](https://discord.com/invite/sPbqWqgcMf) – fastest for general questions.
* Use the in-app support widget to reach out to support without leaving your project.
* Email [support@newly.app](mailto:support@newly.app) for anything account-specific, billing-related, or where you need someone to look at your project directly.

When you write in, including your project name and a screenshot of what you're seeing saves us (and you) a round-trip.


# Prompting
Source: https://docs.newly.app/features/ai-chat

Master the conversational interface for building apps

# AI Chat Interface

# The AI Chat is your primary tool for building apps in Newly. Through natural conversation, you can build your app, create features, fix bugs, and refine your app in real time.

## How It Works

The chat panel on the left side of the screen is where you interact with the AI. Simply describe what you want in plain language - English or in your own native language, and the AI will:

1. Understand your request and build your app
2. Generate and modify code
3. Build and deploy changes
4. Show results instantly in the preview and Expo Go

**Note:** This is a build-focused AI. Use it to build, modify, fix, or add features to your app, not as a general-purpose chatbot for asking unrelated questions.

<Tip>
  The AI maintains the full context of your conversation and project. You can reference previous changes, screens, or features by name.
</Tip>

## Writing Effective Prompts

Clear prompts lead to better results. By describing what you want in a simple and specific way, you’ll help the AI build exactly what you’re looking for. Here are some proven patterns to follow:

### Be Specific

<Tabs>
  <Tab title="Good">
    ```
    - Start with a one-line description of your mobile app.
    Example: “Build me a calorie-tracking app with AI integration.” or "Build me a flashcard app."
    - Provide short, clear context about the app’s main purpose.
    Example: “Users can take a photo of their meal, and the app analyzes whether it’s healthy, then estimates calories, carbs, protein, and fat.”
    - Focus on a simple version of your app in your first prompt.
    You can enhance features and add complexity in follow-up prompts.
    ```
  </Tab>

  <Tab title="Too Vague">
    ```
    Build me an app
    ```
  </Tab>
</Tabs>

### Describe the Behavior

<Tabs>
  <Tab title="Good">
    ```
    User experience is crucial. Make sure you understand the full flow of a user’s journey in your app.
    - Map the user journey: Determine if users need to create an account, go through onboarding, or if your app works without sign-ups and stores user data automatically.
    - Test the app: Use Expo Go to check that all features work properly and the experience feels smooth. If something doesn’t work—like button overlays, saving/deleting issues, or navigation problems—note the issue and ask the AI to fix it.
    - Use clear icons: Ensure your app’s icons are intuitive and easy to understand. You can pick your preferred ones from the visual editor.

    Note: When prompting the AI, combine a screenshot with your text prompt. This helps the AI understand the exact location and context for building or modifying features.
    ```
  </Tab>

  <Tab title="Too Vague">
    ```
    Make my app flow good
    ```
  </Tab>
</Tabs>

### Reference Existing Elements

<Tabs>
  <Tab title="Good">
    ```
    - Fixing existing features: Always reference the specific feature that isn’t working and explain exactly what needs to be fixed. Uploading a screenshot is highly recommended.
    Example: “At the Upload Picture of the Meal feature, I cannot upload a picture, and it doesn’t analyze or give me counts for protein, carbs, calories, and fat. Please fix this.” (+ screenshot)
    - Adding new sections or features: Clearly explain what you want to add and where it should appear in the app.
    Example: “Please add a new section to my app where I can see a monthly report of my meals, including calories, carbs, protein, and fat.”
    - Modifying design: You can upload a design from Figma, a Pinterest sample, or simply describe your design ideas in plain language. Use the visual editor for implementing design changes.
    - Fixing unclear icons: If you see question marks in place of icons, you can fix them immediately using the visual editor.
    ```
  </Tab>

  <Tab title="Ambiguous">
    ```
    Add a save button somewhere
    ```
  </Tab>
</Tabs>

### Database and Backend (including Authentication)

```
- Authentication setup: Decide how users will sign up and log in (e.g., email/password, social login, or anonymous access). Newly provides built-in options for Email, Google, and Apple authentication.
- Data storage: Determine what user data needs to be stored, such as profiles, settings, or app content. Database is created by Newly using our own database as a solution.
- Testing authentication: Test all flows thoroughly, including sign-up, login, password reset, and logout on web preview, iOS and Android using Expo Go. Ensure users can access and modify their data correctly. If login fails or errors appear, upload a screenshot or clearly describe which authentication method isn’t working, then ask the AI to fix it.
- Prompting the AI: Be specific when asking the AI to build or fix backend functionality. Include clear descriptions of the issue, expected behavior, and relevant screenshots. Check the info bar descriptions to understand what has been done and what caused the issue, this helps you prompt the AI more effectively.
```

### Fixing Bugs

```
Be very specifc when fixing the Bugs
- The login button isn't working on the sign-in screen. When I tap it with valid credentials, nothing happens. Expected: navigate to the home screen after successful login.
- Always the best idea to screenshot the error and upload it in the chat, and asking Newly to fix the error/issue
```

### Styling Changes

```
- Use Visual editor for most of your design changes.
- If you want to upload a design from Figma/Pinterest/or any other platforms, it is
better to give the design in the very first prompts, so the design of your app is aligned with
the backend and also when enhancing the app, design is there to help you build the app flow.
- When uploading a design, be specific if you only want the brand and color, not the sections and tabs, so that
Newly only copies the design and keeps your app structure as it is.
```

## Understanding AI Responses

As the AI works on your request, you'll see:

### Status Indicators

| Icon        | Meaning                      |
| ----------- | ---------------------------- |
| 🧠 Thinking | AI is analyzing your request |
| 📝 Writing  | Code is being generated      |
| 🔧 Building | App is being compiled        |
| ✅ Complete  | Changes are ready in preview |

### Activity Feed

The chat shows what actions the AI is taking:

* **Reading files** - Analyzing existing code
* **Writing files** - Creating or modifying code
* **Installing packages** - Adding dependencies
* **Building** - Compiling the app
* **Committing** - Saving changes to version history

<Note>
  Each commit includes a summary of what changed, making it easy to track progress and revert if needed.
</Note>

## Image-Based Prompts

You can attach images to your prompts for:

* **Design references** - "Make it look like this screenshot"
* **Bug reports** - "Here's what I'm seeing, it should show X instead"
* **Inspiration** - "Build something similar to this app"

To attach an image:

1. Click the image icon in the chat input
2. Upload or paste an image
3. Add context in your message

```
[Attached: screenshot of a competitor app]

Build a home screen similar to this but with our color scheme.
Keep the card layout but use rounded corners.
```

## Multi-Step Requests

For complex features, break them into steps:

<Steps>
  <Step title="Core Feature">
    ```
    Create a shopping cart screen that shows:
    - List of items with image, name, price
    - Quantity selector for each item
    - Total at the bottom
    ```
  </Step>

  <Step title="Add Interactions">
    ```
    Add functionality to the cart:
    - Increase/decrease quantity with +/- buttons
    - Remove item on swipe left
    - Update total automatically when quantities change
    ```
  </Step>

  <Step title="Checkout Flow">
    ```
    Add a checkout button that:
    - Validates cart is not empty
    - Shows a confirmation modal with total
    - Navigates to payment screen on confirm
    ```
  </Step>
</Steps>

<Tip>
  Breaking complex features into steps gives the AI clearer context and produces better results.
</Tip>

## Conversation Context

The AI remembers your entire conversation. Use this to your advantage:

```
User: Add a product listing screen with cards showing product images and prices.
AI: [Creates product screen]

User: Make the cards tappable and navigate to a detail page.
AI: [Adds navigation without needing to be told what cards]

User: The detail page should show the full product info.
AI: [Knows which product data to display]
```

## Asking Questions

Not every prompt needs to generate code. You can ask:

* **How does X work?** - Get explanations of features
* **What's the best way to...?** - Get recommendations
* **Can you explain this code?** - Understand generated code
* **What files were changed?** - Review recent updates

When asking questions (vs. making changes), the AI will respond with explanations without modifying code.

## Troubleshooting

### AI Not Understanding

If the AI misinterprets your request:

1. Be more specific about what you want
2. Reference/upload exact screenshot or component names
3. Describe the current vs. expected behavior

### Changes Not Appearing

If changes don't show in preview:

1. Wait for the build to complete (check status indicators)
2. Reload the preview if needed
3. Check the activity feed for errors
4. Check the app both in iOS and Android, and see if both does not show or only one, and prompt accordingly

### Reverting Changes

If something breaks:

2. Use the revert function to see version history to restore a previous commit

## Best Practices

<AccordionGroup>
  <Accordion title="Start Simple">
    Begin with core features, then add complexity. It's easier to build up than fix a complex broken system.
  </Accordion>

  <Accordion title="One Thing at a Time">
    Make one request per message for clearer results. Multi-feature requests can confuse the AI.
  </Accordion>

  <Accordion title="Test Frequently">
    Check the preview after each change via Exp Go. Catching issues early is easier than debugging later.
  </Accordion>

  <Accordion title="Use Descriptive Language">
    Instead of "button", say "blue Submit button at the bottom of the form".
  </Accordion>

  <Accordion title="Reference the Preview">
    "The third item in the list isn't showing correctly" is clearer with context from what you see.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Live Preview" icon="eye" href="/features/preview">
    Learn to use the preview effectively
  </Card>

  <Card title="Code Editor" icon="code" href="/features/code-editor">
    Edit code directly when needed
  </Card>
</CardGroup>


# Backend Systems
Source: https://docs.newly.app/features/backend

Understanding Liquid Backend and Supabase in Newly

# Backend Systems

Newly supports two backend systems for your app's server-side functionality. This guide helps you understand which one you're using and how each works.

## Which Backend Am I Using?

<Note>
  **Quick Check**: Look at the preview header in your project.

  * **See a "Database" button?** → You're using **Liquid Backend**
  * **No "Database" button?** → You're using **Supabase**
</Note>

<Tip>
  **Liquid Backend will get you further.** It's the recommended backend for most use cases. Supabase is mostly available for users that already have a website set up and are running Supabase there.
</Tip>

***

## Liquid Backend

Liquid Backend is Newly's integrated backend system. It automatically generates APIs and databases from natural language.

### What Liquid Backend Provides

<CardGroup>
  <Card title="RESTful APIs" icon="network-wired">
    Automatic API endpoint generation from natural language
  </Card>

  <Card title="PostgreSQL Database" icon="database">
    Fully managed database with automatic schema creation
  </Card>

  <Card title="Authentication" icon="key">
    User registration, login, and session management
  </Card>

  <Card title="File Storage" icon="cloud-arrow-up">
    Upload and serve images and files
  </Card>
</CardGroup>

### When Liquid Backend Is Created

The AI automatically creates backend functionality when you request:

* **User authentication** - Sign up, login, password reset
* **Data persistence** - Saving data across sessions
* **User-specific data** - Data tied to user accounts
* **API integrations** - External services requiring server-side secrets
* **AI features** - ChatGPT or other AI model integrations

### Example Prompts

```text theme={null}
Build me a journaling app, ai integrated with Google and Apple authentication
```

```text theme={null}
Create an AI financial advisor app, where I can chat and ask AI for financial advices on how to spend my money.
```

### Database Viewer

With Liquid Backend, you can view your data directly in Newly:

1. Click the **Database** icon (🗄️) in the preview header
2. Browse tables on the left sidebar
3. View records and their values

This is useful for:

* Verifying data is saving correctly
* Debugging data-related issues
* Understanding the database structure

### Logs Viewer

Liquid Backend includes a **Logs Viewer** in Newly:

1. Click the **Logs** icon in the preview header
2. Switch between "Frontend" and "Backend" tabs
3. View API calls, errors, and debug information

### Environment Variables (Liquid Backend)

For Liquid Backend projects, environment variables are managed through Liquid Backend:

* **Server-side secrets** (API keys, tokens) are stored securely in Liquid Backend
* **Frontend variables** can be added via **More** → **Environment Variables**
* Variables are automatically available to your backend code

<Warning>
  Secret keys (like `OPENAI_API_KEY`) should be stored in Liquid Backend, not exposed to the frontend.
</Warning>

### Production Deployment

When deploying your app with Liquid Backend:

<Steps>
  <Step title="Development">
    During development, you're using a dev environment backend
  </Step>

  <Step title="Push to Production">
    In the Deploy modal, click "Push to Production" for backend
  </Step>

  <Step title="Production URL">
    Your app is automatically configured to use the production API
  </Step>
</Steps>

### Dev and production data

Your project has two separate databases:

* **Dev** — your working sandbox, where you build and test. Test users and sample records you create here live only in dev.
* **Production** — a separate, permanent database that your live app uses.

When you click **Push to Production**, Newly deploys your **code and database structure (schema)** to production. It does **not** copy your dev data across. So a user you registered in dev won't appear in production, and rebuilding or restarting won't change that: the record simply isn't in the production database. This is expected, not a bug.

Production data is permanent. It starts empty and keeps everything created there, including across later deploys. That's by design, so your real users' data stays intact while you keep changing and testing in dev.

To confirm production is saving correctly, sign up or create a record in your **deployed** app, then view it via the **Database** button switched to production.

<Note>
  Deploys move your **code and schema** from dev to production, never your **dev data**. Seed anything your production app needs by creating it in production directly.
</Note>

### After a deploy, your dev database starts empty

A production deploy does two things: it promotes your code and schema to production, and it hands you a **brand-new dev environment** to keep working in. That new dev database has your latest schema and no rows in it.

Nothing was wiped. Your old dev database isn't reset — you're moved onto a fresh one. That's why a test user you registered in dev before a deploy can't log in afterwards: the account lives in the previous dev database, not the new one.

<Note>
  Dev data is disposable by design. Treat anything you create in dev as test data that a deploy will leave behind, and never as something to keep.
</Note>

### Keeping test data across deploys

Rather than re-creating test users by hand after each deploy, have the AI build the sample data into your backend. Ask for it in chat:

> Add a seed script to my backend that inserts sample data into the database — a test user and a few example records. Make it safe to run more than once, run it automatically when the backend starts in development, and also expose it as a dev-only endpoint I can trigger by hand.

A seed script that checks whether a row already exists before inserting it is safe to leave in place permanently: every fresh dev database fills itself the first time your backend boots, so your test login survives every deploy.

<Warning>
  Ask for the seed to run in **development only**. A seed that also runs in production will put fake users and sample records in your live database.
</Warning>

### Why a deploy can look like it started on its own

A production deploy only ever starts when you click **Deploy backend to production** (or run a deploy from the CLI). Two things make it look otherwise:

* **The deploy survives a page refresh.** A merge takes up to about six minutes. While it runs, the button is disabled and reads *Deploying backend…* — so opening the Deploy screen partway through a deploy you started earlier looks like a deploy that began by itself.
* **The new dev environment is provisioned for you.** Once the deploy finishes, Newly creates your replacement dev branch automatically in the background. You may see backend activity for a short while after the deploy itself is done.

If the Deploy screen shows a deploy in flight and you're sure nobody triggered one, contact support with your project link rather than clicking Deploy again.

***

## Comparison Table

| Feature                      | Liquid Backend            | Supabase                                         |
| ---------------------------- | ------------------------- | ------------------------------------------------ |
| **Database Viewer in Newly** | ✅ Yes                     | ⚠️ Project details only (use Dashboard for data) |
| **Backend Logs in Newly**    | ✅ Yes                     | ❌ No (use Dashboard)                             |
| **API Generation**           | Automatic from prompts    | Manual or via AI                                 |
| **Environment Variables**    | Managed in Liquid Backend | OAuth + manual                                   |
| **Authentication**           | Built-in                  | Supabase Auth                                    |
| **Database Access**          | Via generated REST APIs   | Direct client SDK                                |
| **Schema Management**        | AI-generated              | Supabase Dashboard                               |
| **Production Deploy**        | One-click in Newly        | Automatic (Supabase hosted)                      |
| **Realtime**                 | Websockets out of the box | Supabase Realtime                                |

***

## Supabase

Supabase is an open-source Firebase alternative that provides database, authentication, and storage. Some projects use Supabase for specific requirements.

### How Supabase Works

Unlike Liquid Backend which generates APIs automatically, Supabase provides:

1. **Direct Database Access** - Your app connects directly to PostgreSQL
2. **Supabase Client SDK** - Uses `@supabase/supabase-js` for queries
3. **Row Level Security (RLS)** - Security rules defined in Supabase Dashboard
4. **OAuth Integration** - Newly connects to your Supabase project via secure OAuth

### Connecting Supabase

Newly uses OAuth to securely connect to your Supabase project:

<Steps>
  <Step title="Open Supabase Settings">
    Click **More** → **Supabase** in the project menu
  </Step>

  <Step title="Connect via OAuth">
    Click "Connect Supabase" and sign in to your Supabase account
  </Step>

  <Step title="Authorize Access">
    Grant Newly permission to access your Supabase projects
  </Step>

  <Step title="Select Project">
    Choose your Supabase project from the list
  </Step>
</Steps>

<Tip>
  The OAuth connection handles all authentication automatically. No manual API key configuration required.
</Tip>

### Managing Your Supabase Database

The **Database** tab in Newly is relabeled **Supabase** for these projects and shows project details, secrets, and a link to the Supabase Dashboard rather than a table browser. To browse or edit your data, use:

**Supabase Dashboard** - [supabase.com/dashboard](https://supabase.com/dashboard)

* Table Editor for viewing/editing data
* SQL Editor for running queries
* Schema management

### Logs for Supabase

<Warning>
  Supabase backend logs are **not available** in Newly. You must use the Supabase Dashboard.
</Warning>

To view Supabase logs:

1. Go to [supabase.com/dashboard](https://supabase.com/dashboard)
2. Select your project
3. Navigate to **Logs** in the sidebar
4. Choose the log type:
   * **API Logs** - REST API requests
   * **Postgres Logs** - Database queries
   * **Auth Logs** - Authentication events
   * **Edge Function Logs** - Serverless function logs

<Tip>
  For frontend console logs, use the Logs icon in Newly's preview header - these are still available for all projects.
</Tip>

### Environment Variables (Supabase)

Supabase connection is handled automatically via OAuth. The OAuth integration manages your connection securely without requiring manual API key configuration.

For additional environment variables needed by your app, use **More** → **Environment Variables**.

### Supabase Features

| Feature            | How to Use                          |
| ------------------ | ----------------------------------- |
| **Database**       | Supabase Dashboard Table Editor     |
| **Authentication** | Supabase Auth (email, OAuth, phone) |
| **Storage**        | Supabase Storage buckets            |
| **Edge Functions** | Deploy via Supabase CLI             |
| **Realtime**       | Subscribe to database changes       |
| **RLS Policies**   | Define in Supabase Dashboard        |

***

## Migration

<Warning>
  **Migration from Supabase to Liquid Backend is not possible.**
</Warning>

If you need to switch backend systems, you can only migrate **from Liquid Backend to Supabase**, not the other way around.

### When to Consider Migration

In most cases, **Liquid Backend will get you further**. Consider migrating to Supabase only if you specifically need:

* PostgreSQL functions and triggers
* Supabase-specific features (Realtime subscriptions, Edge Functions)
* Integration with existing Supabase infrastructure
* Direct SQL access for complex queries

### Migration from Liquid Backend to Supabase

If you must migrate:

<Steps>
  <Step title="Export Your Data">
    Use the Database Viewer in Newly to review your data, then contact support to assist with data export
  </Step>

  <Step title="Create Supabase Project">
    Set up a new project at supabase.com
  </Step>

  <Step title="Recreate Schema">
    Create your tables in Supabase Dashboard
  </Step>

  <Step title="Import Data">
    Import your data using Supabase's import tools or SQL
  </Step>

  <Step title="Connect via OAuth">
    Follow the OAuth connection steps in Newly
  </Step>

  <Step title="Update App">
    Ask the AI to update your app to use Supabase
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="A user I created in dev isn't in production (or 'nothing saves to prod')">
    Dev and production are separate databases. Push to Production deploys your code and schema, not your dev data, so test records created in dev won't appear in production, and rebuilding won't bring them over. Create the record in your deployed (production) app and it will persist. See [Dev and production data](#dev-and-production-data).
  </Accordion>

  <Accordion title="I don't see the Database button">
    Your project uses Supabase, so that tab is labeled **Supabase** instead. Manage your actual data at [supabase.com/dashboard](https://supabase.com/dashboard).
  </Accordion>

  <Accordion title="Backend logs not showing">
    * **Liquid Backend**: Click the Logs icon and select "Backend" tab
    * **Supabase**: Logs are only available in the Supabase Dashboard
  </Accordion>

  <Accordion title="Environment variables not working">
    * **Liquid Backend**: Check Liquid Backend configuration
    * **Supabase**: Connection is managed via OAuth; additional vars in **More** → **Environment Variables**
  </Accordion>

  <Accordion title="API calls failing">
    * **Liquid Backend**: Check backend logs in Newly
    * **Supabase**: Check API logs in Supabase Dashboard
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Supabase Details" icon="database" href="/integrations/supabase">
    Deep dive into Supabase integration
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/features/deployment">
    Deploy your app to production
  </Card>
</CardGroup>


# Code Editor
Source: https://docs.newly.app/features/code-editor

View and edit generated code directly

# Code Editor

While the AI handles most coding tasks, you have full access to view and edit the generated code directly. To save the manual code changes, you have to give a prompt, so it updates and saves the changes - you can prompt something like: Update README that I was here.

## Accessing the Editor

The code editor is available in **Triple Panel** layout:

1. Click the layout toggle in the header
2. Select the three-panel layout
3. The editor appears in the middle panel

## File Browser

The left sidebar of the editor shows your project files:

```
📁 app/              # Screens and navigation
📁 components/       # Reusable UI components
📁 utils/           # Helper functions
📁 assets/          # Images and fonts
📄 app.json         # App configuration
📄 package.json     # Dependencies
```

Click any file to open it in the editor.

## Editor Features

### Syntax Highlighting

Full TypeScript/React Native syntax highlighting with:

* JSX component highlighting
* TypeScript type annotations
* Import/export statements
* String and number literals

### File Tabs

Open multiple files in tabs for easy switching between related files.

### Search

Use `Ctrl/Cmd + F` to search within the current file.

## When to Edit Manually

The AI handles most tasks, but manual editing is useful for:

<CardGroup>
  <Card title="Quick Fixes" icon="wrench">
    Minor typos or small value changes are faster to fix directly
  </Card>

  <Card title="Learning" icon="graduation-cap">
    Read the code to understand how the AI implemented features
  </Card>

  <Card title="Fine-tuning" icon="sliders">
    Adjust specific values like colors, spacing, or timing
  </Card>

  <Card title="Debugging" icon="bug">
    Add console.log statements to diagnose issues
  </Card>
</CardGroup>

## Common Manual Edits

### Adjusting Styles

```tsx theme={null}
// Change padding from 16 to 24
const styles = StyleSheet.create({
  container: {
    padding: 24, // was 16
  },
});
```

### Fixing Text

```tsx theme={null}
// Fix a typo in the UI
<Text>Submit Application</Text> // was "Sumbit"
```

### Tweaking Animations

```tsx theme={null}
// Make animation faster
Animated.timing(fadeAnim, {
  toValue: 1,
  duration: 200, // was 500
  useNativeDriver: true,
}).start();
```

### Adding Debug Logs

```tsx theme={null}
const handleSubmit = () => {
  console.log('Form data:', formData); // Debug line
  submitForm(formData);
};
```

## Saving Changes

After editing code manually:

1. You have to give a prompt, so the code changes are updated.
2. A build triggers automatically
3. Preview updates with your changes

<Note>
  Manual edits are tracked in version history just like AI changes.
</Note>

## Working with AI and Manual Edits

You can combine AI prompts with manual edits:

1. **AI generates feature** - "Add a settings screen"
2. **You fine-tune** - Adjust spacing, fix typos
3. **AI adds more** - "Add dark mode toggle to settings"

The AI sees your manual changes and works with them.

<Tip>
  Tell the AI about manual changes: "I adjusted the header padding manually. Now add a search bar below it."
</Tip>

## Understanding the Code Structure

### App Directory (Expo Router)

Newly uses [Expo Router](https://docs.expo.dev/router/introduction/) for file-based routing:

```
app/
├── index.tsx        # Home screen (/)
├── profile.tsx      # Profile screen (/profile)
├── settings.tsx     # Settings screen (/settings)
├── (tabs)/          # Tab navigator group
│   ├── _layout.tsx  # Tab configuration
│   ├── home.tsx     # Home tab
│   └── search.tsx   # Search tab
└── product/
    └── [id].tsx     # Dynamic route (/product/123)
```

### Components

Reusable UI components live in `/components`:

```tsx theme={null}
// components/Button.tsx
export function Button({ title, onPress }) {
  return (
    <TouchableOpacity onPress={onPress}>
      <Text>{title}</Text>
    </TouchableOpacity>
  );
}
```

### Utils

Helper functions and API calls in `/utils`:

```tsx theme={null}
// utils/api.ts
export async function fetchProducts() {
  const response = await fetch('/api/products');
  return response.json();
}
```

## Common Patterns

### Navigation

```tsx theme={null}
import { router } from 'expo-router';

// Navigate to a screen
router.push('/profile');

// Navigate with parameters
router.push({
  pathname: '/product/[id]',
  params: { id: '123' }
});

// Go back
router.back();
```

### State Management

```tsx theme={null}
import { useState, useEffect } from 'react';

const [items, setItems] = useState([]);
const [loading, setLoading] = useState(true);

useEffect(() => {
  fetchItems().then(data => {
    setItems(data);
    setLoading(false);
  });
}, []);
```

### API Calls

```tsx theme={null}
import Constants from 'expo-constants';

const backendUrl = Constants.expoConfig?.extra?.backendUrl;

const response = await fetch(`${backendUrl}/api/products`);
const data = await response.json();
```

## Best Practices

<AccordionGroup>
  <Accordion title="Let AI handle big changes">
    For adding features or refactoring, describe it to the AI. Manual editing is best for small tweaks.
  </Accordion>

  <Accordion title="Test after each edit">
    Always verify your manual changes work in the preview before moving on.
  </Accordion>

  <Accordion title="Keep consistent style">
    Match the existing code style when making manual edits.
  </Accordion>

  <Accordion title="Use meaningful commits">
    The AI auto-generates commit messages, but your manual edits are tracked too.
  </Accordion>
</AccordionGroup>

## Exporting Code

To work on the code locally:

<Tabs>
  <Tab title="GitHub Sync">
    1. Connect your GitHub repository
    2. Code syncs automatically
    3. Clone locally: `git clone your-repo`
    4. Install: `npm install`
    5. Run: `npx expo start`
  </Tab>

  <Tab title="Download ZIP">
    1. Click **More** → **Download ZIP**
    2. Extract the archive
    3. Open in your preferred editor
    4. Install: `npm install`
    5. Run: `npx expo start`
  </Tab>
</Tabs>

<Card title="GitHub Integration" icon="github" href="/integrations/github">
  Learn more about syncing with GitHub
</Card>

## Next Steps

<CardGroup>
  <Card title="Backend Features" icon="server" href="/features/backend">
    Understanding backend code generation
  </Card>

  <Card title="Deployment" icon="rocket" href="/features/deployment">
    Build and deploy your app
  </Card>
</CardGroup>


# App Deployment
Source: https://docs.newly.app/features/deployment

Deploy to iOS App Store and Google Play Store

# App Deployment

Newly handles the entire app deployment process, from building your app to submitting it to the App Store and Play Store.

## Deployment Options

<CardGroup>
  <Card title="APK (Android)" icon="android">
    Android installable file for testing and side-loading
  </Card>

  <Card title="AAB (Android)" icon="google-play">
    Android App Bundle for Google Play Store submission
  </Card>

  <Card title="iOS Build" icon="apple">
    iOS build for App Store submission
  </Card>

  <Card title="Backend Deploy" icon="server">
    Push backend changes to production
  </Card>
</CardGroup>

## Building for Android

### APK Build (Testing)

APK files let you install your app directly on Android devices:

<Steps>
  <Step title="Open Deploy Modal">
    Click **More** → **Deploy App** in the project header
  </Step>

  <Step title="Select APK">
    Choose "Build APK" option
  </Step>

  <Step title="Configure">
    Set your app name and icon if not already configured
  </Step>

  <Step title="Build">
    Click Build and wait for compilation (5-10 minutes)
  </Step>

  <Step title="Download">
    Download the APK file when ready
  </Step>

  <Step title="Install">
    Transfer to Android device and install
  </Step>
</Steps>

<Note>
  APKs can be shared with testers directly without going through the Play Store.
</Note>

### AAB Build (Play Store)

For Google Play Store submission, you need to have Google Developer account (\$25/lifetime):

<Steps>
  <Step title="Select AAB">
    Choose "Build AAB" in the Deploy modal
  </Step>

  <Step title="Configure App Details">
    * App name
    * Package name (e.g., `com.yourname.appname`)
    * Version number
  </Step>

  <Step title="Build">
    Wait for the AAB to compile
  </Step>

  <Step title="Download & Upload">
    Download AAB and upload to Google Play Console
  </Step>
</Steps>

<Warning>
  Package names cannot be changed after your first Play Store submission. Choose carefully!
</Warning>

## Building for iOS

iOS builds require an Apple Developer Account (\$99/year):

<Steps>
  <Step title="Apple Developer Account">
    Ensure you have an active [Apple Developer Account](https://developer.apple.com)
  </Step>

  <Step title="Select iOS Build">
    Choose "Build for iOS" in the Deploy modal
  </Step>

  <Step title="Expo Launch">
    * Migrate to Github
    * Make the Repo public
    * Copy the Repo link
    * Open Expo Launch and paste the Repo link
  </Step>

  <Step title="Enter Credentials ">
    Provide your Apple Developer credentials:

    * Apple ID
    * App-specific password (generate in Apple ID settings)
  </Step>

  <Step title="Configure App">
    * App name
    * Bundle identifier (e.g., `com.yourname.appname`)
    * Version number
  </Step>

  <Step title="Build & Submit">
    Newly builds and submits to App Store Connect
  </Step>
</Steps>

### Creating App-Specific Password

For iOS builds, you need an app-specific password:

1. Go to [appleid.apple.com](https://appleid.apple.com)
2. Sign in with your Apple ID
3. Navigate to Security → App-Specific Passwords
4. Click "Generate Password"
5. Name it "Newly" and save the generated password

### Apps That Need Special Entitlements

If your app uses a gated capability — Family Controls (Screen Time), Critical Alerts, CarPlay, clinical Health Records, or Android restricted permissions like background location — you must **apply for approval** before submitting, or the store will reject it.

<Card title="Permissions & Entitlements" icon="shield-check" href="/guides/permissions-and-entitlements">
  How to request entitlements from Apple and declare restricted permissions on Google Play.
</Card>

## App Configuration

Before building, configure your app settings:

### App Name & Icon

<Tabs>
  <Tab title="In Newly">
    1. Click **More** → **Project Settings**
    2. Update app name
    3. Upload app icon (1024x1024 recommended)
  </Tab>

  <Tab title="Via AI">
    ```
    Set the app name to "My Fitness Tracker" and use
    the icon I uploaded earlier for the app icon.
    ```
  </Tab>
</Tabs>

### App Icon Requirements

| Platform | Size      | Format                            |
| -------- | --------- | --------------------------------- |
| iOS      | 1024x1024 | PNG, no transparency              |
| Android  | 512x512   | PNG, with or without transparency |

<Tip>
  Use a simple, recognizable design that looks good at small sizes.
</Tip>

## Backend Deployment

If your app uses Liquid Backend:

<Steps>
  <Step title="Open Deploy Modal">
    Click **More** → **Deploy App**
  </Step>

  <Step title="Backend Section">
    Look for the "Backend" section in the modal
  </Step>

  <Step title="Push to Production">
    Click "Push to Production" to deploy backend changes
  </Step>

  <Step title="Verify">
    Production URL is shown when deployment completes
  </Step>
</Steps>

<Note>
  Deploying pushes your backend **code and schema** to production, not your dev data. Records created in dev stay in dev. See [Dev and production data](/features/backend#dev-and-production-data).
</Note>

<Warning>
  Deploy backend to production before submitting your app to stores. Your production app needs the production backend URL.
</Warning>

## GitHub Integration

Connect GitHub for automatic code sync:

1. Click **More** → **GitHub** in the burger menu
2. Authorize Newly to access GitHub
3. Create a new repository or select existing
4. Code syncs on each commit

Benefits:

* Full version control
* Collaborate with other developers
* Deploy to custom infrastructure
* Code backup and portability

<Card title="GitHub Integration" icon="github" href="/integrations/github">
  Learn more about GitHub setup
</Card>

## Testing Before Submission

Before submitting to app stores:

<AccordionGroup>
  <Accordion title="Test on Real Devices">
    * Download APK and test on Android phone
    * Use TestFlight for iOS testing
    * Try different screen sizes
  </Accordion>

  <Accordion title="Check All Features">
    * Test authentication flows
    * Verify data persistence
    * Check offline behavior
    * Test payments (if applicable)
  </Accordion>

  <Accordion title="Review App Store Guidelines">
    * [Apple App Store Guidelines](https://developer.apple.com/app-store/review/guidelines/)
    * [Google Play Policies](https://play.google.com/about/developer-content-policy/)
  </Accordion>
</AccordionGroup>

## App Store Submission Tips

### Apple App Store

* **Screenshots**: Required for each device size
* **Description**: Clear, accurate app description
* **Privacy Policy**: Required for all apps
* **Age Rating**: Answer questionnaire accurately
* **Review Notes**: Provide demo account if login required

### Google Play Store

* **Screenshots**: At least 2, up to 8
* **Feature Graphic**: 1024x500 banner image
* **Privacy Policy**: Link required
* **Content Rating**: Complete questionnaire
* **Target Audience**: Specify correctly

## Troubleshooting Builds

### Build Fails

<AccordionGroup>
  <Accordion title="iOS Build Errors">
    * Verify Apple ID and password are correct
    * Check app-specific password is valid
    * Ensure bundle ID is unique
    * Review build logs for specific errors
  </Accordion>

  <Accordion title="Android Build Errors">
    * Check package name format
    * Verify version code is higher than previous
    * Review Gradle/dependency errors in logs
  </Accordion>

  <Accordion title="Generic Errors">
    * Try building again (transient issues)
    * Clear build cache if available
    * Contact support via Discord
  </Accordion>
</AccordionGroup>

### App Rejection

If your app is rejected from stores:

1. Read the rejection reason carefully
2. Ask AI to help fix the issue
3. Rebuild and resubmit
4. Respond to reviewer if needed

Common rejection reasons:

* Crashes or bugs
* Incomplete functionality
* Misleading metadata
* Privacy policy issues
* Guideline violations

## Next Steps

<CardGroup>
  <Card title="GitHub Integration" icon="github" href="/integrations/github">
    Set up code syncing with GitHub
  </Card>

  <Card title="RevenueCat Payments" icon="credit-card" href="/integrations/revenuecat">
    Add in-app purchases and subscriptions
  </Card>

  <Card title="Permissions & Entitlements" icon="shield-check" href="/guides/permissions-and-entitlements">
    Apply for gated Apple entitlements and Android permissions
  </Card>
</CardGroup>


# Real-time Preview
Source: https://docs.newly.app/features/preview

See your app running live as you build

# Real-time Preview

The preview panel shows your app running in real-time, allowing you to test features and interactions as you build. We also recommend that you scan the QR code and see your mobile apps on Expo Go.

## How It Works

The preview runs your actual Expo app in a web-based environment. It's not a mockup—it's the real app with full interactivity.

<Note>
  Changes typically appear in 5-30 seconds after the AI finishes generating code, depending on complexity.
</Note>

## Preview Controls

The preview header includes several useful controls:

| Control      | Function                               | Availability                                           |
| ------------ | -------------------------------------- | ------------------------------------------------------ |
| 🔄 Reload    | Refresh the preview to the latest code | All projects                                           |
| 📱 QR Code   | Get QR code for mobile preview         | All projects                                           |
| ↔️ Layout    | Toggle between different view layouts  | All projects                                           |
| 📊 Logs      | View console logs                      | All projects (frontend); Liquid Backend only (backend) |
| 🗄️ Database | Browse database tables                 | Liquid Backend                                         |

<Note>
  **Which backend am I using?** If you see a "Database" button, you're on Liquid Backend. Otherwise, you're using Supabase. See [Backend Systems](/features/backend).
</Note>

## Testing Your App

### Navigation

* **Tap** buttons and links to navigate
* **Swipe** to go back on iOS-style navigation
* **Test tab bars** and bottom navigation

### Forms & Input

* **Text fields** accept keyboard input
* **Dropdowns and pickers** work as expected
* **Form submission** triggers your logic

### Gestures

* **Scroll** through lists and content
* **Swipe gestures** for actions like delete
* **Pull-to-refresh** where implemented

## Preview on Your Device

For the most accurate testing, preview on your actual phone via Expo Go:

<Steps>
  <Step title="Install Expo Go">
    Download **Expo Go** from the [App Store](https://apps.apple.com/app/expo-go/id982107779) or [Play Store](https://play.google.com/store/apps/details?id=host.exp.exponent)
  </Step>

  <Step title="Get QR Code">
    Click the **QR Code** icon in the preview header
  </Step>

  <Step title="Scan & Open">
    * **iOS**: Use your Camera app to scan
    * **Android**: Use Expo Go's built-in scanner
  </Step>
</Steps>

<Warning>
  Your phone must be on the same network as your computer for the preview to connect.
</Warning>

### Benefits of Device Preview

* **Accurate gestures** - Touch feels native
* **Real performance** - See actual speed and animations
* **Native features** - Test camera, notifications, etc.
* **Device differences** - Catch iOS vs Android issues

## Preview Limitations

Some features work differently in preview vs. production:

| Feature            | Preview          | Production         |
| ------------------ | ---------------- | ------------------ |
| Push Notifications | Simulated only   | Full functionality |
| Camera             | Limited support  | Full access        |
| Deep Links         | Not available    | Fully working      |
| App Icon           | Generic Expo     | Your custom icon   |
| Native Modules     | Some limitations | All features       |

<Tip>
  For features that require production testing, use the APK build for Android testing and TestFlight for iOS testing before deployment to App Store and Play Store.
</Tip>

## Viewing Logs

Click the **Logs** icon to see console output from your app.

### Frontend Logs (All Projects)

Frontend logs are available for all projects:

* **Console.log messages** from your code
* **Errors and warnings** for debugging
* **Network requests** showing API calls
* **React Native logs** for deeper debugging

### Backend Logs

<Tabs>
  <Tab title="Liquid Backend">
    Backend logs are available in Newly:

    1. Click the **Logs** icon in the preview header
    2. Switch to the **Backend** tab
    3. View API calls, errors, and server logs
  </Tab>

  <Tab title="Supabase">
    <Warning>
      **Backend logs are not available in Newly for Supabase projects.**
    </Warning>

    View Supabase logs in the Supabase Dashboard:

    1. Go to [supabase.com/dashboard](https://supabase.com/dashboard)
    2. Select your project
    3. Click **Logs** in the sidebar
    4. Choose: API Logs, Postgres Logs, Auth Logs, or Edge Function Logs
  </Tab>
</Tabs>

### Using Logs for Debugging

When something isn't working:

1. Open the logs panel
2. Reproduce the issue in the preview
3. Look for error messages or unexpected values
4. Share log content with the AI for help

```
The add to cart button logs "undefined" when I tap it.
Here's what I see in the logs:
[Error log content]
```

## Database Viewer

<Tabs>
  <Tab title="Liquid Backend">
    The Database Viewer lets you inspect your data directly in Newly:

    * **Browse tables** - See all your data tables
    * **View records** - Inspect individual entries
    * **Verify data** - Confirm your app is saving correctly

    Click the **Database** icon (🗄️) in the preview header to open it.
  </Tab>

  <Tab title="Supabase">
    When your project is connected to Supabase, the **Database** tab is relabeled **Supabase** and shows your project details, secrets, and a link to open the Supabase Dashboard — instead of Newly's table browser.

    To browse and edit your actual data, use the Supabase Dashboard:

    1. Go to [supabase.com/dashboard](https://supabase.com/dashboard)
    2. Select your project
    3. Use the **Table Editor** to view and edit data
    4. Use the **SQL Editor** for queries
  </Tab>
</Tabs>

## Layout Options

Switch between different layout modes:

### Dual Panel

* **Chat** on the left
* **Preview** on the right
* Best for focused development

### Triple Panel (Code Visible)

* **Chat** on the left
* **Code Editor** in the middle
* **Preview** on the right
* Best when editing code directly

### Mobile View

On smaller screens, toggle between chat and preview with the bottom tab bar.

## Troubleshooting Preview

<Warning>
  **Using OneSignal (push notifications) or other native-only packages?** The web preview won't work — you need to build for a native simulator instead. See our [step-by-step guide](/guides/preview-troubleshooting) to fix this.
</Warning>

### Preview Not Loading

<AccordionGroup>
  <Accordion title="Shows blank or loading indefinitely">
    1. Click the **Reload** button
    2. Check if build is still in progress (status indicators)
    3. Try a hard refresh of the browser page
    4. If your app uses native-only packages like OneSignal (push notifications), see [My Project is Stuck on Loading Preview](/guides/preview-troubleshooting) for how to build for a native simulator instead
  </Accordion>

  <Accordion title="Shows error screen">
    1. Read the error message for clues
    2. Check the logs for more details
    3. Ask the AI to fix the issue
  </Accordion>

  <Accordion title="QR code not connecting">
    1. Ensure phone and computer are on same network
    2. Check if VPN is blocking connection
    3. Try closing and reopening Expo Go
  </Accordion>
</AccordionGroup>

### Changes Not Appearing

<AccordionGroup>
  <Accordion title="Code changed but preview unchanged">
    1. Wait for build to complete
    2. Click Reload button
    3. Check for build errors in activity feed
  </Accordion>

  <Accordion title="State seems stale">
    Sometimes preview state persists. Reload the preview for a fresh start.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup>
  <Card title="Test Early and Often" icon="vial">
    Check the preview after each AI response to catch issues quickly
  </Card>

  <Card title="Use Device Preview" icon="mobile">
    Test on your actual phone for critical features and before deployment
  </Card>

  <Card title="Check Both Platforms" icon="arrows-left-right">
    iOS and Android can behave differently—test both if possible
  </Card>

  <Card title="Monitor Logs" icon="terminal">
    Keep logs open to catch errors and debug issues faster
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Code Editor" icon="code" href="/features/code-editor">
    Edit code directly for fine-tuned control
  </Card>

  <Card title="Deployment" icon="rocket" href="/features/deployment">
    Deploy your tested app to stores
  </Card>
</CardGroup>


# App Store Screenshots
Source: https://docs.newly.app/features/screenshot-editor

Turn a raw app screenshot into polished, store-ready App Store screenshots with AI

# App Store Screenshots

The **Screenshot Editor** turns a plain screenshot of your app into a set of
polished, marketing-ready App Store images — device frame, background, brand
accent, and headline copy included. Upload (or capture) a screen, add a
headline, pick a brand color, and Newly generates four professionally-styled
layouts for every screen. You can download them or publish them straight to
App Store Connect.

<Note>
  Everything stays inside your project. Screenshots, copy, and brand color are
  scoped to the project, and your source pixels aren't stored permanently.
</Note>

## Opening the editor

The Screenshot Editor lives in the right-hand **tool strip** of your project,
in the distribution group next to **Deploy**. Click the **Screenshots**
(camera) icon to open the panel.

<Note>
  You need **edit** access to the project to upload, generate, and publish. If
  you don't see the Screenshots icon, the feature may not be enabled for
  your account yet — reach out on [Discord](https://discord.com/invite/sPbqWqgcMf).
</Note>

The panel walks you through four steps, top to bottom.

## Walkthrough

<Steps>
  <Step title="01 — Configure target">
    Pick the **device** you're creating screenshots for. Newly sets the
    exact pixel dimensions the store expects for that device — there's
    nothing else to size manually.

    | Device                         | Size | Dimensions |
    | ------------------------------ | ---- | ---------- |
    | iPhone 17 Pro Max / 16 Pro Max | 6.9″ | 1320×2868  |
    | iPhone Air / 16 Plus           | 6.7″ | 1290×2796  |
    | iPhone 17 Pro / 16 Pro         | 6.3″ | 1206×2622  |
    | iPhone 17 / 16                 | 6.1″ | 1179×2556  |
    | iPad Pro 13″                   | 13″  | 2064×2752  |
    | iPad Pro 11″                   | 11″  | 1668×2388  |
    | iPad mini                      | 8.3″ | 1488×2266  |

    <Tip>
      Start with **iPhone 6.9″ (1320×2868)**. It's the size App Store
      Connect requires for the primary iPhone screenshot set, and it's the
      one that can be published directly from Newly (see
      [Publishing](#publishing-to-app-store-connect)).
    </Tip>
  </Step>

  <Step title="02 — Add your screenshots">
    Get your app screens into the editor two ways:

    * **Upload** — click **Upload** or drag a file onto the drop zone. PNG or
      JPG only, up to 10 MB each.
    * **Capture from preview** — when you're previewing on an iOS or
      Android **simulator**, click **Capture from preview** to grab the current
      screen with no round-trip. (Not available on web or physical-device
      preview.)

    Add up to **6** screens per run. Click any screen's row to edit its
    marketing copy:

    * **Headline** — the big line, e.g. *"Track every workout"*
    * **Subhead** — the supporting line beneath it

    <Tip>
      Keep headlines to a few punchy words. They're rendered large over the
      background, so short copy reads best on a phone-sized listing thumbnail.
    </Tip>
  </Step>

  <Step title="03 — Choose a brand color">
    The brand color drives the AI-generated background and accent. Choose
    **Auto** to let Newly pull a palette from your screenshot, pick one of the
    presets (Sienna, Purple, Blue, Green, Red, Amber, Pink, Ink), or paste a
    custom hex value to match your brand exactly.
  </Step>

  <Step title="04 — Generate, preview & download">
    Click **Generate variants**. Newly generates **four layouts for every
    screen** you added:

    | Layout        | Style                                                        |
    | ------------- | ------------------------------------------------------------ |
    | **Classic**   | Phone large and centered, subtle drop shadow                 |
    | **Editorial** | Phone tilted slightly, copy left-aligned beside it           |
    | **Magazine**  | Phone offset to one side, copy on the other — editorial feel |
    | **Floating**  | Phone elevated with a large perspective shadow               |

    Generation runs in the background (typically a couple of minutes) and
    previews stream in as each image finishes. When it's done you can
    **Download** any single image or **Download all** as a ZIP.

    <Note>
      All four layouts are always generated for each screen — you pick your
      favorites afterward rather than choosing a template up front.
    </Note>
  </Step>
</Steps>

## Publishing to App Store Connect

If you've connected your Apple account in **Deploy**, you can skip the
manual upload entirely. Click **Publish to App Store**, select the images you
want in the gallery, and Newly uploads them to your app's screenshot set in
App Store Connect.

<Warning>
  Direct publishing currently supports the **iPhone 6.9″ (1320×2868)** set
  only, up to **10 screenshots**. Generate on that device to publish directly;
  for other sizes, download the images and upload them in App Store Connect
  manually.
</Warning>

If Apple isn't connected yet, the button reads **Connect Apple to
Publish** — set up your App Store Connect API key in
[Deploy settings](/subscriptions/app-store-connect-setup) first.

## Credits & limits

* **1 prompt per image.** A run costs `screens × 4` prompts — e.g. 2 screens =
  8 prompts. You're told up front if you don't have enough.
* **Up to 6 screens** per generation run; each run produces all 4 layouts.
* **Uploads:** PNG or JPG, max 10 MB per file.
* **Download links expire after 24 hours** — save anything you want to keep.
* A **Stale** badge appears if you change settings after generating. Hit
  **Generate variants** again to refresh.

## Tips for great screenshots

<AccordionGroup>
  <Accordion title="Capture clean source screens">
    Generate against the real content your users will see — a populated list, a
    finished chart, a completed profile. Newly frames and styles the screen
    exactly as provided; it doesn't redraw your UI.
  </Accordion>

  <Accordion title="Lead with your best screen">
    App Store listings show the first two screenshots in search results. Put
    your strongest screen and clearest headline first.
  </Accordion>

  <Accordion title="Use a consistent brand color">
    Pick one hex value and reuse it across every screen so the whole set feels
    like one campaign rather than four unrelated images.
  </Accordion>

  <Accordion title="Why does it always make four layouts?">
    Every screen gets Classic, Editorial, Magazine, and Floating so you can
    compare framings side by side and keep the ones that fit your app — no need
    to guess a template before you generate.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="App Deployment" icon="rocket" href="/features/deployment">
    Build and submit your app to the App Store and Play Store
  </Card>

  <Card title="App Store Connect Setup" icon="apple" href="/subscriptions/app-store-connect-setup">
    Connect your Apple account so you can publish directly
  </Card>
</CardGroup>


# Adding Authentication
Source: https://docs.newly.app/guides/adding-authentication

Add user accounts and login to your app

# Adding Authentication

This guide walks you through adding user authentication to your app, allowing users to create accounts, log in, and access their personal data.

## What You'll Build

* Sign up with email and password
* Log in to existing account
* Persistent login sessions
* Protected routes (only accessible when logged in)
* Logout functionality

## Step 1: Add Auth Screens

Start by asking the AI to create the authentication UI:

```
Add authentication to my app:

1. Create a Login screen with:
   - Email input field
   - Password input field
   - "Sign In" button
   - "Don't have an account? Sign up" link at bottom

2. Create a Sign Up screen with:
   - Email input field
   - Password input field
   - Confirm password field
   - "Create Account" button
   - "Already have an account? Sign in" link

Use the app's existing color scheme and design language.
```

## Step 2: Connect to Backend

Now add the backend authentication logic:

```
Connect the auth screens to the backend:

- When signing up:
  - Validate email format
  - Ensure passwords match
  - Create user account
  - Automatically log in after signup
  - Navigate to home screen

- When logging in:
  - Validate credentials
  - Show error if invalid
  - Navigate to home screen on success
  - Keep user logged in across app restarts
```

<Note>
  This creates the necessary API endpoints in Liquid Backend: `/api/auth/register`, `/api/auth/login`, and `/api/auth/me`.
</Note>

## Step 3: Protect Routes

Make certain screens require authentication:

```
Add authentication protection:
- If user is not logged in, show the Login screen
- After logging in, show the Home screen
- The user should not be able to access Home without logging in
- Check auth status when app launches
```

## Step 4: Add Logout

Add a way for users to sign out:

```
Add a logout button in the Settings screen:
- When tapped, show a confirmation: "Are you sure you want to log out?"
- On confirm, clear the session and return to Login screen
- On cancel, stay on Settings
```

## Step 5: Add User Profile

Show user information in the app:

```
Add a Profile screen that shows:
- User's email address
- Account creation date
- "Edit Profile" button (placeholder for now)
- Logout button at the bottom

Navigate to Profile from a user icon in the header.
```

## Testing Your Auth Flow

Test the complete flow:

<Steps>
  <Step title="Sign Up">
    Create a new account with test credentials
  </Step>

  <Step title="Verify Login">
    After signup, you should be on the home screen
  </Step>

  <Step title="Test Persistence">
    Reload the preview - you should still be logged in
  </Step>

  <Step title="Logout">
    Sign out and verify you're back at login
  </Step>

  <Step title="Login Again">
    Log in with your test credentials
  </Step>
</Steps>

## Common Authentication Patterns

### Showing Auth Status

```
Show the user's name in the header when logged in.
If no name is set, show their email instead.
```

### Forgot Password

```
Add a "Forgot Password?" link on the login screen.
When tapped, show a screen where users enter their email
to receive a password reset link.
```

### Social Login

```
Add "Sign in with Google" and "Sign in with Apple" buttons
below the email/password form.
```

<Warning>
  Social login requires additional configuration in Liquid Backend and the respective provider consoles (Google Cloud, Apple Developer).
</Warning>

<Card title="Apple & Google Login with Supabase" icon="fingerprint" href="/guides/supabase-social-login">
  Using Supabase as your backend? Follow the step-by-step walkthrough for Sign in with Apple and Google.
</Card>

## User-Specific Data

Once authentication is set up, associate data with users:

```
Update the tasks feature so each user only sees their own tasks.
When creating a task, automatically associate it with the current user.
When fetching tasks, only return the current user's tasks.
```

## Best Practices

<CardGroup>
  <Card title="Validate Input" icon="check">
    Check email format and password strength
  </Card>

  <Card title="Clear Error Messages" icon="message">
    Tell users exactly what went wrong
  </Card>

  <Card title="Loading States" icon="spinner">
    Show loading indicators during auth operations
  </Card>

  <Card title="Secure Storage" icon="lock">
    Auth tokens are stored securely automatically
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Login fails with valid credentials">
    * Check the backend logs for errors
    * Verify the account was created successfully
    * Try creating a new account
  </Accordion>

  <Accordion title="Session not persisting">
    * Tell the AI: "The login session is not persisting across app restarts"
    * Verify secure storage is being used correctly
  </Accordion>

  <Accordion title="Can't access protected screens">
    * Check the auth state logic
    * Verify the auth check runs on app launch
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Connect Database" icon="database" href="/guides/connecting-database">
    Store user-specific data
  </Card>

  <Card title="Add Payments" icon="credit-card" href="/guides/adding-payments">
    Monetize with subscriptions
  </Card>
</CardGroup>


# Adding Payments
Source: https://docs.newly.app/guides/adding-payments

Monetize your app with subscriptions and purchases

# Adding Payments

This guide walks you through adding in-app purchases and subscriptions to your app using RevenueCat.

## Prerequisites

Before adding payments:

1. **Apple Developer Account** - Required for iOS purchases (\$99/year)
2. **Google Play Developer Account** - Required for Android (\$25 one-time)
3. **RevenueCat Account** - Free to start at [revenuecat.com](https://www.revenuecat.com)

<Card title="RevenueCat Integration" icon="credit-card" href="/integrations/revenuecat">
  Set up RevenueCat connection first
</Card>

## Step 1: Define Your Offering

Decide what you're selling:

<Tabs>
  <Tab title="Subscription">
    Recurring payments for ongoing access:

    * Monthly: \$9.99/month
    * Yearly: \$79.99/year (save 33%)
  </Tab>

  <Tab title="One-time Purchase">
    Single payment for permanent access:

    * Pro Upgrade: \$29.99 (remove ads forever)
  </Tab>

  <Tab title="Consumable">
    Single-use purchases:

    * 100 Credits: \$4.99
    * 500 Credits: \$19.99
  </Tab>
</Tabs>

## Step 2: Create Products in App Stores

<Steps>
  <Step title="App Store Connect (iOS)">
    1. Go to your app → Subscriptions
    2. Create a subscription group
    3. Add products with prices
    4. Submit for review
  </Step>

  <Step title="Google Play Console (Android)">
    1. Go to Monetization → Products → Subscriptions
    2. Create subscription products
    3. Set prices and billing periods
    4. Activate the products
  </Step>

  <Step title="RevenueCat Dashboard">
    1. Add your app to RevenueCat
    2. Configure store credentials
    3. Import products from stores
    4. Create entitlements (what users get access to)
  </Step>
</Steps>

## Step 3: Add Paywall to Your App

Ask the AI to create a paywall:

```
Create a premium subscription feature:

1. Create a paywall screen that shows:
   - App logo at the top
   - "Unlock Premium" heading
   - List of premium features with checkmarks
   - Monthly option: $9.99/month
   - Yearly option: $79.99/year (highlighted as "Best Value")
   - "Start Free Trial" button (7-day trial)
   - "Restore Purchases" link at bottom
   - Terms and Privacy links

2. When user taps a subscription option:
   - Show the system purchase dialog
   - Handle success: unlock premium, navigate to home
   - Handle failure: show error message

Use RevenueCat for payment processing.
```

## Step 4: Gate Premium Features

Lock features behind the subscription:

```
Make these features premium-only:
- AI chat (free users get 5 messages/day)
- Custom themes
- Cloud sync
- Remove ads

When a non-subscriber tries to access these features:
- Show a brief preview or explanation
- Display "Upgrade to Premium" button
- Tapping it navigates to the paywall screen
```

## Step 5: Check Subscription Status

The AI will generate code to check access:

```tsx theme={null}
// Example generated code
import Purchases from 'react-native-purchases';

const checkPremiumAccess = async () => {
  const customerInfo = await Purchases.getCustomerInfo();
  return customerInfo.entitlements.active['premium'] !== undefined;
};
```

### Show Status in UI

```
In the settings screen, show the user's subscription status:
- If subscribed: "Premium Member" with renewal date
- If not subscribed: "Free Plan" with upgrade button
```

## Step 6: Handle Restore Purchases

Important for returning users:

```
Add a "Restore Purchases" function:
1. Place it in Settings and on the paywall
2. When tapped, check for existing purchases
3. If found, restore access and show success message
4. If not found, show "No purchases to restore"
```

## Testing Purchases

<Warning>
  Never use real purchases during development. Always use sandbox/test accounts.
</Warning>

### iOS Sandbox Testing

1. Create Sandbox Apple ID in App Store Connect
2. Sign out of App Store on test device
3. Sign in with Sandbox account when making test purchase
4. Sandbox subscriptions renew quickly for testing

### Android Test Purchases

1. Add email as license tester in Play Console
2. Sign in with that account on test device
3. You'll see "(test)" badge on purchase dialogs
4. No real charges are made

## Subscription States

Handle different subscription states:

```
Handle these subscription scenarios:
- Active subscription: Show premium features
- Expired subscription: Show paywall with "Renew" messaging
- In free trial: Show "X days left in trial" banner
- Cancelled but still active: Show "Subscription ending on [date]"
```

## Best Practices

<CardGroup>
  <Card title="Clear Value First" icon="star">
    Show what premium offers before asking to pay
  </Card>

  <Card title="Offer Free Trial" icon="gift">
    Let users try before buying
  </Card>

  <Card title="Easy Restore" icon="rotate">
    Make restore purchases easily accessible
  </Card>

  <Card title="Transparent Pricing" icon="tag">
    Show prices clearly, no hidden fees
  </Card>
</CardGroup>

## App Store Requirements

Both stores have strict requirements:

### Apple App Store

* Digital goods MUST use Apple IAP
* Clearly state renewal terms
* Link to terms of service
* No external payment links

### Google Play Store

* Digital goods MUST use Google Play Billing
* Subscription terms visible before purchase
* Easy access to cancellation
* Clear pricing display

## Analytics and Revenue

Track your revenue in RevenueCat dashboard:

* Monthly Recurring Revenue (MRR)
* Active subscribers
* Trial conversions
* Churn rate
* Revenue by product

## Troubleshooting

<AccordionGroup>
  <Accordion title="Purchase not completing">
    * Verify products are approved in stores
    * Check RevenueCat configuration
    * Ensure correct product IDs
    * Test with sandbox account
  </Accordion>

  <Accordion title="Entitlement not granted">
    * Check RevenueCat dashboard for purchase
    * Verify entitlement linked to product
    * Check webhook configuration
  </Accordion>

  <Accordion title="Restore not finding purchases">
    * Same store account required
    * Check if subscription expired
    * Verify sandbox vs production
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Deploy Your App" icon="rocket" href="/features/deployment">
    Submit to app stores
  </Card>

  <Card title="RevenueCat Details" icon="credit-card" href="/integrations/revenuecat">
    Advanced RevenueCat features
  </Card>
</CardGroup>


# App Store Submission, Step by Step
Source: https://docs.newly.app/guides/app-store-submission

A start-to-finish walkthrough for publishing your app to the Apple App Store and Google Play Store, in the order you actually do things.

This is the one page that walks you through submission **in order**, from "I have a finished app" to "it's live in the store." If you've never shipped an app before, follow it top to bottom.

There are two separate submissions — **iOS (Apple App Store)** and **Android (Google Play Store)**. They're independent. You can do one, the other, or both. Each has its own developer account, its own build, and its own review.

<Note>
  Set aside time. Getting the accounts approved and the first build through review usually takes a few days end to end — most of that is waiting on Apple/Google, not work on your side. This is normal. You are not stuck.
</Note>

## Before you start (both platforms)

Do these once, before you touch either store. They apply to iOS and Android alike.

<Steps>
  <Step title="Finish and test your app">
    Submission is not the time to discover bugs. Test the real flows on a real device — sign-up/login, the main features, payments if you have them. See [Preview vs Builds](/guides/preview-vs-builds) for how a store build differs from the preview.
  </Step>

  <Step title="Set your app name and icon">
    In Newly: **More → Project Settings**. Upload a **1024×1024 PNG icon (no transparency for iOS)** and set the final app name. See [Deployment → App Configuration](/features/deployment#app-configuration).
  </Step>

  <Step title="Deploy your backend to production (if you use Liquid Backend)">
    Open the **Deploy** modal → **Backend** section → **Push to Production**. Your production app must point at the production backend, so do this *before* you build the app you'll submit. Details: [Backend deployment](/features/deployment#backend-deployment).
  </Step>

  <Step title="Have a privacy policy URL ready">
    Both stores require a public privacy policy link for essentially every app. Have the URL on hand before you start the listing.
  </Step>

  <Step title="Check for special entitlements — apply EARLY">
    If your app uses a gated capability (Family Controls / Screen Time, Critical Alerts, CarPlay, clinical Health Records, or Android restricted permissions like background location), you must **apply for approval before submitting** or the store will reject you. This approval can take time, so start it now. See [Permissions & Entitlements](/guides/permissions-and-entitlements).
  </Step>
</Steps>

***

## iOS — Apple App Store

### Step 1 — Enroll in the Apple Developer Program

You need a paid **[Apple Developer Program](https://developer.apple.com/programs/enroll/)** membership — **\$99/year**. A free Apple ID is not enough. Enrollment can take anywhere from a few hours to a couple of days for Apple to approve, so do this first.

### Step 2 — Open the Deploy modal and start an iOS build

In your Newly project, click **Deploy**, then **Build & Deploy**, and select **iOS**. The Apple Credentials section appears.

### Step 3 — Connect your Apple account

Use **Automatic setup** (recommended):

1. Enter your **Apple ID** email and password.
2. Complete **two-factor authentication** when prompted.
3. **Select your team** from your Apple account.
4. Newly **auto-provisions the required keys** — you'll see a checkmark appear for each one.
5. **Select or create your app** — Newly pre-fills the name and bundle ID from your project.

Prefer to manage your own keys? Use **Manual setup** instead. Full detail on both paths, and what each key is for, is in [App Store Connect Setup](/subscriptions/app-store-connect-setup).

<Tip>
  You only connect your Apple account once. Credentials are stored encrypted and reused across all your Newly projects.
</Tip>

### Step 4 — Confirm your app details

Before building, confirm:

* **App name**
* **Bundle identifier** (e.g. `com.yourname.appname`) — [changing it later is a two-step process](/guides/bundle-id-changes), so get it right now
* **Version number**

### Step 5 — Build and submit

Click **Build**. Newly compiles your app (typically 5–15 minutes) and **submits the build to App Store Connect** automatically. When it finishes, the build shows up in your App Store Connect account.

### Step 6 — Test with TestFlight (recommended)

Once the build lands in App Store Connect, install it via **TestFlight** on a real iPhone and run through everything one more time. Catching a crash here is free; catching it in review costs you days.

### Step 7 — Fill out your App Store listing

In [App Store Connect](https://appstoreconnect.apple.com), open your app and complete the listing. This is the part people forget is separate from the build:

* **Screenshots** — required for each required device size
* **Description** — clear and accurate; don't oversell features you don't have
* **Keywords**
* **Privacy Policy URL**
* **App Privacy questionnaire** — declare what data you collect
* **Age rating** — answer the questionnaire honestly
* **Review notes** — **if your app requires login, provide a working demo account** (username + password). Missing demo credentials is one of the most common rejection reasons.

<Tip>
  Newly's Marketing Studio can help generate store screenshots. See [Marketing Studio](/features/marketing-studio).
</Tip>

### Step 8 — Submit for review

Attach your build to the version and click **Submit for Review**. Apple review typically takes **1–3 days**.

### Step 9 — Respond to the result

* **Approved** → release it (immediately or on a date you choose). 🎉
* **Rejected** → read the reason carefully. Most rejections are fixable: paste the reason to the AI in Newly, fix it, rebuild, and resubmit. You can also reply to the reviewer in the Resolution Center. See [Handling rejections](#handling-rejections) below.

***

## Android — Google Play Store

### Step 1 — Create a Google Play Developer account

Sign up for a **[Google Play Developer account](https://play.google.com/console/signup)** — a **one-time \$25** fee. Google verifies your identity, which can take a day or two.

### Step 2 — Deploy your backend to production

Same as iOS — if you use Liquid Backend, push it to production before building. See [Backend deployment](/features/deployment#backend-deployment).

### Step 3 — Confirm your app details and build an AAB

In the **Deploy** modal, choose **Build AAB** (the Android App Bundle is the format the Play Store requires). Confirm:

* **App name**
* **Package name** (e.g. `com.yourname.appname`)
* **Version number**

<Warning>
  Your package name **cannot be changed after your first Play Store submission**. Choose it carefully.
</Warning>

Wait for the AAB to compile, then **download** it.

### Step 4 — Create your app in the Play Console and upload the AAB

In the [Google Play Console](https://play.google.com/console), create a new app, then upload your downloaded **.aab** file to a release (start with Internal testing if you want to trial it first, or Production to go live).

### Step 5 — Complete your store listing

Play requires more listing pieces than most people expect:

* **Screenshots** — at least 2 (up to 8)
* **Feature graphic** — a 1024×500 banner image
* **App icon** — 512×512 PNG
* **Short and full description**
* **Privacy Policy URL**
* **Content rating** — complete the questionnaire
* **Target audience** — specify correctly
* **Data safety form** — declare what data you collect and how it's used

### Step 6 — Submit for review

Roll out the release and submit. Google review times vary — often a day or two, but first submissions from a new account can take longer.

***

## Pre-submission checklist

Run through this before you hit submit on either store:

<AccordionGroup>
  <Accordion title="Accounts & money">
    * Apple Developer Program active (\$99/yr) — for iOS
    * Google Play Developer account active (\$25 once) — for Android
  </Accordion>

  <Accordion title="The app itself">
    * Tested on a real device (TestFlight for iOS)
    * Final app name and icon set
    * Correct bundle ID / package name (these are hard to change later)
    * Version number set
    * Backend pushed to production (if using Liquid Backend)
    * Any special entitlements already approved
  </Accordion>

  <Accordion title="The store listing">
    * Screenshots for all required sizes
    * Description, keywords/short description
    * Privacy policy URL live and reachable
    * Age / content rating completed
    * Privacy / data-safety questionnaire completed
    * Demo account provided in review notes (if login is required)
  </Accordion>
</AccordionGroup>

***

## Handling rejections

A rejection is routine — plenty of apps are rejected on the first try. It's not the end.

1. Read the exact reason the store gives you.
2. Paste that reason to the AI in Newly and ask it to help fix the issue.
3. Rebuild and resubmit.
4. If you disagree or need to clarify, reply to the reviewer (Apple's Resolution Center / Play's policy contact).

The most common causes:

* Crashes or bugs during review
* Incomplete or broken functionality
* **No working demo account** for a login-gated app
* Missing or unreachable privacy policy
* Misleading metadata / screenshots
* Guideline or policy violations

More detail: [Deployment → Troubleshooting & rejections](/features/deployment#app-rejection).

***

## Related

<CardGroup>
  <Card title="App Deployment" icon="rocket" href="/features/deployment">
    Reference for how Newly builds and ships your app
  </Card>

  <Card title="App Store Connect Setup" icon="apple" href="/subscriptions/app-store-connect-setup">
    Connecting your Apple account and keys in depth
  </Card>

  <Card title="Permissions & Entitlements" icon="shield-check" href="/guides/permissions-and-entitlements">
    Apply for gated Apple entitlements and Android permissions
  </Card>

  <Card title="Changing your Bundle ID" icon="tag" href="/guides/bundle-id-changes">
    The two-step update if you rename your bundle ID
  </Card>

  <Card title="Marketing Studio" icon="wand-magic-sparkles" href="/features/marketing-studio">
    Generate store screenshots and marketing assets
  </Card>

  <Card title="Preview vs Builds" icon="mobile" href="/guides/preview-vs-builds">
    How a store build differs from the in-app preview
  </Card>
</CardGroup>


# Changing your bundle ID
Source: https://docs.newly.app/guides/bundle-id-changes

If you rename your bundle ID and your iOS build still uses the old one, here's the two-step update that keeps everything in sync.

Renaming your iOS bundle ID is two steps, not one. Doing only the first step is the most common cause of *"my app.json says `com.newname.app` but the build still shows `com.oldname.app`"* errors.

This guide walks through both steps in the Newly UI.

## Why it's two steps

Your bundle ID is referenced in two places:

1. *Your project's Apple credentials* (stored on Newly's side). EAS reads this when building.
2. *OneSignal's APNs platform config* (if you've connected push notifications). OneSignal sends notifications to the bundle ID it has on file.

Saving a new bundle ID in the first place doesn't automatically push it to the second. So OneSignal can keep using the old bundle ID even after your project, app.json, and EAS build are all on the new one.

## The two-step update

<Steps>
  <Step title="Update the Bundle ID in Apple Credentials → Team Info">
    Open your project, go to the **Deploy** tab on the right, and find the Apple Credentials section. Click into the **Team Info** step. (The same step is also reachable from the OneSignal panel and the Compliance card on the Deploy page – they all lead to the same form.)

    Change the **Bundle ID** field to your new value and click **Save**.

    What this does behind the scenes:

    * Updates the bundle ID in your project's Apple credentials on our side
    * Writes the new value into your project's `app.json` under `ios.bundleIdentifier`

    Your repo and our database are in sync after this step. EAS builds triggered from now on will use the new bundle ID.
  </Step>

  <Step title="Push the new bundle ID to OneSignal's APNs config">
    Only needed if you have OneSignal connected. Skip this step if your project doesn't use push notifications.

    Open the OneSignal panel (**More** → **Push Notifications**) and click **Configure platforms**.

    This re-pushes the current bundle ID to OneSignal's APNs platform config. Without this step, OneSignal keeps the old `apns_bundle_id` baked in and your notifications won't deliver to the new app identifier.

    *Alternative:* clicking **Disconnect** then **Connect OneSignal** again does the same thing – reconnecting always calls Configure platforms automatically.
  </Step>

  <Step title="Trigger a fresh iOS build">
    From the Deploy tab, trigger a new iOS build. It will use the new bundle ID for the EAS credentials prep, the Apple submission, and (if applicable) the OneSignal APNs platform.
  </Step>
</Steps>

## How to check that both sides are in sync

After step 2, you can verify both pieces:

* *In Newly:* open your `app.json` from the file tree and confirm `ios.bundleIdentifier` matches what you intended.
* *In OneSignal:* (optional) open your OneSignal dashboard for this app, go to **Settings → Apple iOS (APNs)**, and check the bundle ID listed there matches.

If the EAS build still emits log lines like *"Linking bundle identifier oldvalue"*, the Apple credentials side wasn't saved cleanly. Re-do step 1 and confirm the save lands.

## A note on bundle ID format

iOS accepts any reverse-domain bundle ID (`com.yourname.app`, `fun.example.app`, etc.).

For Android AAB builds specifically, the build flow currently accepts any reverse-domain package name, but earlier versions required the `com.*` prefix. If you're on a brand-new project, you can pick anything. If you're upgrading an older project and the AAB build rejects your package name, ask the AI to update `android.package` in `app.json` to a `com.*` value and try again.

## Related

* [OneSignal Integration](/integrations/onesignal) – full setup for push notifications.
* [Deployment](/features/deployment) – how Newly builds and ships your app.


# Cancel your subscription
Source: https://docs.newly.app/guides/cancel-subscription



You want to stop your monthly billing or request a refund for your Newly subscription.

## Quick answer

Go to [**newly.app/pricing**](https://newly.app/pricing), select **Billing & Invoices** (or the **Plans** tab), and cancel your plan from there. Your access remains active until the end of your current billing cycle.

## Refund policy

As per our [terms](https://newly.app/terms) we process refunds only if you have used less than 5% of your monthly AI prompts. For example, on the standard plan (50 prompts per month), you are not eligible for a refund if you have used more than 2 prompts.

## If that didn't work

If the billing button does not load or you cannot access the pricing page, reach out to support with your account email and we will process the cancellation manually.


# Connecting a Database
Source: https://docs.newly.app/guides/connecting-database

Store and retrieve data in your app

# Connecting a Database

This guide explains how to store, retrieve, and manage data in your Newly app using the built-in Liquid Backend.

## When You Need a Database

You need a database when:

* Data should persist across app restarts
* Data should sync across devices
* Users need their own personal data
* You're building any CRUD application

## Basic Data Storage

### Creating a Simple Feature

Let's build a notes app to demonstrate database concepts:

```
Create a notes app where users can:
- View a list of their notes
- Tap a note to see full content
- Create new notes with title and content
- Edit existing notes
- Delete notes

Store notes in the database so they persist.
Each user should only see their own notes.
```

<Note>
  When you request data persistence, Liquid Backend automatically creates the necessary database tables and API endpoints.
</Note>

## Understanding the Data Model

### How the AI Creates Tables

The AI analyzes your request and creates an appropriate schema:

```sql theme={null}
-- Example generated table for notes
CREATE TABLE notes (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT NOT NULL,
  title TEXT NOT NULL,
  content TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);
```

### Being Explicit About Schema

For complex data, be specific:

```
Create a recipes feature with this data structure:

Recipes table:
- id (unique identifier)
- title (required, text)
- description (optional, text)
- prep_time (number, in minutes)
- cook_time (number, in minutes)
- servings (number)
- image_url (optional, text)
- created_at (timestamp)
- user_id (link to user)

Ingredients table (linked to recipes):
- id (unique)
- recipe_id (link to recipe)
- name (required, text)
- quantity (text, like "2 cups")
- order (number, for sorting)

Each user can only see their own recipes.
```

## CRUD Operations

### Create (Adding Data)

```
When the user submits the new recipe form:
1. Validate all required fields are filled
2. Save the recipe to the database
3. Navigate back to the recipe list
4. Show a success toast: "Recipe saved!"
```

### Read (Fetching Data)

```
On the recipes list screen:
1. Fetch all recipes for the current user
2. Order by created_at, newest first
3. Show a loading spinner while fetching
4. Show "No recipes yet" if empty
```

### Update (Editing Data)

```
Add an edit button on the recipe detail screen:
1. Tapping it shows the recipe form with existing data
2. User can modify any field
3. On save, update the recipe in the database
4. Show success toast and return to detail view
```

### Delete (Removing Data)

```
Add delete functionality:
1. Long press on a recipe shows delete option
2. Show confirmation dialog: "Delete this recipe?"
3. On confirm, delete from database
4. Remove from list with animation
```

## Relationships Between Data

### One-to-Many Relationships

```
Each recipe has many ingredients.
When viewing a recipe, show its ingredients.
When deleting a recipe, also delete its ingredients.
```

### Fetching Related Data

```
On the recipe detail screen:
- Fetch the recipe by ID
- Also fetch all ingredients for this recipe
- Display ingredients in order
```

## Querying and Filtering

### Search

```
Add a search bar to the recipes list:
- Filter recipes as the user types
- Search both title and description
- Show "No results" if nothing matches
```

### Sorting

```
Add a sort option to recipes:
- Sort by newest first (default)
- Sort by prep time (shortest first)
- Sort alphabetically by title
```

### Filtering

```
Add category filtering:
- Each recipe has a category (breakfast, lunch, dinner, dessert)
- Add filter chips at the top of the list
- Tapping a chip shows only that category
```

## Optimistic Updates

For better UX, update the UI before the server responds:

```
When marking a task complete:
1. Immediately show it as complete (optimistic update)
2. Send the update to the server in background
3. If the server request fails, revert the change
4. Show an error toast if it fails
```

## Error Handling

```
Handle database errors gracefully:
- If save fails, show error message and keep form data
- If fetch fails, show retry button
- If delete fails, show error and keep item in list
- Always show user-friendly error messages
```

## Viewing Your Data

Use the Database Viewer to inspect your data:

1. Click the **Database** icon in the preview header
2. Select a table from the sidebar
3. Browse records and their values

This is useful for:

* Debugging data issues
* Verifying saves work correctly
* Understanding the data structure

## Best Practices

<CardGroup>
  <Card title="Validate Before Saving" icon="check">
    Check data is valid before sending to server
  </Card>

  <Card title="Show Loading States" icon="spinner">
    Indicate when data is being fetched or saved
  </Card>

  <Card title="Handle Errors" icon="triangle-exclamation">
    Always handle and display errors gracefully
  </Card>

  <Card title="Use Optimistic Updates" icon="bolt">
    Update UI immediately for better responsiveness
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Add Authentication" icon="user" href="/guides/adding-authentication">
    Secure your data with user accounts
  </Card>

  <Card title="Supabase Integration" icon="database" href="/integrations/supabase">
    Use Supabase for advanced features
  </Card>
</CardGroup>


# Delete your account
Source: https://docs.newly.app/guides/delete-account

How to permanently delete your Newly account, what gets removed, and the less drastic options to consider first.

Deleting your account permanently removes your Newly profile, every project you've
built, and all associated data. This guide walks through the steps, spells out exactly
what gets removed, and covers the lighter-weight options — cancelling your subscription
or deleting projects — that solve most cases without closing your account.

<Warning>
  Account deletion is **permanent and cannot be undone.** There is no grace period and no
  way to recover your projects afterward. If you might want your work later,
  [export your code](/advanced/exporting-code) or
  [push it to GitHub](/integrations/github) first.
</Warning>

## Quick answer

Open the **profile menu** (your avatar, top-right) → **Settings** → the **Danger zone** tab
→ type your account email to confirm → **Delete my account**. Deletion is immediate.

## Before you delete: consider these first

Most people who reach for "delete account" only need one of these. Each keeps your
account intact.

<CardGroup>
  <Card title="Just stop being billed?" icon="credit-card" href="/guides/cancel-subscription">
    Cancel your subscription and keep your account and projects on the free tier. See
    [Cancel your subscription](/guides/cancel-subscription).
  </Card>

  <Card title="Clear out your projects?" icon="trash" href="#delete-projects-without-deleting-your-account">
    Delete all — or individual — projects while keeping your login, settings, and any
    active plan.
  </Card>

  <Card title="Keep a copy of your work?" icon="download" href="/advanced/exporting-code">
    Export your project's source code or sync it to GitHub before you remove anything.
  </Card>

  <Card title="Not sure?" icon="life-ring" href="mailto:support@newly.app">
    Email [support@newly.app](mailto:support@newly.app) — we're happy to help you find the
    right option before you do something irreversible.
  </Card>
</CardGroup>

## Delete your account

<Steps>
  <Step title="Open Settings">
    Click your avatar in the top-right corner to open the profile menu, then choose
    **Settings**.
  </Step>

  <Step title="Go to the Danger zone">
    In the settings panel, select the **Danger zone** tab.
  </Step>

  <Step title="Confirm with your email">
    Type your account's primary email address into the confirmation field. The delete
    button stays disabled until it matches exactly — this is the guard against accidental
    deletion.
  </Step>

  <Step title="Delete">
    Click **Delete my account**. If you have a paid plan, the button instead reads
    **Cancel subscription & delete account** — clicking it cancels your subscription and
    deletes your account in one step.

    You'll be signed out and returned to the homepage once deletion completes.
  </Step>
</Steps>

<Note>
  If you have an active paid subscription, deletion **automatically cancels it** as part of
  the same action — you don't need to cancel separately first. Cancellation is immediate and
  **no refund is issued** for unused time in the current billing period.
</Note>

## What gets deleted

When you delete your account, we permanently remove:

* **Your account and login** — your profile, avatar, name, and email addresses.
* **All of your projects** — every app you've built, including its files, chat history,
  and version history.
* **Connected accounts** — linked Google and GitHub sign-ins and integrations.
* **Active sessions** — you're signed out everywhere.

Your active subscription is cancelled at the same time.

### What we retain

For legal and accounting reasons, your **billing records with our payment processor
(Stripe)** are preserved so that disputes, chargebacks, and any refunds remain possible.
These records are no longer tied to a usable Newly account — your login and product data
are gone. If you need these records erased as well, contact
[support@newly.app](mailto:support@newly.app).

## Delete projects without deleting your account

If you only want a clean slate, you can remove projects while keeping your account and
subscription:

* **Delete all projects at once** — open **Settings → Data** and use **Delete all
  projects**. This removes every app and its history but leaves your account, settings, and
  plan untouched.
* **Delete a single project** — from the project list, open a project's menu and choose
  delete.

<Warning>
  Deleting projects is also permanent. [Export the code](/advanced/exporting-code) or
  [sync to GitHub](/integrations/github) first if you might want it back.
</Warning>

## Refunds

Deleting your account cancels any active subscription **without a prorated refund** for the
unused portion of the current period. Separately from deletion, our standard
[refund policy](https://newly.app/terms) applies: we process refunds only if you've used
less than 5% of your monthly AI credits. See
[Cancel your subscription](/guides/cancel-subscription#refund-policy) for details.

## If something goes wrong

Account deletion coordinates a few systems (billing, then account removal). If deletion
fails partway — for example, you see a message saying your subscription was cancelled but
the account wasn't removed — **do not retry.** Contact
[support@newly.app](mailto:support@newly.app) with your account email and we'll finish it
for you.

## Still have questions?

* Billing and cancellation questions → [Cancel your subscription](/guides/cancel-subscription)
* Data or privacy requests → [support@newly.app](mailto:support@newly.app)
* General help → the [Discord community](https://discord.com/invite/sPbqWqgcMf)


# Build Your First App
Source: https://docs.newly.app/guides/first-app

Complete walkthrough of building a task manager app

# Build Your First App

This tutorial walks you through building a complete task manager app from scratch. You'll learn key concepts and patterns that apply to any app you build with Newly.

## What We're Building

A task manager app with:

* Add and view tasks
* Mark tasks complete
* Delete tasks
* Clean, modern UI

**Time required**: About 15 minutes

## Step 1: Start the Project

<Steps>
  <Step title="Go to Newly">
    Visit [newly.app](https://newly.app) and sign in
  </Step>

  <Step title="Create New Project">
    In the input box, describe your app:

    ```
    Create a task manager app with a clean, minimal design.
    Show a list of tasks where each task has:
    - Title text
    - Checkbox to mark complete
    - Completed tasks should show strikethrough text

    Include an "Add Task" button that opens a simple form
    to enter a new task title.

    Use a white background with dark gray text and
    a blue accent color for the add button.
    ```
  </Step>

  <Step title="Wait for Generation">
    The AI will create your app. Watch the activity feed to see progress.
  </Step>
</Steps>

<Note>
  First builds take 1-2 minutes. Subsequent changes are faster.
</Note>

## Step 2: Test the Basic App

Once the preview loads:

1. **Tap "Add Task"** - The form should appear
2. **Enter a task** - Type "Buy groceries"
3. **Submit** - Task should appear in the list
4. **Tap the checkbox** - Task should show strikethrough

If something doesn't work as expected, tell the AI:

```
When I tap the checkbox, the strikethrough isn't showing.
Fix this so completed tasks have strikethrough text.
```

## Step 3: Add More Features

Now let's enhance the app. Send this message:

```
Add these features to the task manager:
1. Swipe left on a task to reveal a delete button
2. When deleting, show a brief confirmation animation
3. Show "No tasks yet" message when the list is empty
4. Add a count showing "X tasks" in the header
```

### Understanding the Changes

The AI will:

* Add gesture handling for swipe
* Create delete animation
* Add empty state component
* Update header with count

## Step 4: Improve the Design

Let's make it look more polished:

```
Improve the design:
- Add subtle shadows to task cards
- Make the add button floating at the bottom right (FAB style)
- Add a gradient background from light blue to white
- Use the SF Pro or System font
- Add a nice entrance animation when tasks are added

Or use Visual Editor.
```

## Step 5: Add Due Dates

Let's add more functionality:

```
Add due dates to tasks:
- Include a date picker when adding tasks
- Show the due date below each task title
- Highlight overdue tasks in red
- Sort tasks by due date, soonest first
```

### Test the Feature

1. Add a new task with a due date
2. Add another with a different date
3. Verify sorting works correctly
4. Add a past date and check it shows red

## Step 6: Add Persistence (Optional)

To save tasks across app restarts:

```
Save tasks to the backend so they persist across sessions.
When the app loads, fetch existing tasks.
When I add, complete, or delete a task, sync with the backend.
```

<Note>
  This triggers Liquid Backend creation. Your tasks will now be saved to a database.
</Note>

## Step 7: Final Polish

Add finishing touches:

```
Final polish:
- Add haptic feedback when completing a task
- Add a satisfying checkmark animation on complete
- Show a subtle toast when task is added: "Task added!"
- Add pull-to-refresh on the task list
```

## Complete App Review

Your task manager now includes:

✅ Add tasks with titles and due dates ✅ Mark tasks complete with animation ✅ Swipe to delete ✅ Visual hierarchy for overdue tasks ✅ Data persistence ✅ Pull to refresh ✅ Empty states ✅ Haptic feedback

## Key Learnings

<AccordionGroup>
  <Accordion title="Start simple, add complexity">
    Begin with core features, then layer on enhancements. This makes debugging easier.
  </Accordion>

  <Accordion title="Be specific about design">
    Instead of "make it look good", specify colors, spacing, and effects.
  </Accordion>

  <Accordion title="Test each change">
    Verify features work before adding more. It's easier to fix issues early.
  </Accordion>

  <Accordion title="Describe behavior, not just appearance">
    Tell the AI what should happen on interactions, not just how things look.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you've built your first app:

<CardGroup>
  <Card title="Add Authentication" icon="user" href="/guides/adding-authentication">
    Let users create accounts
  </Card>

  <Card title="Connect Database" icon="database" href="/guides/connecting-database">
    Deep dive into data persistence
  </Card>

  <Card title="Deploy Your App" icon="rocket" href="/features/deployment">
    Put your app on the App Store
  </Card>

  <Card title="AI Chat Tips" icon="message-bot" href="/features/ai-chat">
    Master the AI interfaceu
  </Card>
</CardGroup>


# Native Packages
Source: https://docs.newly.app/guides/native-packages

What native packages are and why they need a simulator or dev build to run

# Native Packages

When building your app, you might see a message saying a **native package was detected**. This page explains what that means and what to do about it.

<Frame>
  <img alt="Native package detected warning in the preview panel" />
</Frame>

## What Are Native Packages?

Native packages are libraries that use features built into your phone's operating system - things like **Bluetooth**, **push notifications**, **NFC**, or **health data**. These features don't exist in a web browser, which means they can't run in the **web preview** or **Expo Go**.

Examples of native packages include:

| Category           | Packages                                         |
| ------------------ | ------------------------------------------------ |
| Push notifications | onesignal-expo-plugin                            |
| Bluetooth / NFC    | react-native-ble-plx, react-native-nfc-manager   |
| Health             | react-native-health, react-native-health-connect |
| Camera (advanced)  | react-native-vision-camera                       |
| Maps (Mapbox)      | @rnmapbox/maps                                   |
| Storage            | react-native-mmkv                                |
| Firebase           | @react-native-firebase/\*                        |
| In-App Purchases   | react-native-iap                                 |
| Speech recognition | expo-speech-recognition                          |

<Note>
  Many common packages **do** work in Expo Go and web preview - including `expo-camera`, `react-native-maps`, `react-native-reanimated`, `@stripe/stripe-react-native`, and most `expo-*` packages. These come pre-installed in the Expo Go runtime, so they work without a custom build. You'll only see the native package warning for packages that aren't pre-installed and use their own native code.
</Note>

## What Should I Do?

If your app uses a native package, you need to build for a **native simulator** instead of using the web preview. Switch to the **iOS** or **Android** tab in the preview panel, then follow the steps in our [simulator build guide](/guides/preview-troubleshooting#how-to-fix-it) to get your app running.

## Why Can't Native Packages Run in Web Preview?

Native packages include platform-specific code written in programming languages like Swift or Kotlin (the languages used to build iPhone and Android apps). This code needs to be baked directly into the app when it's built. Native packages can also require special device permissions, like Bluetooth or camera access, which need to be set up when the app is built.

**Expo Go** is a pre-built app that Expo provides for quick testing. It comes with a fixed set of native modules already baked into it. When your JavaScript code tries to use a native package that isn't part of that set, it's trying to talk to native code that simply doesn't exist in the app - so it fails or gets stuck.

**Web preview** has the same problem but for a different reason. It runs your app in a browser, and browsers can't run Swift or Kotlin code at all.

A **simulator build** solves both of these issues. It creates your own custom version of the app with exactly the native packages your project needs compiled into it, so everything runs properly.

## Does It Need a Special Entitlement?

Some native capabilities also need **approval** from Apple or Google before you can publish — for example Family Controls (Screen Time), Critical Alerts, CarPlay, or Android background location. Adding the package isn't enough; you have to apply for the entitlement too.

<Card title="Permissions & Entitlements" icon="shield-check" href="/guides/permissions-and-entitlements">
  Check whether your capability needs an approval request before you submit.
</Card>

## Still Have Questions?

* **Ask the AI** in your project chat - describe the issue and it can help debug
* **Use the in-app support widget** to reach out to support without leaving your project
* **Email us** at [support@newly.app](mailto:support@newly.app)


# Permissions & Entitlements
Source: https://docs.newly.app/guides/permissions-and-entitlements

Some app capabilities need approval from Apple or Google before you can ship them. Here's how to apply.

# Permissions & Entitlements

Most permissions your app needs — camera, location, notifications, photos — work as soon as you add them and ask the user. But a small set of powerful capabilities are **gated**: Apple or Google requires a separate application or declaration, and your app will be **rejected at submission** if you ship the capability without it.

This page explains which capabilities are gated, how to apply for each, and how to add the capability to your app in Newly.

<Note>
  This page is **only** about approval-gated capabilities. Everyday permissions like camera, microphone, location, contacts and push notifications need no special approval — just add them and the OS prompts the user at runtime.
</Note>

## How gating works

There are three different gates, and knowing which one applies tells you what to do:

<CardGroup>
  <Card title="Apple request form" icon="file-signature">
    You fill out an Apple form and wait for approval **before** the entitlement can be used in a distribution build.
  </Card>

  <Card title="Apple App Review" icon="apple">
    No form — you enable the capability in your build, and Apple checks it during normal **App Review**.
  </Card>

  <Card title="Play Console declaration" icon="google-play">
    You complete a **Permissions Declaration** inside Google Play Console before the app or update can publish.
  </Card>
</CardGroup>

## Apple: managed entitlements

These Apple capabilities require a **request form** and approval before you can ship a distribution build. Each links to a deeper guide.

| Capability                                                   | What it's for                                          | Apply via                                                                                                          |
| ------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| [Family Controls](/articles/family-controls-entitlement)     | Screen Time, app blocking, parental controls           | [Family Controls (Distribution) request](https://developer.apple.com/contact/request/family-controls-distribution) |
| [Critical Alerts](/articles/critical-alerts-entitlement)     | Notifications that bypass silent mode & Focus          | [Critical Alerts request](https://developer.apple.com/contact/request/notifications-critical-alerts-entitlement/)  |
| [CarPlay](/articles/carplay-entitlement)                     | In-car app UI (audio, navigation, EV charging…)        | [Request a CarPlay entitlement](https://developer.apple.com/contact/carplay/)                                      |
| [Network Extension](/articles/network-extension-entitlement) | Hotspot Helper (VPN/content-filter are now self-serve) | [Network Extension request](https://developer.apple.com/contact/request/network-extension)                         |

A few Apple capabilities are gated at **App Review** instead — there's no form, but you must meet documented requirements:

| Capability                                             | What it's for                                                         | How it's gated                                    |
| ------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------- |
| [Health Records](/articles/health-records-entitlement) | Reading a user's clinical / FHIR health records                       | Enable in Xcode → justify at App Review           |
| [Default App](/articles/ios-default-app-entitlement)   | Default calling, messaging, navigation or translation app (iOS 18.2+) | Enable in Xcode → meet requirements at App Review |

### The Apple request flow

For the form-gated entitlements above, the process is the same:

<Steps>
  <Step title="Develop against the capability first">
    Many entitlements (like Family Controls) provide a development variant you can build and test with locally before you request distribution.
  </Step>

  <Step title="Sign in as the Account Holder">
    Open the request form while signed in to the Apple Developer account that owns the app — requests are tied to your team.
  </Step>

  <Step title="Describe your app and use case">
    Provide the bundle identifier and a clear, specific justification for why the app needs the capability and how it uses it.
  </Step>

  <Step title="Wait for review">
    Apple reviews each request manually — typically a few business days to a few weeks. Submit early.
  </Step>

  <Step title="Enable the capability and rebuild">
    Once approved, turn the capability on for your bundle ID, regenerate your distribution provisioning profile, and rebuild.
  </Step>
</Steps>

<Warning>
  Approval must happen **before** you submit to the App Store. The development build can work locally while you wait, but uploading a distribution build with an unapproved managed entitlement will fail signing or be rejected.
</Warning>

## Android: restricted permissions

Google Play classifies some permissions as high-risk. Requesting one triggers a **Permissions Declaration** in Play Console, and in most cases you need approval before the app or any update can publish. See the [full guide](/articles/android-restricted-permissions) for details.

| Permission                   | What it covers              | Declaration required?                                  |
| ---------------------------- | --------------------------- | ------------------------------------------------------ |
| `BIND_ACCESSIBILITY_SERVICE` | Accessibility API           | Always, unless it's a genuine accessibility tool       |
| `READ_SMS` / `READ_CALL_LOG` | SMS & call history          | Always (must be default handler or approved exception) |
| `ACCESS_BACKGROUND_LOCATION` | Location while backgrounded | Always                                                 |
| `MANAGE_EXTERNAL_STORAGE`    | All Files Access            | Always                                                 |
| `QUERY_ALL_PACKAGES`         | See all installed apps      | When broad visibility is requested                     |

<Steps>
  <Step title="Audit your compiled manifest">
    A library or config plugin can pull in a sensitive permission you didn't add directly. Review the merged `AndroidManifest.xml` (or `expo prebuild` output) before you submit.
  </Step>

  <Step title="Open the declaration in Play Console">
    Go to **App content → Sensitive app permissions / Permissions Declaration Form**. It also surfaces automatically during a release that requests an undeclared sensitive permission.
  </Step>

  <Step title="Justify the core use case">
    Select the supported use case, explain why the permission is essential, and why a privacy-friendlier alternative won't work.
  </Step>

  <Step title="Provide a video demonstration">
    Add a short video showing the permission in use, plus test instructions or a test account.
  </Step>

  <Step title="Submit and wait for extended review">
    The release sits in pending publication during extended review — Google says this can take up to several weeks.
  </Step>
</Steps>

<Warning>
  If you don't declare a restricted permission, you **can't publish updates**, and a non-compliant live app can be removed from Google Play.
</Warning>

## Adding the entitlement in Newly

Newly builds real native apps, so a gated capability goes into your project the same way it would in a hand-written app — you just describe it.

<Tabs>
  <Tab title="Via AI">
    Describe the capability in your project chat, for example:

    ```
    Add the Family Controls entitlement so users can block
    selected apps during focus sessions.
    ```

    The agent wires up the entitlement keys, `Info.plist` / `AndroidManifest` entries and native modules for you.
  </Tab>

  <Tab title="Then apply & rebuild">
    1. File the Apple request (or complete the Play Console declaration) yourself — only your developer account can do this.
    2. Once approved, open **More → Deploy App** and rebuild.
    3. Submit to the App Store / Play Store. The entitlement is already in your build, so it's ready the moment approval lands.
  </Tab>
</Tabs>

<Tip>
  File the approval request **early** — it often takes longer than the build itself. You can keep developing while you wait.
</Tip>

## Still have questions?

* **Ask the AI** in your project chat — describe the capability you need and it can help wire it up.
* **Email us** at [support@newly.app](mailto:support@newly.app).

<Card title="App Deployment" icon="rocket" href="/features/deployment">
  How Newly builds and submits your app to the App Store and Play Store.
</Card>


# Preview troubleshooting
Source: https://docs.newly.app/guides/preview-troubleshooting

Fixes for the most common preview issues: web preview stuck, iOS showing the welcome screen, stale bundle, and more.

# Preview troubleshooting

Most preview issues fall into one of these patterns. Pick the section that matches what you're seeing.

* *Web preview stuck on "Loading preview\..."* → [Web preview stuck](#web-preview-stuck-on-loading-preview)
* *Code changes don't show up on a real device or in TestFlight* → [Changes don't show on device or TestFlight](#changes-dont-show-on-device-or-testflight)

## Web preview stuck on "Loading preview\..."

If your web preview is stuck on "Loading preview\..." and never loads, it's likely because your app uses a native-only package like **OneSignal (push notifications)** that doesn't work in the browser-based web preview.

<Frame>
  <img alt="Web preview stuck on Loading preview..." />
</Frame>

The fix is to build your app for a **native simulator** (iOS or Android) instead of using the web preview.

## How to Fix It

<Steps>
  <Step title="Switch to the iOS or Android tab">
    Click the **iOS** or **Android** tab at the top of the preview panel. You'll see a **Build simulator** button at the bottom.

    <Frame>
      <img alt="iOS tab with Build simulator button" />
    </Frame>
  </Step>

  <Step title="Start the simulator build">
    Click **Build simulator**. In the Deploy panel that opens, make sure **Simulator** is selected, then click **Build simulator**.

    <Frame>
      <img alt="Deploy panel with Simulator selected" />
    </Frame>
  </Step>

  <Step title="Create an Expo account">
    The build process requires an Expo account. When prompted for your email or username, create a free account at [expo.dev](https://expo.dev/) and enter your credentials.

    <Frame>
      <img alt="Expo login prompt during build" />
    </Frame>
  </Step>

  <Step title="Wait for the build to complete">
    The simulator build takes a few minutes. Once it's done, your app will open in the simulator where you can test all native features including push notifications.
  </Step>
</Steps>

## Why Does This Happen?

The web preview runs your Expo app in a browser-based environment. Some packages – like **OneSignal (push notifications)** – rely on native iOS/Android APIs that don't exist in the browser. When these packages try to initialize, the web preview gets stuck.

Building for a native simulator creates a real native app that supports all native APIs, so everything works as expected.

<Tip>
  This issue can also happen with other native-only packages. If your web preview is stuck and you've recently added a new package, try building for a native simulator to test your app.
</Tip>

## Changes don't show on device or TestFlight

This usually means you're looking at a different version of the app than the one your changes reached. Newly has three places your app can run – web preview, simulator, and TestFlight or the App Store – and they don't always update at the same time.

TestFlight uses the version of your app from your last build. Code changes don't reach TestFlight until you start a new build.

The full breakdown of which version contains what, and how to think about it: [Preview vs builds](/guides/preview-vs-builds).

For a different class of issue – a fresh QR scan in Expo Go is still showing an old version – try force-closing Expo Go on your device and re-scanning the QR code from a clean start.

## Still stuck?

If none of the above fixes the issue:

* **Ask the AI** to diagnose the problem – describe what you see and it can help debug.
* **Use the in-app support widget** to reach out to support without leaving your project.
* **Email us** at [support@newly.app](mailto:support@newly.app).


# Preview vs builds: which one am I looking at?
Source: https://docs.newly.app/guides/preview-vs-builds

Newly gives you three ways to see your app while you build. They don't all update at the same time, and knowing which one you're looking at clears up most 'it works here but not there' confusion.

Ever added something, watched it appear in the Newly preview, then opened TestFlight and it's just not there? Or had a feature work on your phone but not in the browser preview? You're not doing anything wrong. You're looking at a different copy of your app than you think.

Newly shows you your app in three places while you build. Each one updates at its own speed and behaves a little differently. Here's what each is for.

## The three ways to see your app

### Web preview

The panel on the right side of your project. This is the fastest way to see changes: edit something, save, and it updates right away. No waiting.

Best for: checking layout, wording, your screens, and how you move between them. Anything visual.

One thing to watch: the browser preview runs your app in a little sandbox, and that sandbox handles login slightly differently than a real phone does. So if something tied to your account (adding a member, saving a value, creating a record) gives you a "session expired" error here, don't panic. Try the same thing in the simulator. It almost always just works, and you don't have to change anything.

### Simulator

The iOS and Android tabs in the preview panel. This runs a closer-to-real version of your app, and it still picks up your latest changes as you save.

Best for: anything that needs to behave like a real phone, such as logging in, push notifications, the camera, location, or links that open your app. Much closer to the real thing than the browser preview.

One thing to watch: the Android and iOS tabs don't work quite the same way behind the scenes. Android is usually faster and has fewer things that can go wrong. For the workflow most experienced Newly builders use day to day, see [Recommended dev loop](/guides/recommended-dev-loop).

### Real builds (TestFlight and the app stores)

When you hit **Deploy**, Newly builds the real, finished version of your app. That's what goes to TestFlight, the App Store, and Google Play.

Best for: the actual app your users install. It's also the only version Apple and Google review.

One thing to watch, and this one trips up almost everyone: a build is a snapshot. It captures your app exactly as it was the moment you hit Deploy. Anything you change after that doesn't reach TestFlight on its own. To see new changes there, hit Deploy again and upload the new build.

This is the number one reason for "the AI fixed it, so why don't I see it in TestFlight?"

## The three side by side

|                              | Web preview              | Simulator                   | Real build                       |
| ---------------------------- | ------------------------ | --------------------------- | -------------------------------- |
| **Where it runs**            | In your browser          | In the iOS/Android tab      | On a real phone, from the stores |
| **How fast it updates**      | Instantly, when you save | When you save               | Only when you Deploy again       |
| **Login on iOS**             | Sometimes glitchy        | Works like a real phone     | Works like a real phone          |
| **Best for**                 | Layout and wording       | Testing real-phone behavior | Shipping to users                |
| **When your changes appear** | The moment you save      | Next time it reloads        | After your next Deploy           |

## Common confusions, explained

<AccordionGroup>
  <Accordion title="The feature shows up in the Newly preview but is missing from TestFlight">
    Your TestFlight version was built before you added the feature, so it doesn't have it yet. Go to the Deploy tab and build again. The new build includes your latest work, and TestFlight will show it once you upload it.

    Quick check: open your project files and confirm the feature is actually in your code. If it is, this is just an old TestFlight version, not a bug.
  </Accordion>

  <Accordion title="'Session expired' when I add a member or save in the web preview, but it works in the simulator">
    The browser preview handles your login in a way that some actions can't always read back. Try the same thing in the simulator or on your phone. It should work, and you don't need to change anything.

    If you'd also like it to work in the browser preview, ask the AI to check whether you're signed in instead of re-reading your login on every request.
  </Accordion>

  <Accordion title="The app works in the Newly preview, but iOS shows 'Welcome to Newly, your app is currently building...'">
    This usually means the AI updated your Android and web screens but missed the matching iOS ones. Ask the AI to update the iOS version of your app so it matches what you see on web and Android.
  </Accordion>

  <Accordion title="I made a change, the preview shows it, but Expo Go on my phone is still on the old version">
    Force-close the Expo Go app and scan the QR code again. Expo Go can hold onto the old version, and a fresh scan picks up the new one.
  </Accordion>
</AccordionGroup>

## Rule of thumb

* Browser preview for quick visual changes.
* Simulator (Android by default) for everyday building and feature work.
* The iOS tab when you need to check something specific to iPhone.
* A real build (Deploy) for anything going to actual users.

When something looks off, ask yourself one question first: which version am I looking at, and does it actually have the changes I just made?


# Recommended dev loop
Source: https://docs.newly.app/guides/recommended-dev-loop

Build on Android day-to-day, use iOS for verification – this saves you time, credits, and most platform-side headaches.

Most of the friction Newly builders run into during iteration comes from the iOS preview pipeline. iOS goes through more layers (Expo, EAS, Apple credentials, dev-client versions) than Android does, and each layer has its own failure modes. If you're testing every change on iOS, you'll hit those layers often enough to slow you down.

The shorter route: do daily building on Android, then check on iOS occasionally and when you're ready to ship.

## The pattern

<Steps>
  <Step title="Open the Android simulator as your default preview">
    In the preview panel, switch to the **Android** tab and use the Android simulator (or Expo Go on an Android phone) for everyday testing.

    Android doesn't go through Expo's build pipeline, so the simulator spins up faster and has fewer steps that can fail between you and a working app.
  </Step>

  <Step title="Keep using Newly's web preview for layout checks">
    The web preview is great for quick visual feedback – colors, spacing, copy. It re-bundles your JS as you save, so visual changes show up live.

    Just know that the web preview wraps your app in an iframe, which affects a few auth-heavy flows (more on that in [Preview vs builds](/guides/preview-vs-builds)).
  </Step>

  <Step title="Trigger an iOS build when you need to verify something iOS-specific">
    Examples: Apple sign-in, layout quirks that look different on iOS, App Store metadata, or pre-TestFlight smoke tests.

    Not every prompt iteration. Once per feature, or once per session, is a healthy cadence.
  </Step>

  <Step title="Run a full iOS build before TestFlight submission">
    When you're ready to ship, trigger a fresh build from the Deploy tab. This is the build TestFlight will use, so do this right before you upload.
  </Step>
</Steps>

## Why this works

The iOS preview pipeline has more moving parts than the Android one:

* *Expo + EAS* handles iOS builds. Each EAS build is a new compile with its own credentials prep step.
* *Apple credentials* (ASC API key, provisioning, bundle ID) need to be in sync with your project.
* *dev-client version* on iOS must match your SDK version. A small mismatch produces native errors.

Android skips most of that. Its simulator boots from a Gradle build that lives entirely in our infrastructure, with no Apple-side dependencies. You can do hundreds of Android iterations without touching any of the iOS-specific layers.

## When iOS-primary is the right choice

If you're building something iOS-specific (HealthKit, Apple Pay, iOS-only widgets, an iPad-first layout), Android-primary doesn't help you. Use iOS preview from the start in that case.

Same if you're days away from App Store submission – keep iOS in the loop so you catch any submission-blocking issues before they hold you up.

## Quick comparison

| Situation                                            | Use                            |
| ---------------------------------------------------- | ------------------------------ |
| Editing UI, building features, normal iteration      | Android simulator              |
| Quick visual / layout check                          | Web preview                    |
| Verifying Apple sign-in, Apple Pay, iOS-specific bug | iOS preview                    |
| Pre-TestFlight smoke test                            | iOS build via Deploy tab       |
| Daily dev on an iOS-only feature                     | iOS preview (no shortcut here) |

## Related

* [Preview vs builds](/guides/preview-vs-builds) – the three runtime layers (web preview, simulator, production build) and what changes between them.
* [How to save AI prompts](/guides/save-prompts) – getting more out of each credit.
* [My Project is Stuck on Loading Preview](/guides/preview-troubleshooting) – fixes for when the preview itself misbehaves.


# How to save credits
Source: https://docs.newly.app/guides/save-prompts

Get more out of every credit: write tighter prompts, use Ask mode, restore broken state, and try a diagnose-first pattern instead of fix-everything prompts.

The AI is making mistakes, undoing previous work, or eating into your monthly credit limit without fixing the actual issue you're trying to solve.

## Quick answer

Stop using single, massive prompts to build the entire app. Break your work into logical steps, send screenshots of specific errors, and use **Ask mode** when you only need a question answered. When something breaks, the **Restore** button is almost always faster than another fix prompt.

## Check your credit usage

1. Go to **newly.app/pricing**.
2. Click the **Usage** tab to see your remaining credits for the month.

If you run out before your next renewal, you can buy a one-time top-up from the same page without changing your plan.

## Best practices for prompting

* **Iterate step by step.** The ideal workflow is Prompt → Review App → Feedback Prompt → Review App. Don't paste a giant list of requirements into a single prompt.
* **Be specific.** Avoid abstract commands like "fix the app" or "make things good". Describe the exact user flow, the desired steps, and the expected outcome.
* **Use screenshots for errors.** If you hit a build error or a visual bug, take a screenshot, upload it to the chat, and explain how you want it to look or function.
  <Tip>
    **Mac:** Press **Shift + Control + Command + 4**, then drag to select an area. The screenshot is copied to your clipboard, ready to paste with **Command + V**.
  </Tip>
  <Tip>
    **Windows:** Press **Windows + Shift + S** to open Snipping Tool. Choose rectangular, freeform, window, or fullscreen mode, then make your selection. The screenshot is copied to your clipboard, ready to paste with **Ctrl + V**.
  </Tip>
* **Use Ask mode for questions.** If you're asking a question rather than requesting a code change, click the build dropdown and select **Ask mode**. This costs 10x fewer credits than a standard build request.
  <Frame>
    <img alt="Ask mode selected in the chat mode dropdown" />
  </Frame>
* **Read prompts before sending.** If you're copy-pasting from ChatGPT or another LLM, skim it first. It's easy to send something off-target and burn a credit on a wrong direction.

## Restore is your fastest way back to a working version

If something was working an hour ago and the AI broke it on a recent prompt, **don't try to fix it forward with more prompts.** The Restore button next to any chat message rolls your project back to that exact point, including dependencies and project state.

Restoring is almost always faster than trying to repair the broken state. It also costs zero credits.

<Tip>
  Restoring from chat history is more reliable than copy-pasting code from a downloaded ZIP. The chat history Restore preserves dependency versions and project state alongside your code. A ZIP only contains the files.
</Tip>

## Diagnose first, then fix

When the AI is bouncing between attempts and not converging on a fix, it usually means the prompt asked it to *change* something before it had inspected what's actually broken. A prompt that explicitly asks the AI to read and report first, then propose a change, tends to land in one round instead of three.

Template:

```
Before changing any code, do this:
1. Read the file at [path] and show me the relevant section verbatim.
2. Run the action that's failing and tell me the exact error message.
3. Explain what's causing the error based on what you read.
Do not make any changes yet. Show me your findings and I'll confirm before you change anything.
```

This pattern works especially well for:

* Bugs where the AI has tried 3+ fixes and none stick.
* Backend API issues where the actual error message is more useful than a guess.
* File-structure questions ("does this file exist", "is this function defined here").

## For a stuck build specifically

If a build is stuck at *"1 issue blocking"* or similar, broad prompts like "fix the build" rarely work. Use this:

```
Open the build logs, find the specific blocking issue, and either fix it or tell me exactly what's blocking and what's needed to clear it. Do not say it's a platform issue without checking the log first.
```

The last sentence is the one that matters most. It stops the AI from defaulting to *"this must be a Newly platform problem"* when it hasn't actually looked at the log.

## Related

* [Using logs to debug](/guides/using-logs-to-debug) – how to read build and runtime logs in your project.
* [Recommended dev loop](/guides/recommended-dev-loop) – building on Android by default cuts down on iOS-pipeline issues that often look like "the AI broke it".


# Apple & Google Login with Supabase
Source: https://docs.newly.app/guides/supabase-social-login

Add Sign in with Apple and Sign in with Google to your app using Supabase Auth

# Apple & Google Login with Supabase

This guide walks you through adding **Sign in with Apple** and **Sign in with Google** to a Newly app that uses **Supabase** as its backend.

Unlike email/password, social login needs a one-time setup in the provider consoles (Google Cloud, Apple Developer) and in your Supabase Dashboard. Newly can't do this part for you because it involves your own developer accounts and secrets. Once configured, you tell the AI to build the buttons and wire up the flow.

<Note>
  This guide is for projects using **Supabase**. If you're on **Liquid Backend**, follow [Adding Authentication](/guides/adding-authentication) instead — Google login works there without any console setup for development. See [Backend Systems](/features/backend) to check which backend you're on.
</Note>

## How social login works on native

On a phone, social login isn't a website popup — it uses the operating system's native account picker. The flow is:

1. The user taps **Continue with Apple** / **Continue with Google**.
2. The OS shows its native sign-in sheet and returns a signed **ID token**.
3. Your app passes that token to Supabase with `signInWithIdToken`.
4. Supabase verifies the token, creates or finds the user, and returns a session.

This is why each provider needs a **client ID** that matches your app, and why Supabase needs to know which client IDs to trust.

## Prerequisites

<CardGroup>
  <Card title="Supabase project connected" icon="database" href="/integrations/supabase">
    Your Newly app is already linked to a Supabase project
  </Card>

  <Card title="Apple Developer Account" icon="apple">
    Required for Sign in with Apple (\$99/year)
  </Card>

  <Card title="Google Cloud Account" icon="google">
    Free — for creating OAuth client IDs
  </Card>

  <Card title="Your app's Bundle ID" icon="hashtag" href="/guides/bundle-id-changes">
    e.g. <code>com.yourcompany.yourapp</code> — you'll need it in both consoles
  </Card>
</CardGroup>

<Tip>
  Decide your **Bundle ID** before starting. Both Apple and Google tie their client IDs to it, and changing it later means redoing this setup. See [Changing Your Bundle ID](/guides/bundle-id-changes).
</Tip>

***

## Sign in with Google

### Step 1: Create OAuth client IDs in Google Cloud

Google needs a separate client ID per platform.

<Steps>
  <Step title="Create a project">
    Go to the [Google Cloud Console](https://console.cloud.google.com) and create (or select) a project.
  </Step>

  <Step title="Configure the consent screen">
    Go to **APIs & Services → OAuth consent screen**. Choose **External**, fill in the app name, support email, and developer contact. Add your email as a test user while developing.
  </Step>

  <Step title="Create a Web client ID">
    Under **Credentials → Create Credentials → OAuth client ID**, choose **Web application**. This is the client Supabase uses. Copy its **Client ID** and **Client secret**.
  </Step>

  <Step title="Add the Supabase redirect URL">
    In the Web client, add this to **Authorized redirect URIs** (find your project ref in the Supabase Dashboard URL):

    ```
    https://<your-project-ref>.supabase.co/auth/v1/callback
    ```
  </Step>

  <Step title="Create an iOS client ID">
    Create another OAuth client ID of type **iOS** and enter your app's **Bundle ID**. Copy this **iOS Client ID**.
  </Step>

  <Step title="Create an Android client ID (if shipping Android)">
    Create an **Android** OAuth client ID with your package name and SHA-1 certificate fingerprint. Copy the **Android Client ID**.
  </Step>
</Steps>

### Step 2: Enable Google in Supabase

<Steps>
  <Step title="Open the provider settings">
    In the [Supabase Dashboard](https://supabase.com/dashboard) go to **Authentication → Providers → Google** and toggle it on.
  </Step>

  <Step title="Add the Web client credentials">
    Paste the **Web** Client ID and Client secret from Step 1.
  </Step>

  <Step title="Authorize your native client IDs">
    In the **Authorized Client IDs** field, add your **iOS** (and **Android**) client IDs, comma-separated. This is what lets Supabase trust the ID tokens coming from the native sign-in sheet.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

<Warning>
  A common mistake is adding only the Web client ID. Native sign-in returns tokens issued to the **iOS/Android** client IDs — if those aren't in **Authorized Client IDs**, Supabase rejects the token with an "audience mismatch" error.
</Warning>

### Step 3: Build the button in Newly

Tell the AI what you want, and give it the client IDs so it can configure the native module:

```
Add a "Continue with Google" button to my Login and Sign Up screens
using native Google Sign-In and Supabase.

Use supabase.auth.signInWithIdToken with the ID token from the native
Google sign-in sheet (not the web browser flow).

My Google iOS client ID is: <paste iOS client ID>
My Google Web client ID is: <paste Web client ID>

Match the existing screen design, show a loading state while signing in,
and navigate to the home screen on success.
```

<Note>
  Newly installs and configures the native Google Sign-In package for you. Because this adds a native module, you'll need to run it on a **development build / TestFlight**, not the in-editor preview. See [Preview vs Builds](/guides/preview-vs-builds).
</Note>

***

## Sign in with Apple

Apple requires native **Sign in with Apple** for any app that offers third-party login (like Google) on iOS. So if you add Google, you generally must add Apple too, or Apple may reject your submission.

### Step 1: Configure your App ID in Apple Developer

<Steps>
  <Step title="Enable the capability">
    In the [Apple Developer portal](https://developer.apple.com/account), go to **Certificates, Identifiers & Profiles → Identifiers**, open your app's **App ID** (matching your Bundle ID), and enable the **Sign in with Apple** capability.
  </Step>

  <Step title="Create a Services ID">
    Create a new **Services ID** (e.g. `com.yourcompany.yourapp.signin`). Enable **Sign in with Apple** on it and configure the web domain and return URL:

    ```
    https://<your-project-ref>.supabase.co/auth/v1/callback
    ```
  </Step>

  <Step title="Create a signing key">
    Under **Keys**, create a new key with **Sign in with Apple** enabled. Download the `.p8` file (you can only download it once) and note the **Key ID** and your **Team ID**.
  </Step>
</Steps>

### Step 2: Enable Apple in Supabase

<Steps>
  <Step title="Open the provider settings">
    Go to **Authentication → Providers → Apple** in the Supabase Dashboard and toggle it on.
  </Step>

  <Step title="Add your credentials">
    Enter the **Services ID** (as the Client ID), your **Team ID**, **Key ID**, and the contents of the `.p8` key file so Supabase can generate the client secret.
  </Step>

  <Step title="Authorize the native client ID">
    In **Authorized Client IDs**, add your app's **Bundle ID**. Native iOS Sign in with Apple issues tokens to the bundle ID, so Supabase needs it listed to accept them.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

### Step 3: Build the button in Newly

```
Add a "Sign in with Apple" button to my Login and Sign Up screens,
following Apple's Human Interface Guidelines (black button, Apple logo).

Use expo-apple-authentication to get the identity token, then call
supabase.auth.signInWithIdToken with provider "apple".

Only show the button on iOS. Handle the case where the user cancels
the sheet, and navigate to the home screen on success.
```

<Warning>
  Apple only returns the user's name and email on the **first** sign-in for a given Apple ID. Capture and store them then — on later logins you'll only get the user identifier. If you need to test again, remove the app from your Apple ID under **Settings → your name → Sign in with Apple**.
</Warning>

***

## Handling the session

Once either provider returns a session, the rest of your auth flow is identical to email/password. Ask the AI to tie it together:

```
After a successful social login, persist the Supabase session so the user
stays logged in across app restarts, and load their profile.

If a profiles table row doesn't exist for this user yet, create one with
their name and email from the auth session.
```

<Note>
  Supabase stores the session automatically when the client is configured with persistent storage. Newly sets this up for you, but if sessions don't persist, tell the AI: "The Supabase session isn't persisting across app restarts."
</Note>

## Row Level Security

Social-logged-in users are regular Supabase auth users, so the same RLS rules apply. Make sure your tables restrict rows to the owner:

```
Add RLS policies so each user can only read and write their own rows,
matching auth.uid() against the user_id column.
```

See [Supabase Integration → Row Level Security](/integrations/supabase#row-level-security) for common patterns.

## Testing

<Steps>
  <Step title="Use a development build">
    Native sign-in needs a real build (TestFlight or dev client), not the in-editor preview.
  </Step>

  <Step title="Sign in with Google">
    Tap the button, pick an account, and confirm you land on the home screen.
  </Step>

  <Step title="Sign in with Apple">
    On a real iOS device or simulator signed into an Apple ID, confirm the sheet appears and login succeeds.
  </Step>

  <Step title="Verify the user in Supabase">
    Check **Authentication → Users** in the Supabase Dashboard — the new user should appear with the correct provider.
  </Step>

  <Step title="Test persistence">
    Fully close and reopen the app — you should still be signed in.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Google: 'audience mismatch' or 'invalid token' error">
    The iOS/Android client ID that issued the token isn't listed in Supabase. Add it under **Authentication → Providers → Google → Authorized Client IDs** (comma-separated), separate from the Web client ID.
  </Accordion>

  <Accordion title="Apple: button does nothing / 'not handled' error">
    * Confirm **Sign in with Apple** is enabled on your App ID and the Bundle ID matches exactly.
    * Confirm your Bundle ID is in Supabase's **Authorized Client IDs** for Apple.
    * Native Sign in with Apple only works on a real build, not the preview.
  </Accordion>

  <Accordion title="Redirect URI mismatch">
    The redirect URL in Google Cloud (Web client) and Apple's Services ID must exactly match <code>https\://\<your-project-ref>.supabase.co/auth/v1/callback</code>. Double-check the project ref.
  </Accordion>

  <Accordion title="Apple approves but returns no email">
    Apple only sends name/email on the first authorization for that Apple ID. Store them on first login, and remove the app under **Settings → Sign in with Apple** to test the first-run flow again.
  </Accordion>

  <Accordion title="Works in preview but not in the build (or vice versa)">
    Native sign-in modules only run in real builds. The web browser OAuth flow can run in the preview but gives a worse UX. Use native sign-in for shipping apps. See [Preview vs Builds](/guides/preview-vs-builds).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Supabase Integration" icon="database" href="/integrations/supabase">
    Full reference for Supabase in Newly
  </Card>

  <Card title="Adding Authentication" icon="user" href="/guides/adding-authentication">
    Email/password auth and protected routes
  </Card>

  <Card title="Connect a Database" icon="table" href="/guides/connecting-database">
    Store user-specific data
  </Card>

  <Card title="Preview vs Builds" icon="mobile" href="/guides/preview-vs-builds">
    Why native login needs a real build
  </Card>
</CardGroup>


# Troubleshooting log
Source: https://docs.newly.app/guides/troubleshooting-log

Real issues found while building on Newly, with the root cause and the exact fix for each. Updated as new issues get solved.

# Troubleshooting log

A running log of specific issues we've hit and fixed, one entry per issue. Each entry has the problem as it appears to you, the root cause, and the fix. New entries get added to the top as they come up.

* *iOS Simulator fails with "Input is required... non-interactive mode"* → [Simulator fails with a non-interactive EAS auth error](#simulator-fails-with-a-non-interactive-eas-auth-error)

## Simulator fails with a non-interactive EAS auth error

### Problem

Running a project in the iOS Simulator fails immediately with an error screen instead of loading the app:

```
There was a problem running the requested app.

HTTP response error 500:
{"error":"CommandError: Input is required, but 'npx expo' is in non-interactive mode.
Use the EXPO_TOKEN environment variable to authenticate in CI (Learn more:
https://docs.expo.dev/accounts/programmatic-access/)"}
```

### Root cause

The project's `app.json` had a leftover `extra.eas.projectId` entry from a previous EAS build (a real device/TestFlight build via **Build simulator** or App Store submission). Newly normally strips this field back out automatically once a build finishes — but that cleanup step can fail silently (e.g. if the build was interrupted), leaving the ID behind.

The ordinary Simulator preview runs a plain `expo start` process with no Expo login and no way to prompt for one (it's a piped, non-interactive process). That's fine for a normal project — but once `app.json` carries an `extra.eas.projectId`, the Expo CLI tries to validate that EAS project against your Expo account over the network. With no login available and no terminal to prompt in, it fails hard with the error above.

In short: it looks like a Simulator bug, but it's actually a stale field in `app.json` left over from an earlier build.

### Fix

Open `app.json` and remove the `eas` block under `extra`:

```json theme={null}
// Before
"extra": {
  "router": {},
  "backendUrl": "...",
  "eas": {
    "projectId": "4d6fa720-b142-4bb0-bfa6-8f73bc776974"
  }
}

// After
"extra": {
  "router": {},
  "backendUrl": "..."
}
```

Nothing else in the project reads `extra.eas.projectId`, so removing it doesn't affect app behavior — it only controls whether the Expo CLI tries to resolve an EAS project on start.

<Tip>
  You can just ask the AI in your project to "remove the stray extra.eas.projectId from app.json" and it will make this exact edit for you.
</Tip>

<Note>
  This field gets added back automatically the next time you run a real EAS build (**Build simulator**, TestFlight, or App Store submission) — that's expected. You'll only need to repeat this fix if a future build gets interrupted before the automatic cleanup runs.
</Note>


# Using Logs to Debug
Source: https://docs.newly.app/guides/using-logs-to-debug



When the AI keeps guessing, it's usually because it doesn't have the one thing that would make this trivial: the actual error.

## Quick answer

The fix is straightforward. Copy the relevant log, paste it into chat with one line about what you were doing, and that's it. The AI gets the real error message, stack trace, or failing request, and you skip three rounds of "can you describe what you're seeing."

## The 3 types of logs in Newly

Newly provides three different log types, each useful for a different class of problem. Knowing which one to grab will save you prompts and time.

### 1. Frontend logs

Runtime logs from your app in the preview: JavaScript errors, failed network calls from the client, missing imports, render warnings, `console.log` output, all of it.

**Use these when:**

* The app loads but a screen is broken, blank, or shows a red error overlay.
* A button does nothing when tapped.
* You see "Something went wrong" or a JavaScript runtime error.
* Data isn't displaying even though the backend looks fine.

**Where to find them:** In the Logs panel, under Frontend Console Logs.

<Frame>
  <img alt="Frontend Console Logs panel" />
</Frame>

### 2. Backend logs (Specular - Liquid Backend)

Server-side logs from your backend functions and database calls. Newly pulls these from Specular, so you can see what actually happened on the server: failed queries, validation errors, auth failures, any unhandled exceptions.

**Use these when:**

* A request from the app fails or returns a 4xx/5xx error.
* Data isn't being saved or returned correctly.
* Login, signup, or any auth flow is broken.
* The frontend looks fine but something "isn't working" end-to-end.

**Where to find them:** In the Logs panel, under Backend Logs.

<Frame>
  <img alt="Backend Logs panel" />
</Frame>

### 3. Build logs (Deploy)

Pipeline output from a failed Android or iOS build. Dependency resolution errors, native module issues, gradle failures, missing config, invalid app metadata.

**Use these when:**

* Your app build fails and you see an error on the build status screen.
* A previously working build suddenly stops compiling after a change.
* You added a new package or native dependency and the build broke.

**Where to find them:** On the Deploy screen under Build History

<Frame>
  <img alt="Build History on the Deploy screen" />
</Frame>

## Steps to fix an issue using logs

1. Reproduce the problem in the preview (or trigger the failing build).
2. Open the relevant log panel for that problem (frontend, backend, or build).
3. Copy the error message and a few lines of surrounding context – not the entire log file.
4. Paste it into the chat with a one-line description of what you were trying to do.
5. Let the AI propose a fix, then verify in the preview or with a new build.

## Best practices for prompting with logs

* **Match the log type to the problem:** A blank screen is almost always frontend. A 500 from a saved record is backend. "Build failed" is build. Grab the wrong one and you've wasted a prompt.
* **Copy the error, not the entire log:** Logs can run thousands of lines. The AI only needs the actual error, the stack trace, and a bit of surrounding context. Everything else dilutes the signal and sometimes actively confuses the model.
* **Include what you were doing:** "I tapped the Save button on the profile screen and got this error" is far more useful than just dumping a stack trace. The AI needs to know which user action triggered the log.
* **Combine logs with screenshots when relevant:** If a screen looks wrong AND throws an error, paste both. The screenshot shows the symptom, the log shows the cause.
  <Tip>
    **Mac** Press **Shift + Control + Command + 4**, then drag to select an area. The screenshot is copied to your clipboard, ready to paste with **Command + V**.
  </Tip>
  <Tip>
    **Windows** Press **Windows + Shift + S** to open Snipping Tool's snip bar. Choose rectangular, freeform, window, or fullscreen mode, then make your selection. The screenshot is copied to your clipboard, ready to paste with **Ctrl + V**.
  </Tip>
* **For build failures, include the failing step:** For build failures, scroll until you hit a line that says `FAILED` or `error:` and paste from there. and start there. Nobody needs the steps that succeeded.
* **Use Ask mode if you just want an explanation:** It costs about a tenth of a build request and is perfect for "what does this even mean."
* **Don't paste secrets:** Logs sometimes carry API keys, tokens, or user data. Skim before you send.
* **If the same error keeps appearing, use Restore:** When the AI's fix attempts are making things worse, click **Restore** on a known-good message and try again with cleaner context. That's almost always cheaper than prompting your way out of a broken state.

## Example: a good log-based prompt

> I'm getting an error when I tap "Submit" on the signup form. The user isn't created and the screen just freezes.
>
> **Frontend log:**
>
> ```text theme={null}
> ERROR  [TypeError: Cannot read property 'id' of undefined]
>     at SignupScreen.handleSubmit (SignupScreen.tsx:42)
> ```
>
> **Backend log (Specular):**
>
> ```text theme={null}
> [error] insert into "users" failed: duplicate key value violates unique constraint "users_email_key"
> ```
>
> Please fix the signup so it shows a friendly "email already in use" message instead of crashing.

That's the user action, the client-side symptom, the server-side root cause, and the behavior you want. Usually enough to land a fix in one shot.

## Ask the AI to read the log itself

If you don't want to copy-paste the log, you can have the AI go read it for you. This is especially useful for build failures, where the log can be long.

Template:

```
Open the build logs for the most recent failed build, find the specific blocking issue, and either fix it or tell me exactly what's blocking and what's needed to clear it. Do not say it's a platform issue without checking the log first.
```

The last sentence matters. Without it, the AI sometimes defaults to "this must be a Newly platform problem" when it hasn't actually inspected the log. Asking it to check first usually produces a real diagnosis.

The same pattern works for runtime and backend logs:

```
Reproduce the [failing action]. Then open the [frontend / backend] logs, find the error line, and explain what's causing it. Don't change any code yet – show me your findings first.
```

This is the *diagnose-first* pattern from [How to save credits](/guides/save-prompts#diagnose-first-then-fix), applied to logs specifically. It tends to land a fix in one round instead of three.


# Introduction
Source: https://docs.newly.app/index

Build native iOS and Android apps using AI - no coding required

# Welcome to Newly

Newly is an AI-powered platform that enables anyone to create native iOS and Android mobile apps without coding. Simply describe what you want to build in natural language, and watch your app come to life in real-time.

## What Makes Newly Different

Unlike drag-and-drop builders that create web wrappers or PWAs, Newly generates **true native code** using React Native and Expo - the same technology powering apps like Discord, Shopify, and Instagram.

<CardGroup>
  <Card title="Real Native Apps" icon="mobile">
    Generate production-ready iOS and Android apps, not web wrappers
  </Card>

  <Card title="AI-Powered Development" icon="sparkles">
    Describe features in plain English and watch them come to life
  </Card>

  <Card title="Full Code Ownership" icon="code">
    Export your complete source code anytime. No vendor lock-in
  </Card>

  <Card title="Live Preview" icon="eye">
    See changes instantly on a real mobile device preview
  </Card>
</CardGroup>

## Quick Start

Get your first app running in minutes:

<Steps>
  <Step title="Sign Up">
    Create a free account at [newly.app](https://newly.app)
  </Step>

  <Step title="Describe Your App">
    Tell the AI what you want to build. Be as detailed as you like:

    *"Create a workout tracking app where users can log exercises, track their progress with charts, and set weekly goals"*
  </Step>

  <Step title="Preview & Iterate">
    Watch your app come to life in the real-time preview. Chat with the AI to refine and add features.
  </Step>

  <Step title="Deploy">
    When ready, deploy to the App Store and Google Play Store directly from Newly.
  </Step>
</Steps>

## What Can You Build?

Newly excels at building apps with:

* **Beautiful UI** - Modern, polished interfaces with smooth animations
* **Database Integration** - Store and retrieve data with built-in backend support
* **User Authentication** - Login, signup, and user management
* **API Connections** - Connect to any external service or API
* **In-App Purchases** - Monetize with subscriptions via RevenueCat
* **Push Notifications** - Engage users with timely updates
* **Camera & Photos** - Access device camera and photo library
* **Location Services** - GPS and mapping features

<Card title="Browse Example Apps" icon="grid" href="https://newly.app/examples">
  See what others have built with Newly for inspiration
</Card>

## Key Features

<Columns>
  <Card title="AI Chat Interface" icon="message-bot" href="/features/ai-chat">
    Natural language interface to describe features and make changes
  </Card>

  <Card title="Real-time Preview" icon="mobile" href="/features/preview">
    See your app running live as you build
  </Card>

  <Card title="Code Editor" icon="code" href="/features/code-editor">
    Full access to edit generated code directly
  </Card>

  <Card title="Backend Generation" icon="server" href="/features/backend">
    Automatic API and database creation with Liquid Backend
  </Card>

  <Card title="App Store Deployment" icon="rocket" href="/features/deployment">
    Deploy to iOS and Android app stores
  </Card>

  <Card title="GitHub Integration" icon="github" href="/integrations/github">
    Sync your code to a GitHub repository
  </Card>
</Columns>

## Technical Stack

Under the hood, Newly uses industry-standard technologies:

| Component        | Technology                         |
| ---------------- | ---------------------------------- |
| Mobile Framework | React Native with Expo SDK 54      |
| Language         | TypeScript                         |
| Backend          | serverless API + PostgreSQL        |
| Payments         | RevenueCat                         |
| Deployment       | EAS Build (App Store & Play Store) |

## Getting Help

<CardGroup>
  <Card title="Discord Community" icon="discord" href="https://discord.com/invite/sPbqWqgcMf">
    Join our active community for help and inspiration
  </Card>

  <Card title="Example Apps" icon="grid" href="https://newly.app/examples">
    Learn from apps built by others
  </Card>

  <Card title="FAQ" icon="circle-question" href="https://newly.app/faq">
    Common questions answered
  </Card>
</CardGroup>

## Ready to Start?

<Card title="Create Your First App" icon="rocket" href="/quickstart">
  Follow our step-by-step guide to build and deploy your first app
</Card>


# GitHub Integration
Source: https://docs.newly.app/integrations/github

Sync your code to GitHub for version control and collaboration

# GitHub Integration

Connect your Newly project to GitHub to sync code, collaborate with developers, and maintain a backup of your project.

## Why Connect GitHub

<CardGroup>
  <Card title="Version Control" icon="code-branch">
    Full Git history outside of Newly
  </Card>

  <Card title="Collaboration" icon="users">
    Work with other developers on your code
  </Card>

  <Card title="Code Backup" icon="cloud-arrow-up">
    Your code is safe in your own repository
  </Card>

  <Card title="Local Development" icon="laptop-code">
    Clone and run your project locally
  </Card>
</CardGroup>

## Connecting GitHub

<Steps>
  <Step title="Open GitHub Settings">
    Click **More** → look for the GitHub button in the menu
  </Step>

  <Step title="Authorize Newly GitHub App">
    Click **Connect GitHub Account** and install the Newly App on your GitHub account.
    Installing the App does **not** create any repository on its own — it just
    grants Newly permission to create or connect one later.
  </Step>

  <Step title="Choose Create New or Use Existing">
    After install, pick one of:

    * **Create New** — Newly creates a fresh repository under your account (public or private).
    * **Use Existing** — paste a GitHub HTTPS clone URL of a repo you already have access to.
  </Step>

  <Step title="Your code syncs automatically">
    Once a repo is connected, Newly pushes your project to it and keeps it in sync.
  </Step>
</Steps>

## Automatic Syncing

Once connected, Newly automatically:

* **Pushes on commit** - Every change is synced to GitHub
* **Preserves history** - All commit messages are kept
* **Handles conflicts** - AI changes are cleanly merged

<Note>
  Syncing happens automatically when the AI writes code. You don't need to manually push changes or ask the AI to push.
</Note>

## Working Locally

Clone and run your project locally:

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/yourusername/your-app.git
    cd your-app
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Start Expo">
    ```bash theme={null}
    pnpx expo start --tunnel
    ```
  </Step>

  <Step title="Test on Device">
    Scan QR code with Expo Go app or run in simulator
  </Step>
</Steps>

### Local Development Requirements

* Node.js 18+
* pnpm
* Expo CLI (`pnpx expo`)
* iOS Simulator (Mac) or Android Emulator (optional)

## Collaborating with Developers

### Adding Collaborators

1. Go to your repository on GitHub
2. Settings → Collaborators
3. Add team members by username or email

### Development Workflow

For teams, we recommend:

<Steps>
  <Step title="Newly for Design">
    Use Newly to prototype and build features quickly
  </Step>

  <Step title="GitHub for Collaboration">
    Developers clone the repo and make changes locally
  </Step>

  <Step title="Pull Requests">
    Review changes through GitHub PRs
  </Step>

  <Step title="Merge & Sync">
    Merged changes sync back to Newly
  </Step>
</Steps>

## Two-Way Sync

Newly supports syncing changes made outside of Newly:

<Note>
  When you push changes to GitHub from your local machine or via PR, those changes will be synced back to your Newly project.
</Note>

### Handling External Changes

1. Push changes to the `main` branch on GitHub
2. Newly detects the changes on next project open
3. Your project is updated with the external changes
4. AI has context of the new code

## Best Practices

<AccordionGroup>
  <Accordion title="Use meaningful commit messages">
    The AI generates descriptive commit messages, but for local changes, use clear messages like "Add checkout screen" or "Fix navigation bug"
  </Accordion>

  <Accordion title="Don't commit secrets">
    Never commit API keys or passwords. Put secrets on the backend via "Secrets" for Liquid Backend. Commiting secrets will stop the Github connection to work.
  </Accordion>

  <Accordion title="Review AI changes">
    Check the commit history to understand what the AI changed
  </Accordion>
</AccordionGroup>

## Disconnecting GitHub

The GitHub panel exposes three separate actions so you can stop at whichever level you need.

### When a repository is connected

<CardGroup>
  <Card title="Disconnect Repo">
    Unlinks this project from its GitHub repository. The Newly GitHub App stays installed on your account and the repository stays on GitHub untouched — only this project stops syncing to it. You can reconnect the same repo or link a different one immediately.
  </Card>

  <Card title="Delete Repo">
    Same as **Disconnect Repo**, plus deletes the repository from GitHub itself. Your code is still safe in Newly's storage. The GitHub App stays installed.
  </Card>
</CardGroup>

### When no repository is connected

Once you've disconnected or deleted the repo, a third option appears at the bottom of the GitHub panel:

<Card title="Disconnect GitHub">
  Fully removes the Newly GitHub App from your GitHub account. This revokes Newly's access token, uninstalls the App, and clears every project's GitHub link. After this you're back to the **Connect GitHub Account** state.
</Card>

<Note>
  You can also uninstall the Newly App directly from
  [github.com/settings/installations](https://github.com/settings/installations) —
  Newly detects the uninstall automatically and updates the UI the next time
  you return to the tab.
</Note>

<Warning>
  None of these actions delete your code from Newly. Your project continues
  to work; it just stops syncing to GitHub until you connect a repo again.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sync Failed">
    * Check GitHub App authorization is still valid
    * Verify repository exists and you have write access
    * Check for branch protection rules
    * Verify you have no secrets pushed and that chat\_history.json is in .gitignore as it may contain pre-signed urls that Github thinks are secrets.
  </Accordion>

  <Accordion title="Conflicts">
    * Newly uses force push for AI changes
    * If you have local changes, pull before making changes in Newly
  </Accordion>

  <Accordion title="Missing Files">
    * Some files like `.env` are intentionally excluded
    * Check `.gitignore` for excluded patterns
  </Accordion>
</AccordionGroup>

## Private vs Public Repositories

You can choose either:

| Type    | Best For                              |
| ------- | ------------------------------------- |
| Private | Commercial projects, proprietary code |
| Public  | Open source projects, portfolios      |

<Tip>
  GitHub offers free private repositories, so there's no cost for keeping your code private.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Code Editor" icon="code" href="/features/code-editor">
    Learn to edit code directly
  </Card>

  <Card title="Deployment" icon="rocket" href="/features/deployment">
    Deploy your app to stores
  </Card>
</CardGroup>


# OneSignal Integration
Source: https://docs.newly.app/integrations/onesignal

Add push notifications to your app with OneSignal

# OneSignal Integration

OneSignal lets you add push notifications to your Newly app. Connect with one click and the AI sets up the SDK, notification components, and a preferences screen for you. Supports both **iOS** and **Android**.

## What is OneSignal?

OneSignal is a push notification platform that handles delivery, user segmentation, engagement tracking, and rich notifications (images, buttons, deep links).

## Setting Up OneSignal

<Steps>
  <Step title="Open &#x22;More&#x22; in Newly and tap Push Notifications">
    Find the Push Notifications panel in the tool strip.
  </Step>

  <Step title="Press Connect OneSignal">
    Newly creates a OneSignal app and links it to your project automatically. No OneSignal account needed.

    <Frame>
      <img alt="OneSignal connect panel" />
    </Frame>
  </Step>

  <Step title="Configure platform credentials">
    Set up credentials for the platforms you want to support:

    * **iOS**: If you've added Apple credentials in Newly, press **Sync Apple credentials to OneSignal** to configure APNs for iOS push delivery.
    * **Android**: Upload your Firebase service account JSON and `google-services.json` in the Push Notifications panel to enable FCM for Android push delivery. See [Android Configuration](#android-configuration) for details.
  </Step>

  <Step title="Press &#x22;Add push notifications (AI)&#x22;">
    The AI will:

    * Add `NotificationProvider` to your app layout
    * Add a `NotificationBell` component to your home screen
    * Create a notification preferences screen
    * Configure your bundle identifier
  </Step>

  <Step title="Build and test">
    Create a native build and press **Send test notification** to verify everything works.
  </Step>
</Steps>

<Warning>
  Push notifications only work in native builds. They will **not** work in the web preview or Expo Go.
</Warning>

## What Gets Added to Your App

When you connect OneSignal and run the AI setup, three components are added:

| Component                    | Purpose                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| **NotificationProvider**     | Wraps your app layout, initializes the OneSignal SDK, and handles permission prompts |
| **NotificationBell**         | A bell icon for your home screen that shows unread notification count                |
| **Notification Preferences** | A screen where users can manage their notification settings                          |

## Sending Notifications

After setup, you can send notifications by asking the AI to set them up in your app logic. Newly manages the OneSignal connection for you.

<Tabs>
  <Tab title="From Your App">
    Ask the AI to trigger notifications based on events in your app:

    ```
    When a user completes a purchase, send them a
    push notification thanking them for their order.
    ```
  </Tab>

  <Tab title="Segments">
    Target specific user groups:

    ```
    Add a notification that targets users who haven't
    opened the app in 7 days with a re-engagement message.
    ```
  </Tab>

  <Tab title="Test Notification">
    Use the **Send test notification** button in the Push Notifications panel to verify your setup is working.
  </Tab>
</Tabs>

## Common Patterns

<Tabs>
  <Tab title="Welcome Notification">
    ```
    Send a welcome push notification when a new user
    signs up for the first time.
    ```
  </Tab>

  <Tab title="Activity Updates">
    ```
    Notify users when someone comments on their post
    or follows their profile.
    ```
  </Tab>

  <Tab title="Promotional">
    ```
    Set up a notification for a limited-time discount
    that deep links to the offers screen.
    ```
  </Tab>
</Tabs>

## iOS Configuration

iOS requires APNs (Apple Push Notification service) credentials to deliver notifications. You'll need to set up your Apple credentials in Newly first.

<Steps>
  <Step title="Set up Apple credentials">
    Open the **Apple Credentials** panel in Newly. You can either:

    * **Automatic** (recommended): Sign in with your Apple ID and Newly handles the rest
    * **Manual**: Upload your own `.p8` APNs key file from the Apple Developer Portal
  </Step>

  <Step title="Sync to OneSignal">
    In the Push Notifications panel, press **Sync Apple credentials to OneSignal**. This sends your APNs credentials to OneSignal so it can deliver to iOS devices.
  </Step>

  <Step title="Verify">
    The panel will show **APNs credentials detected** when synced successfully.
  </Step>
</Steps>

## Android Configuration

Android requires Firebase Cloud Messaging (FCM) credentials to deliver notifications. You'll need a Firebase project linked to your app.

<Steps>
  <Step title="Create a Firebase project">
    Go to the [Firebase Console](https://console.firebase.google.com) and create a project (or use an existing one). Add an Android app with your app's package name.
  </Step>

  <Step title="Download your credentials">
    You need two files from Firebase:

    * **Service account JSON**: Go to **Project Settings → Service accounts → Generate new private key**. This file lets OneSignal send notifications via FCM.
    * **google-services.json**: Go to **Project Settings → General → Your apps → Download google-services.json**. This file configures your Android app to receive notifications.
  </Step>

  <Step title="Upload to Newly">
    In the Push Notifications panel, find the **Android (FCM)** section and upload both files.
  </Step>

  <Step title="Sync to OneSignal">
    Press **Sync credentials to OneSignal** to send your FCM credentials to OneSignal for Android push delivery.
  </Step>

  <Step title="Verify">
    The panel will show your **Firebase project ID** when configured successfully.
  </Step>
</Steps>

## Testing Notifications

1. Create a **development build** of your app (not Expo Go)
2. Install on a physical device or simulator
3. Accept the push notification permission prompt
4. Go back to the Push Notifications panel in Newly
5. Press **Send test notification**

<Tip>
  If the test notification doesn't arrive, make sure your platform credentials are synced (APNs for iOS, FCM for Android) and that the app has notification permissions enabled on the device.
</Tip>

## Best Practices

<CardGroup>
  <Card title="Don't Spam" icon="bell-slash">
    Only send notifications users care about. Too many and they'll uninstall.
  </Card>

  <Card title="Personalize" icon="user">
    Use segments and user data to send relevant messages
  </Card>

  <Card title="Respect Preferences" icon="sliders">
    Let users control which notifications they receive
  </Card>

  <Card title="Time It Right" icon="clock">
    Schedule notifications for when users are most likely to engage
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Notifications not arriving">
    * Make sure you're testing on a **native build**, not Expo Go or web preview
    * Check that the device has notification permissions enabled
    * **iOS**: Verify APNs credentials are synced in the Push Notifications panel
    * **Android**: Verify FCM credentials are uploaded and synced
  </Accordion>

  <Accordion title="APNs not detected">
    * Add your Apple credentials in the Apple Credentials panel first
    * Then press **Sync Apple credentials to OneSignal** in the Push Notifications panel
    * If it still fails, double check your APNs Auth Key, Key ID, and Team ID
  </Accordion>

  <Accordion title="FCM credentials not working">
    * Make sure you uploaded both the **service account JSON** and **google-services.json**
    * Re-download fresh files from the Firebase Console if in doubt
    * Ensure the Firebase project has Cloud Messaging API enabled
  </Accordion>

  <Accordion title="Test notification sent but not received">
    * Make sure the app was opened at least once after installing the native build
    * Check that the user accepted the notification permission prompt
    * **iOS**: Ensure APNs credentials are synced
    * **Android**: Ensure FCM credentials are uploaded and synced
    * Try uninstalling and reinstalling the app, then send again
  </Accordion>

  <Accordion title="Connect button fails">
    * Check your internet connection
    * Try refreshing the page and connecting again
    * If it keeps failing, disconnect and reconnect OneSignal
  </Accordion>

  <Accordion title="Build still uses my old bundle ID after I renamed it">
    Bundle ID changes need two steps. Saving the new bundle ID in Apple Credentials updates your project and `app.json`, but it doesn't automatically push the new value to OneSignal's APNs config. To finish the update:

    1. **More → Push Notifications**, then click **Configure platforms**. This pushes the current bundle ID to OneSignal's APNs platform config.

    Alternatively, you can **Disconnect** OneSignal and **Connect** it again – reconnecting calls Configure platforms automatically.

    See the full walkthrough in [Changing your bundle ID](/guides/bundle-id-changes).
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup>
  <Card title="OneSignal Docs" icon="book" href="https://documentation.onesignal.com">
    Official OneSignal documentation
  </Card>

  <Card title="Push Notification Guide" icon="bell" href="https://documentation.onesignal.com/docs/push-notification-guide">
    Best practices for push notifications
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Deployment" icon="rocket" href="/features/deployment">
    Deploy your app with push notifications
  </Card>

  <Card title="RevenueCat" icon="credit-card" href="/integrations/revenuecat">
    Add in-app purchases and subscriptions
  </Card>
</CardGroup>


# RevenueCat Integration
Source: https://docs.newly.app/integrations/revenuecat

Add in-app purchases and subscriptions to your app

# RevenueCat Integration

RevenueCat makes it easy to add in-app purchases and subscriptions to your Newly app. Handle payments, manage subscriptions, and track revenue without complex payment infrastructure.

## What is RevenueCat?

RevenueCat is a subscription management platform that:

* **Handles payments** - Process iOS and Android purchases
* **Manages subscriptions** - Track status, renewals, cancellations
* **Syncs across platforms** - One subscription works on both iOS and Android
* **Provides analytics** - Revenue, churn, and subscriber metrics

## Setting Up RevenueCat

<Steps>
  <Step title="Press on &#x22;More&#x22; in Newly and then RevenueCat">
    You will be prompted to create an account / sign in to your RevenueCat account and authorize permissions to Newly.
  </Step>

  <Step title="Create a Project & Press Connect">
    Create a new project in RevenueCat
  </Step>

  <Step title="Create a Project & Press Connect">
    Newly automatically creates a Paywall, product, entitlements and connects this to your app with 1 prompt.
  </Step>

  <Step title="Configure App Store Connect">
    Add your iOS app with App Store Connect credentials
  </Step>

  <Step title="Configure Play Console">
    Add your Android app with Google Play Console credentials
  </Step>

  <Step title="Market app & make money" />
</Steps>

## Modifying Purchases to Your App

Tell the AI what you want to sell:

```
Add a premium subscription with monthly ($9.99) and yearly ($79.99) options.
Show a paywall screen when users try to access premium features.
After purchase, unlock the premium features.
```

### Common Patterns

<Tabs>
  <Tab title="Paywall Screen">
    ```
    Create a paywall screen that shows:
    - List of premium features
    - Monthly and yearly pricing options
    - "Restore Purchases" button (required for App Store)
    - Terms and privacy links at bottom (required for App Store)
    ```
  </Tab>

  <Tab title="Feature Gating">
    ```
    Make the AI chat feature premium-only.
    When non-subscribers tap it, show the paywall.
    Subscribers should have unlimited access.
    ```
  </Tab>

  <Tab title="Consumable Purchase">
    ```
    Add a "credits" system where users can buy
    100 credits for $4.99. Deduct credits when
    they use premium features.
    ```
  </Tab>
</Tabs>

## Purchase Types

RevenueCat supports:

| Type               | Description                 | Example                |
| ------------------ | --------------------------- | ---------------------- |
| **Subscription**   | Recurring payment           | Monthly premium access |
| **Non-consumable** | One-time permanent purchase | Remove ads forever     |
| **Consumable**     | Single-use purchases        | Credits, tokens        |

## Entitlements

Entitlements are what users get access to after purchasing:

```
Create a "premium" entitlement that includes:
- Unlimited projects
- AI assistance
- Priority support
- Custom themes

Both monthly and yearly subscriptions grant "premium" entitlement.
```

## Checking Subscription Status

The AI will generate code to check if users have active subscriptions:

```tsx theme={null}
// Example generated code
const { customerInfo } = await Purchases.getCustomerInfo();
const isPremium = customerInfo.entitlements.active['premium'];

if (isPremium) {
  // Show premium features
} else {
  // Show paywall
}
```

## Restore Purchases

Always include a restore option for users who:

* Reinstall the app
* Switch devices
* Had billing issues

```
Add a "Restore Purchases" button in settings that
checks for previous purchases and restores access.
```

## Testing Purchases

### Sandbox Testing

Before going live:

1. Use Apple/Google sandbox accounts
2. Purchases are simulated (no real charges)
3. Subscription periods are shortened for testing

<Tabs>
  <Tab title="iOS">
    Use a Sandbox Apple ID created in App Store Connect
  </Tab>

  <Tab title="Android">
    Add license testers in Google Play Console
  </Tab>
</Tabs>

### RevenueCat Dashboard

Monitor purchases in the RevenueCat dashboard:

* Active subscriptions
* Revenue metrics
* Customer history
* Error logs

## Best Practices

<CardGroup>
  <Card title="Clear Value Proposition" icon="star">
    Show what users get before asking them to pay
  </Card>

  <Card title="Multiple Options" icon="list">
    Offer monthly and yearly (with discount) options
  </Card>

  <Card title="Free Trial" icon="gift">
    Consider offering a free trial period
  </Card>

  <Card title="Restore Button" icon="rotate">
    Always include restore purchases option
  </Card>
</CardGroup>

## App Store Requirements

Both app stores have requirements for in-app purchases:

### Apple App Store

* Must use Apple's IAP for digital goods
* Clearly display pricing
* Terms of service required
* Auto-renewal disclosure

### Google Play Store

* Must use Google Play Billing for digital goods
* Clear subscription terms
* Easy cancellation access
* Price displayed before purchase

<Warning>
  Violating app store payment policies can result in app rejection or removal.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Purchases Not Working">
    * Verify RevenueCat is connected correctly
    * Check product IDs match in app and stores
    * Ensure app is properly configured in App Store Connect / Play Console
  </Accordion>

  <Accordion title="Restore Not Finding Purchases">
    * User must be signed into same App Store / Play Store account
    * Check sandbox vs production environment
    * Verify subscription hasn't expired
  </Accordion>

  <Accordion title="Entitlement Not Granted">
    * Check RevenueCat dashboard for the purchase
    * Verify entitlement is linked to product
    * Check for webhook configuration issues
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup>
  <Card title="RevenueCat Docs" icon="book" href="https://docs.revenuecat.com">
    Official RevenueCat documentation
  </Card>

  <Card title="Pricing Best Practices" icon="dollar-sign" href="https://www.revenuecat.com/blog/growth/subscription-pricing-guide/">
    Guide to subscription pricing
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Deployment" icon="rocket" href="/features/deployment">
    Deploy your app with payments
  </Card>

  <Card title="Backend Features" icon="server" href="/features/backend">
    Add backend functionality
  </Card>
</CardGroup>


# Supabase Integration
Source: https://docs.newly.app/integrations/supabase

Connect Supabase for database and authentication via OAuth

# Supabase Integration

Supabase is an open-source Firebase alternative providing PostgreSQL database, authentication, storage, and edge functions. This guide covers how Supabase works with Newly.

## How Supabase Works in Newly

In general, when creating a project in Newly, Liquid Backend is automatically enabled if your prompt covers anything that might need backend functionality.

<Note>
  **Not sure which backend you're using?** If the tab labeled "Database" instead shows "Supabase", your project is connected to Supabase. See [Backend Systems](/features/backend) for details.
</Note>

If you have good reasons for using supabase instead, such as; already having a website with Supabase and you want to use the same database for your app - then you can go to "More" and connect your Supabase account.

After connecting, the AI automatically has access to update your database schema, add or modify edge functions, alter RLS policies and view edge function logs.

## Connecting Supabase

Newly uses OAuth to securely connect to your Supabase project—no manual API keys required.

<Steps>
  <Step title="Open Supabase Settings">
    Click **More** → **Supabase** in the project menu
  </Step>

  <Step title="Connect via OAuth">
    Click "Connect Supabase" and sign in to your Supabase account
  </Step>

  <Step title="Authorize Access">
    Grant Newly permission to access your Supabase projects
  </Step>

  <Step title="Select Project">
    Choose the Supabase project you want to connect
  </Step>

  <Step title="Connected">
    Your Supabase project is now linked to your Newly app
  </Step>
</Steps>

<Tip>
  The OAuth connection handles all authentication automatically. You don't need to manually copy API keys or configure environment variables for the Supabase connection.
</Tip>

## Using Supabase in Your App

Once connected, tell the AI what you want to build:

```
Create a posts feature using my Supabase database.
Show a list of posts and let users create new ones.
```

The AI will generate the appropriate code to interact with your Supabase database.

### What You Can Ask For

* **Database operations** - Create, read, update, delete records
* **Authentication** - Sign up, login, password reset using Supabase Auth
* **Storage** - Upload and display images and files
* **Realtime** - Subscribe to live database changes

## Managing Your Database

When your project is connected to Supabase, the **Database** tab shows your Supabase project details, secrets, and a link to open the Supabase Dashboard instead of Newly's built-in table browser. Full data management — browsing rows, running SQL, editing schema — still happens in the Supabase Dashboard.

### Supabase Dashboard

Manage your database at [supabase.com/dashboard](https://supabase.com/dashboard):

| Feature             | Where to Find     |
| ------------------- | ----------------- |
| **View/Edit Data**  | Table Editor      |
| **Run SQL Queries** | SQL Editor        |
| **Create Tables**   | Database → Tables |
| **Manage Auth**     | Authentication    |
| **File Storage**    | Storage           |
| **Edge Functions**  | Edge Functions    |

### Creating Tables

In Supabase Dashboard:

1. Go to **Table Editor**
2. Click **New Table**
3. Define columns with types and constraints
4. Enable Row Level Security (RLS)

<Warning>
  Always enable Row Level Security (RLS) on your tables for security. Without RLS, anyone with your project URL could access your data.
</Warning>

## Authentication with Supabase

Supabase Auth provides multiple authentication methods:

```
Add login and signup using Supabase authentication.
Support email/password.
```

<Warning>
  **Social login like Google OAuth require a Google OAuth key to be set up in Google Cloud for Supabase projects - Liquid Backend provides Google OAuth without any setup for development purposes.**
</Warning>

<Card title="Apple & Google Login with Supabase" icon="fingerprint" href="/guides/supabase-social-login">
  Step-by-step walkthrough for adding Sign in with Apple and Sign in with Google to a Supabase-backed app.
</Card>

### Supported Auth Methods

| Method         | Setup Required                  |
| -------------- | ------------------------------- |
| Email/Password | Ready to use                    |
| Magic Links    | Ready to use                    |
| Google OAuth   | Configure in Supabase Dashboard |
| Apple OAuth    | Configure in Supabase Dashboard |
| GitHub OAuth   | Configure in Supabase Dashboard |
| Phone/SMS      | Requires Twilio setup           |

## Viewing Supabase Logs

Access logs in the Supabase Dashboard:

1. Go to [supabase.com/dashboard](https://supabase.com/dashboard)
2. Select your project
3. Click **Logs** in the sidebar

| Log Type               | What It Shows                        |
| ---------------------- | ------------------------------------ |
| **API Logs**           | REST API requests, response codes    |
| **Postgres Logs**      | Database queries, errors             |
| **Auth Logs**          | Login attempts, signups, OAuth flows |
| **Edge Function Logs** | Serverless function execution        |
| **Realtime Logs**      | WebSocket subscription events        |

### Frontend Logs in Newly

While Supabase logs aren't directly available in Newly, you can still view frontend console logs:

1. Click the **Logs** icon in the preview header
2. View console.log output, errors, and warnings from your React Native code

## Row Level Security (RLS)

RLS is crucial for Supabase security. Configure policies in the Supabase Dashboard under **Authentication → Policies**.

Common patterns:

* **Users read own data** - Only see records where user\_id matches
* **Public read, authenticated write** - Anyone can view, only logged-in users can create
* **Admin access** - Full access for admin users

<Warning>
  Without RLS enabled, your data is publicly accessible. Always configure appropriate policies before going to production.
</Warning>

## Storage

For file uploads, tell the AI:

```
Let users upload profile pictures and display them on their profile.
Store the images in Supabase Storage.
```

Configure storage buckets and policies in the Supabase Dashboard under **Storage**.

## Edge Functions

For server-side logic requiring secrets (like OpenAI API calls), use Supabase Edge Functions:

1. Create functions in Supabase Dashboard → Edge Functions
2. Deploy via Supabase CLI
3. Tell the AI to call your edge function from the app

<Note>
  Edge Functions are useful when you need server-side processing that can't be done safely in the frontend.
</Note>

## Migrating from Liquid Backend to Supabase

<Warning>
  **Migration from Supabase to Liquid Backend is not possible.** However, you can migrate from Liquid Backend to Supabase if you have specific requirements that only Supabase can meet.
</Warning>

### When to Consider Migration

In most cases, **Liquid Backend will get you further**. Consider Supabase only if you already have a website with Supabase or an existing Supabase database that you need to use.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed">
    * Try disconnecting and reconnecting via **More** → **Supabase**
    * Check your Supabase project isn't paused (free tier pauses after inactivity)
    * Verify you authorized the correct Supabase account
  </Accordion>

  <Accordion title="Permission denied / 403errors when using the app">
    * Ask Newly AI about Row Level Security policies
    * Manually check Row Level Security policies in Supabase Dashboard
    * Verify the user is authenticated if your policies require it
    * Review policies under Authentication → Policies
  </Accordion>

  <Accordion title="Can't see backend logs">
    Backend logs for Supabase are only available in the Supabase Dashboard, not in Newly. Go to supabase.com/dashboard → Logs.
  </Accordion>

  <Accordion title="Data not showing in app">
    * Check the Table Editor in Supabase Dashboard to verify data exists
    * Check RLS policies aren't blocking access
    * Look at API Logs in Supabase for errors
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup>
  <Card title="Supabase Docs" icon="book" href="https://supabase.com/docs">
    Official Supabase documentation
  </Card>

  <Card title="Supabase Dashboard" icon="gauge" href="https://supabase.com/dashboard">
    Manage your database
  </Card>

  <Card title="Backend Systems" icon="server" href="/features/backend">
    Compare Supabase vs Liquid Backend
  </Card>

  <Card title="Liquid Backend" icon="bolt" href="/features/backend">
    Liquid Backend documentation
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.newly.app/quickstart

Build your first mobile app in under 10 minutes

# Build Your First App

This guide walks you through creating and deploying a complete mobile app using Newly. By the end, you'll have a working app you can preview on your phone.

## Prerequisites

* A free Newly account ([sign up here](https://newly.app))
* A mobile device or the preview in your browser

## Step 1: Create a New Project

<Steps>
  <Step title="Go to the Dashboard">
    Visit [newly.app](https://newly.app) and sign in to your account.
  </Step>

  <Step title="Start a New Project">
    Click the input box on the dashboard and describe what you want to build.

    <Tip>
      Be specific! The more details you provide, the better your app will be.
    </Tip>
  </Step>
</Steps>

### Example Prompts

Here are some example prompts to get you started:

<AccordionGroup>
  <Accordion title="Task Manager App">
    ```
    Create a task manager app where users can:
    - Add tasks with a title and due date
    - Mark tasks as complete
    - Filter between active and completed tasks
    - Swipe to delete tasks
    Use a clean, minimal design with a blue color scheme.
    ```
  </Accordion>

  <Accordion title="Recipe Book App">
    ```
    Build a recipe collection app where users can:
    - Browse recipes in a grid layout with photos
    - Search recipes by name or ingredient
    - View detailed recipe with ingredients and steps
    - Save favorite recipes
    Make it look like a modern cooking magazine.
    ```
  </Accordion>

  <Accordion title="Expense Tracker">
    ```
    Create an expense tracker with:
    - Add expenses with amount, category, and date
    - View monthly spending summary with a chart
    - Category breakdown (food, transport, entertainment, etc.)
    - List of recent transactions
    Use a finance-style dark theme.
    ```
  </Accordion>
</AccordionGroup>

## Step 2: Watch Your App Being Built

Once you submit your prompt, the AI will:

1. **Analyze your request** - Understand what features you need
2. **Generate the code** - Create all the screens and components
3. **Build and compile** - Package everything into a working app
4. **Show the preview** - Display your app in the live preview

<Note>
  The first build takes about 1-2 minutes. Subsequent changes are much faster.
</Note>

## Step 3: Preview Your App

The preview panel on the right shows your running app. You can:

* **Interact with it** - Tap buttons, navigate between screens
* **Test features** - Add data, see how everything works
* **Check responsiveness** - The preview matches a real device

### Preview on Your Phone

For the best experience, preview on your actual device:

1. Click the **QR Code** icon in the preview header
2. Scan the QR code with your phone's camera
3. Open the link in Expo Go app (download from App Store/Play Store)

<Warning>
  Make sure your phone is on the same network as your computer for the preview to work.
</Warning>

## Step 4: Refine with AI Chat

Use the chat panel to make changes and add features:

<Tabs>
  <Tab title="Adding Features">
    ```
    Add a settings screen where users can:
    - Toggle dark mode
    - Change notification preferences
    - View app version
    ```
  </Tab>

  <Tab title="Fixing Issues">
    ```
    The submit button on the add task screen isn't working.
    When I tap it, nothing happens.
    ```
  </Tab>

  <Tab title="Changing Design">
    ```
    Change the color scheme to use purple instead of blue.
    Make the headers larger and add more spacing between items.
    ```
  </Tab>
</Tabs>

### Tips for Effective Prompts

<CardGroup>
  <Card title="Be Specific" icon="bullseye">
    Instead of "make it look better", say "increase the font size to 18px and add more padding"
  </Card>

  <Card title="Reference Screens" icon="mobile">
    Mention specific screens: "On the profile screen, add a logout button"
  </Card>

  <Card title="Describe Behavior" icon="hand-pointer">
    Explain what should happen: "When I tap the heart icon, it should save the item"
  </Card>

  <Card title="Include Examples" icon="lightbulb">
    Give examples: "Show prices like '\$29.99' not '29.99 dollars'"
  </Card>
</CardGroup>

## Step 5: Add Backend Features (Optional)

If your app needs to save data or have user accounts, the AI will automatically use Liquid Backend to create your backend.

Example prompts that trigger backend creation:

```
Add user authentication so people can create accounts and log in.
Their data should be saved to their account.
```

```
When a user saves a recipe, store it in the database so they
can access it on any device.
```

<Info>
  Learn more about backend features in our [Backend Generation guide](/features/backend).
</Info>

## Step 6: Deploy Your App

When you're ready to share your app:

<Steps>
  <Step title="Open Deploy Menu">
    Click the **More** button in the header and select **Deploy App**.
  </Step>

  <Step title="Choose Platform">
    * **APK** - Android installable file (for testing)
    * **AAB** - Android bundle (for Play Store)
    * **iOS** - App Store build
  </Step>

  <Step title="Configure & Build">
    Follow the on-screen instructions to configure your app icon, name, and build settings.
  </Step>
</Steps>

<Card title="Deployment Guide" icon="rocket" href="/features/deployment">
  See the full deployment guide for App Store and Play Store submission
</Card>

## Next Steps

Now that you've built your first app, explore more features:

<CardGroup>
  <Card title="AI Chat Deep Dive" icon="message-bot" href="/features/ai-chat">
    Master the AI chat for faster development
  </Card>

  <Card title="Code Editor" icon="code" href="/features/code-editor">
    Edit generated code directly
  </Card>

  <Card title="Connect Supabase" icon="database" href="/integrations/supabase">
    Use Supabase for advanced database features
  </Card>

  <Card title="Add Payments" icon="credit-card" href="/integrations/revenuecat">
    Monetize with in-app purchases
  </Card>
</CardGroup>

## Getting Help

Stuck on something? Here's how to get help:

* **Discord Community** - Get real-time help from the community and team
* **Example Apps** - See how others solved similar problems
* **AI Chat** - Ask the AI to explain or fix issues

<Card title="Join Discord" icon="discord" href="https://discord.com/invite/sPbqWqgcMf">
  Join our active community of builders
</Card>


# App Store Connect Setup
Source: https://docs.newly.app/subscriptions/app-store-connect-setup

Connect your Apple Developer account and automate App Store Connect configuration

## Prerequisites

To create subscriptions and submit your app to the App Store, you need an [Apple Developer Program](https://developer.apple.com/programs/) membership.

<Warning>
  The Apple Developer Program costs **\$99 USD/year**. This is separate from a free Apple ID — you must be enrolled in the paid developer program. [Enroll here](https://developer.apple.com/programs/enroll/).
</Warning>

## Connecting your Apple account

1. Open the **Deploy modal** in the Newly dashboard (click "Deploy" on your project)
2. Click **Build & Deploy** and select **iOS**
3. The Apple Credentials section will appear

You have two options:

### Automatic setup (recommended)

1. Enter your **Apple ID** email and password
2. Complete **two-factor authentication** if prompted (code sent to your trusted device or phone)
3. **Select your team** from the list of teams associated with your Apple account
4. Newly **auto-provisions all required keys** — you'll see checkmarks as each one is created
5. **Select or create your app** — Newly pre-fills the name and bundle ID from your project

### Manual setup

If you prefer to manage your own keys, you can upload them individually:

* **ASC API Key** — Key ID + .p8 private key file
* **IAP Key** — Key ID + .p8 private key file
* **APNs Key** — Key ID + .p8 private key file
* **Team ID** and **Bundle ID**

You can find or create these in the [Apple Developer portal](https://developer.apple.com/account/resources/authkeys/list) under Keys.

<Tip>
  Credentials are stored encrypted and shared across all your Newly projects — you only need to connect your Apple account once.
</Tip>

## What gets auto-provisioned

During automatic setup, Newly creates three API keys in your Apple Developer account:

| Key                   | Purpose                                                               |
| --------------------- | --------------------------------------------------------------------- |
| **ASC API Key** (.p8) | Manage products and subscriptions in App Store Connect                |
| **IAP Key** (.p8)     | Allow RevenueCat to validate subscription receipts from the App Store |
| **APNs Key** (.p8)    | Enable push notifications (e.g., subscription renewal reminders)      |

These keys are visible in your [Apple Developer account](https://developer.apple.com/account/resources/authkeys/list) under Keys.

## How products get created in App Store Connect

Once your Apple credentials and RevenueCat catalog both exist, Newly automatically creates matching products in App Store Connect:

* A **subscription group** called "NSubscriptions"
* **Subscription products** with the same product IDs as your RevenueCat catalog
* **English localizations** for each product

These products appear in your App Store Connect account ready for App Review — no manual product creation needed.

<Info>
  **Setup order doesn't matter.** You can connect Apple first and RevenueCat later, or the other way around. Newly detects which pieces are already in place and fills in the gaps automatically.
</Info>

## Production SDK keys

After the store setup completes, Newly:

1. Creates **App Store** and **Play Store** app entries in your RevenueCat project
2. Attaches your Apple credentials (ASC + IAP keys) to the RevenueCat app
3. Fetches **production SDK keys** (`appl_*` for iOS, `goog_*` for Android)
4. Writes the keys to your app's `app.json` automatically

See [Technical Details](/subscriptions/technical-details) for the full list of keys and generated files.

***

## Under the hood

You don't need to know this to use Newly, but it may help if you're debugging or curious about how the automation works.

### Idempotent operations

All automated operations are safe to run multiple times:

* **Catalog creation** skips products that already exist in RevenueCat
* **ASC product creation** skips subscriptions that already exist in App Store Connect
* **Store setup** updates credentials on existing RevenueCat apps rather than creating duplicates

This means retrying a failed setup or re-running the flow won't create duplicate products or break your configuration.

### Token management

RevenueCat OAuth tokens expire after approximately 1 hour. Newly handles this automatically:

* Tokens are **auto-refreshed** before API calls when expired
* **Concurrent requests** are handled safely — if multiple operations detect an expired token at the same time, only one refresh happens and the others pick up the new token
* If auto-refresh fails (e.g., the token was revoked), you'll see a "Reconnect RevenueCat" prompt

### Retrigger mechanism

When you upload Apple credentials after RevenueCat is already connected, a background task automatically:

1. Re-runs store setup (attaches credentials to your RevenueCat apps)
2. Creates ASC subscription products (if your catalog already exists)
3. Fetches updated production keys

This runs in the background — you can continue working while it completes. The retrigger fires from any Apple credential action: auto-provisioning, manual key upload, or app selection.

### Product ID uniqueness

Product identifiers in App Store Connect are **globally unique and can never be reused** — even after deletion. To prevent collisions, Newly appends a project-scoped hash to each product ID:

```
pro_monthly_9_99_a1b2c3
└── price ──────┘ └─ project hash
```

This ensures your products never conflict with other apps or previously deleted products.

### Credential reference

| Credential        | Purpose                           | How it's obtained                 |
| ----------------- | --------------------------------- | --------------------------------- |
| ASC API Key (.p8) | Manage App Store Connect products | Auto-provisioned or manual upload |
| IAP Key (.p8)     | RevenueCat receipt validation     | Auto-provisioned or manual upload |
| APNs Key          | Push notifications                | Auto-provisioned                  |
| RC Access Token   | RevenueCat API calls              | OAuth flow, auto-refreshed hourly |
| RC Refresh Token  | Refresh the access token          | OAuth flow, rotated on each use   |


# Authentication & Subscriptions
Source: https://docs.newly.app/subscriptions/authentication

How authentication affects purchase syncing and what happens without it

## Do I need authentication?

**No — subscriptions work without authentication.** Your app can process purchases in anonymous mode. However, there's an important trade-off.

## With authentication

When your app has authentication (e.g. via Clerk or Supabase), Newly automatically:

* Syncs purchases to the user's account via their user ID
* Enables **cross-device purchase syncing** — if a user subscribes on one device, their subscription is recognized on all devices where they're signed in
* Handles restore purchases automatically when a user signs in on a new device

## Without authentication (anonymous mode)

When there's no authentication:

* Purchases work normally on the device where they were made
* **Purchases do not sync across devices** — if a user switches phones or reinstalls the app, their subscription won't carry over
* Users would need to use Apple/Google's built-in restore purchases to recover their subscription on a new device

<Warning>
  Without authentication, if a user reinstalls your app or switches to a new device, they will appear as a new (non-subscribed) user. Their subscription still exists in the App Store/Play Store, but the app won't know about it until they manually restore purchases.
</Warning>

## Recommended approach

<Tip>
  **Set up authentication before adding subscriptions.** This gives your users the best experience with automatic cross-device syncing. The AI agent will also recommend this order.
</Tip>

If you add subscriptions first and authentication later, the system will automatically adapt — it detects the auth context and adds user ID syncing to the subscription provider.

## Restore Purchases button

<Info>
  **Apple requires a Restore Purchases button** (App Store Review Guideline 3.1.1) for any app with in-app purchases or subscriptions. Make sure your app includes a visible way for users to restore previous purchases. If it doesn't, ask the AI to add one.
</Info>


# How Subscription Setup Works
Source: https://docs.newly.app/subscriptions/overview

What Newly automates when you add subscriptions to your app

Newly handles most of the RevenueCat setup automatically. Here's what happens when you add subscriptions to your app.

## One-click setup

When you ask the AI to add a paywall or subscriptions, the flow is:

<Steps>
  <Step title="Connect your RevenueCat account">
    An OAuth popup lets you connect your RevenueCat account. This gives Newly permission to create products and fetch API keys on your behalf.
  </Step>

  <Step title="Choose your price">
    You pick a monthly subscription price (e.g. \$9.99/month). Newly does the rest.
  </Step>

  <Step title="Everything gets created automatically">
    Newly creates the following in your RevenueCat dashboard:

    * An **entitlement** (always named "pro")
    * A **product** with your chosen price
    * An **offering** and **package** linking them together
    * **App Store** and **Play Store** apps in RevenueCat
    * **App Store Connect** subscriptions and products

    Then the AI agent generates all the code in your app:

    * `SubscriptionContext.tsx` — provider with RevenueCat SDK
    * A paywall screen at `/paywall`
    * Integration into your onboarding flow
    * SDK API keys in `app.json`
  </Step>
</Steps>

## What gets automated

| Step                          | Manual?    | Notes                                    |
| ----------------------------- | ---------- | ---------------------------------------- |
| RevenueCat account connection | One click  | OAuth flow                               |
| Price selection               | You choose | Monthly billing, one price per product   |
| Product catalog creation      | Automatic  | Entitlement, product, offering, package  |
| App Store app creation in RC  | Automatic  | iOS + Android                            |
| App Store Connect products    | Automatic  | Subscriptions and IAP configuration      |
| SDK key fetching              | Automatic  | Test + production keys                   |
| Code generation               | Automatic  | Context, paywall, onboarding integration |
| Paywall UI                    | Automatic  | AI generates based on your app           |

## The "pro" entitlement

Newly uses a single entitlement called **"pro"** for all subscriptions. Custom entitlement names are not supported. If a different name is accidentally set, the system auto-corrects it to "pro".

<Note>
  You don't need to worry about entitlement names — the system handles this automatically. If you see "pro" in your RevenueCat dashboard, that's expected.
</Note>

## Navigation order

When you have authentication, onboarding, and a paywall, Newly enforces a deterministic navigation order:

1. **Authentication** — user signs in or creates account
2. **Onboarding** — app onboarding screens
3. **Paywall** — subscription screen

This order is enforced regardless of the sequence you set things up in.


# Pricing & Products
Source: https://docs.newly.app/subscriptions/pricing-and-products

Custom prices, multiple apps, and current pricing limitations

## Custom prices

You can set a custom price during the catalog setup step. You're not limited to default price tiers — pick any monthly price that works for your app.

<Note>
  Newly currently supports **monthly subscriptions only** — annual and other billing periods are not yet available. Each product supports a single price. Modifying the price after initial setup is not yet supported.
</Note>

## Multiple apps

Each app you create in Newly gets its own isolated RevenueCat project. This means:

* **No collisions** between apps, even if they share the same name or slug
* **Product identifiers are unique** per project
* **API keys are separate** for each app
* Storage keys include your project ID to prevent conflicts

## Single subscription tier

Newly currently supports a single subscription tier with the "pro" entitlement and a single monthly price. Modifying the price or adding multiple tiers (e.g. Basic, Pro, Enterprise) is not yet supported. If you need these features, you would need to configure them manually in RevenueCat and update the generated code.


# Technical Details
Source: https://docs.newly.app/subscriptions/technical-details

What gets added to your app — configuration keys, generated files, and important caveats

## Keys in app.json

After setup, the following keys are added to your `app.json` (under the `extra` field):

| Key                       | Example    | Description                             |
| ------------------------- | ---------- | --------------------------------------- |
| `revenueCatApiKeyIos`     | `appl_...` | Production iOS API key                  |
| `revenueCatApiKeyAndroid` | `goog_...` | Production Android API key              |
| `revenueCatTestApiKey`    | `test_...` | Test Store key for dev builds           |
| `revenueCatEntitlementId` | `pro`      | The entitlement to check (always "pro") |

The app automatically selects test keys in development (`__DEV__` is true) and production keys in release builds.

## Generated files

The AI agent creates or modifies these files:

| File                      | Purpose                                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `SubscriptionContext.tsx` | React context provider wrapping the RevenueCat SDK. Handles initialization, purchase state, and optionally syncs user ID if auth exists. |
| `/paywall` screen         | The paywall UI where users can subscribe. Shows pricing, features, and purchase buttons.                                                 |
| `_layout.tsx`             | Modified to wrap the app in `SubscriptionProvider` and add a `SubscriptionRedirect` for enforcing the paywall.                           |
| Onboarding integration    | If onboarding exists, the paywall is wired into the flow after onboarding completes.                                                     |

## Dependencies

The `react-native-purchases` package is installed automatically.

<Warning>
  **Do not add `react-native-purchases` to the `plugins` array in `app.json`.** This causes build errors. The SDK is configured entirely through `SubscriptionContext.tsx`, not as an Expo plugin.
</Warning>

## How API key switching works

The generated `SubscriptionContext.tsx` includes logic like:

```javascript theme={null}
const apiKey = __DEV__ && testApiKey ? testApiKey : platformApiKey;
```

* In development builds, the Test Store key is used so you can simulate purchases safely
* In production builds, the real iOS or Android key is used for actual App Store / Play Store purchases
* This switching is automatic — you don't need to change anything between environments

## Storage key scoping

To prevent conflicts between multiple apps that might share the same Expo slug, the subscription context uses your Newly project ID in its storage key. This ensures subscription state is isolated per-app.


# Testing Purchases
Source: https://docs.newly.app/subscriptions/testing

How to test subscriptions in Expo Go, dev builds, web preview, and production

## Expo Go limitations

<Warning>
  **Purchases do not work in standard Expo Go.** The RevenueCat SDK and SecureStore (used for credential storage) are not available in Expo Go.
</Warning>

To test real purchases, you need either:

* A **custom dev build** (`npx expo prebuild` then build for your device)
* A **production build** (through app store or ad-hoc distribution)

## Test vs production API keys

Newly automatically manages two sets of API keys:

| Environment        | Key type                            | When used               |
| ------------------ | ----------------------------------- | ----------------------- |
| Dev/Preview builds | Test Store keys (`test_*`)          | When `__DEV__` is true  |
| Production builds  | iOS (`appl_*`) / Android (`goog_*`) | When `__DEV__` is false |

**You don't need to manage this manually.** The app automatically uses test keys in development and real keys in production. The switching happens at runtime based on React Native's `__DEV__` flag.

## Web preview

You can preview your paywall in the web browser. Here's how it works:

* **Pricing is real** — mock data is fetched from your RevenueCat dashboard so prices shown match your actual product configuration
* **Purchases are simulated** — no real charges occur in web preview
* **Purchases persist** — test purchases persist across page reloads so you can test the full flow

<Tip>
  Web preview is great for testing your paywall UI and flow. For testing actual purchase mechanics, use a dev build or production build on a real device.
</Tip>

## Testing checklist

<Steps>
  <Step title="Test in web preview first">
    Verify the paywall looks correct and the flow works end-to-end.
  </Step>

  <Step title="Build a dev build">
    Run `npx expo prebuild` and build for your device to test with Test Store keys.
  </Step>

  <Step title="Test on a real device">
    Use Apple's sandbox testing or Google Play's test tracks for real purchase flows.
  </Step>
</Steps>


# Troubleshooting
Source: https://docs.newly.app/subscriptions/troubleshooting

Common subscription issues and how to fix them

## "No subscription plans available"

This usually means one of:

* **Entitlement mismatch** — your app expects an entitlement that doesn't match what's in RevenueCat. Newly uses "pro" as the entitlement name. Check your RevenueCat dashboard.
* **Incomplete catalog** — products, offerings, or packages weren't created. Check your RevenueCat dashboard for a complete catalog.
* **Missing API keys** — your app doesn't have the right SDK keys configured.

<Tip>
  Ask the AI agent to run a diagnosis — it has a built-in tool that validates your `app.json` configuration against your RevenueCat dashboard and reports specific issues.
</Tip>

## "RevenueCat session expired"

RevenueCat OAuth tokens expire after approximately 1 hour. The system auto-refreshes them in most cases, but occasionally you may need to reconnect.

**Fix:** Re-run the RevenueCat connection flow. Ask the AI to "reconnect RevenueCat" or use the settings panel.

## Purchases work in dev but not production

<Warning>
  Getting production purchases to work is one of the hardest parts of launching a mobile app. Even experienced developers get stuck here. Be patient — this process involves multiple external systems (Apple, Google, RevenueCat) that all need to be correctly configured and fully propagated.
</Warning>

Production purchases failing while dev/test purchases work is **the most common subscription issue**. Work through every step below in order.

### Step 1: Accept the Paid Applications Agreement (Apple)

This is the **number one cause** of production purchase failures. Without this, nothing else will work.

1. Go to [App Store Connect Business](https://appstoreconnect.apple.com/business)
2. Under **Paid Apps**, look for a **"Review and Accept"** button or a yellow/red banner
3. **Accept the agreement** if prompted
4. **Complete all required forms**: tax information, bank account details, and contact information

<Warning>
  If any of these forms are incomplete, Apple will reject all in-app purchase operations — including RevenueCat's ability to validate your IAP keys. Your RevenueCat dashboard may show key validation errors until this is fully resolved.
</Warning>

### Step 2: Wait for Apple propagation

If your app was recently created in App Store Connect, Apple may need **up to 24–48 hours** to fully propagate your app's bundle ID and subscription configuration. During this time:

* IAP key validation in RevenueCat may fail
* Products may not appear in the SDK
* Receipt validation may return errors

There is no way to speed this up. If your app was created in the last 48 hours and everything else looks correct, wait and retry.

### Step 3: Verify your Apple credentials

Ensure the following are configured in your Newly dashboard:

| Credential            | What it does                                      | How to check                        |
| --------------------- | ------------------------------------------------- | ----------------------------------- |
| **ASC API Key** (.p8) | Creates and manages products in App Store Connect | Newly dashboard → Apple credentials |
| **IAP Key** (.p8)     | Lets RevenueCat validate purchase receipts        | Newly dashboard → Apple credentials |

These are typically auto-provisioned when you connect your Apple Developer account. If they show errors, try disconnecting and reconnecting your Apple credentials.

### Step 4: Check your RevenueCat configuration

Open your [RevenueCat dashboard](https://app.revenuecat.com) and verify:

* Your app has an **App Store** app with the correct bundle ID
* The IAP key status shows as **valid** (not "invalid" or "pending")
* Your offering is set as **Current**
* Products in the offering have **pricing configured**

### Step 5: Use RevenueCat's troubleshooting guide

RevenueCat has a detailed guide for diagnosing offering and product issues:

**[RevenueCat Offerings Troubleshooting Guide](https://www.revenuecat.com/docs/offerings/troubleshooting-offerings)**

This guide covers SDK-level debugging, verifying your product configuration, and common pitfalls. It requires some technical depth — take your time with it.

### Still stuck?

Production purchase issues can be genuinely difficult to resolve, especially if you are new to mobile app development. If you have worked through all the steps above and purchases still are not working:

* **Ask the AI agent** to run a diagnosis — it validates your full configuration and identifies specific mismatches
* **Use the in-app support widget** to reach out to support without leaving your project
* **Email us** at [support@newly.app](mailto:support@newly.app) with your project name and a description of the error
* **Need hands-on help?** Our [Consulting plan](https://newly.app/pricing?tab=plans) includes dedicated support where we handle complex setup like production purchases for you

<Info>
  Production purchases involve Apple/Google account setup, RevenueCat configuration, and app-level code all working together. A failure in any one of these layers can cause purchases to silently fail. Do not assume the problem is in your app code — it is almost always an account or configuration issue.
</Info>

## "Missing Metadata" in RevenueCat

You may see a **"Missing Metadata"** warning on your product in the RevenueCat dashboard:

<Frame>
  <img alt="RevenueCat dashboard showing Missing Metadata status on a subscription product" />
</Frame>

This means the subscription product was created in App Store Connect, but Apple still needs additional metadata before it can go live. Newly auto-creates the products, but some metadata must be completed manually in App Store Connect for now.

**Fix:** Go to [App Store Connect](https://appstoreconnect.apple.com) and complete the missing metadata:

1. Navigate to **My Apps** → your app → **Subscriptions**
2. Select your subscription group (usually "NSubscriptions")
3. For each product, check that the following are all set:
   * **Localization** — display name and description in at least one language (English)
   * **Pricing** — at least one price set for a territory
   * **Review screenshot** — an image for Apple's review team

Once all metadata is filled in, the product status in App Store Connect should change from "Missing Metadata" to **"Ready to Submit"**, and the warning in your RevenueCat dashboard should disappear.

For a step-by-step checklist, see [RevenueCat's offerings troubleshooting guide](https://www.revenuecat.com/docs/offerings/troubleshooting-offerings) — scroll down to the **App Store** section and verify each requirement. You can also refer to [Apple's in-app purchase status reference](https://developer.apple.com/help/app-store-connect/reference/in-app-purchases-and-subscriptions/in-app-purchase-statuses) for a full list of what Apple requires.

## Paywall shows "Premium Feature 1, 2, 3"

The AI agent should auto-generate realistic feature names based on your app's functionality. If you see generic placeholder text:

**Fix:** Ask the AI to "update the paywall features" or "make the paywall match my app's features". It will analyze your app and suggest relevant premium feature descriptions.

## Purchases not syncing across devices

This happens when your app doesn't have authentication. Without a user ID, RevenueCat can't link purchases across devices.

**Fix:** Add authentication to your app. Ask the AI to "set up auth" — once auth exists, the subscription system will automatically start syncing purchases via user ID.

See [Authentication & Subscriptions](/subscriptions/authentication) for more details.

## "Invalid API key" error in Expo Go

<Warning>
  RevenueCat purchases do not work in standard Expo Go. You need a custom dev build.
</Warning>

**Fix:** Run `npx expo prebuild` and build for your device. See [Testing Purchases](/subscriptions/testing) for details.

## Connection issues after setup

If the RevenueCat integration seems broken after initial setup:

1. Check if your OAuth session expired (re-run connection flow)
2. Verify products exist in your RevenueCat dashboard
3. Confirm API keys are present in your `app.json` (see [Technical Details](/subscriptions/technical-details))
4. Ask the AI to diagnose the issue — it can validate the full configuration