Local Development

Who is this page for? This page is for people who write code. If you've never written code, you don't need this. Appsanic does everything you'll need without ever opening a terminal. Skip to App Configuration or any other doc in the sidebar.

Once you've exported your project to GitHub, you can clone it and work on it locally. Useful when you want to:

• Edit code in VS Code, Cursor, or JetBrains tools.
• Run the app without Appsanic's preview server.
• Connect with your team's git workflow, CI, code review.
• Add tests, custom tooling, or build scripts not covered by the agent.

You don't have to do any of this. Appsanic alone is a complete environment. This is for when you're ready to take more control.

Prerequisites

• macOS, Windows, or Linux (Intel or Apple Silicon).
• Node.js: version 20 LTS or later. nodejs.org.
• Git: any recent version.
• Expo CLI: installed as a dev dependency by the project.
• A phone with Expo Go installed, or an iOS Simulator / Android emulator.

Step 1: Clone the repo

git clone https://github.com/you/your-app.git
cd your-app

Step 2: Install dependencies

npm install

Takes 30 seconds to 2 minutes; Expo projects pull in a fair amount of React Native core.

Step 3: Environment variables

There is no .env file to set up. A generated project does not use one. Publishable keys (the Supabase anon key, Mapbox public token, and similar) are inlined directly in the source, because that key class is designed to live in client code. Secret keys (OpenAI, Anthropic, Twilio, and so on) are never bundled. They stay encrypted in Appsanic, and the app reaches them through a small server-side relay, which Appsanic can deploy as a Supabase Edge Function when Supabase is connected. See Environment Variables for the full picture of which keys are safe to embed.

So once you have cloned and installed, you can move straight to the dev server. If you do introduce your own secrets later (a server-side build script, your own CI), keep them out of the repo and rotate anything you accidentally commit at the issuing service.

Step 4: Start the dev server

npx expo start

Metro bundler runs at http://localhost:8081, with a QR code in the terminal.

• Real device: scan the QR with Expo Go.
• iOS Simulator: press i.
• Android Emulator: press a.

Step 5: Edit code

The structure mirrors what you saw in Appsanic:

App.tsx         # Entry point: NavigationContainer + navigator (React Navigation v7)
screens/        # One screen per file (e.g. HomeScreen.tsx)
components/      # Shared React Native components
stores/         # Zustand stores, one per concern
theme.ts        # Design tokens: colours, spacing, type, radii
types.ts        # Shared TypeScript types
app.json        # Expo config
package.json    # dependencies and scripts
tsconfig.json   # TypeScript config

Note: there is no Expo Router (navigation is wired by hand in App.tsx), no NativeWind or Tailwind (styling is StyleSheet.create reading from theme.ts), and no local supabase/migrations folder (schema changes go through Appsanic's connector tools, not a local migration runner). For the full layout and conventions, see Editing Exported Code.

Make changes; Metro hot-reloads in roughly a second.

Editor setup

VS Code or Cursor

The project includes .vscode/extensions.json with recommended extensions:

• ESLint: uses the project's lint rules.
• Prettier: formats on save.
• Error Lens: inline error display.
• TypeScript: built in.

For Cursor specifically: if a .cursor/rules/ directory is present, Cursor uses those rules to keep its AI assistance aligned with Appsanic's conventions. (Older projects use .cursorrules; both work.)

JetBrains WebStorm

Opens cleanly as a folder. TypeScript, linting, formatting, and debugging all work out of the box. Configure the run config to npx expo start.

Working with the database

An exported project has no local supabase/migrations folder. Schema changes are applied through Appsanic's connector tools against your hosted Supabase project, not a local migration runner. So when you develop locally, you develop against that same hosted project. The Supabase client in the code is already configured with the publishable (anon) key, so there is nothing to point at by hand.

If you want schema changes, the cleanest path is to ask the agent in Appsanic (it applies them and keeps Row Level Security in step), then git pull any code changes back. If you prefer to manage schema yourself with the Supabase CLI, you can connect the CLI to your hosted project and run your own migrations - just keep in mind that Appsanic will not know about migrations you author outside it.

Common local-dev tasks

Install a new dependency

npm install <package>

For libraries with native code (anything that adds iOS/Android Swift/Kotlin/Obj-C), Expo Go can't run it. You'll need a Dev Client build:

eas build --profile development --platform ios

Install the resulting Dev Client and use it instead of Expo Go.

Lint and type-check

npm run lint
npx tsc --noEmit

Create a production build

eas build --platform ios
eas build --platform android

Requires eas login first.

Pulling agent changes back locally

If the agent has pushed updates in Appsanic since your last pull:

git pull
npm install   # in case dependencies changed

Metro picks up the new files on next reload.

Pushing local changes back

Standard PR flow:

git checkout -b fix/streak-timezone
# ...edit...
git commit -m "Fix streak rollover on DST transitions"
git push -u origin fix/streak-timezone

Open a PR on GitHub. The reviewer sees a clean diff against main.

Mixing Appsanic and local edits

Both work. One rule: don't have Appsanic and your editor editing the same file at the same moment. The agent reads from git; if you have uncommitted local changes, the agent might overwrite them.

Recommendation:

• Small/quick: edit in Appsanic.
• Larger engineering work: pull, edit locally, commit, push, resume in Appsanic.
• Never: edit the same file in both places within the same hour.

Debugging

For runtime issues:

1. Shake the device (or Cmd-D in Simulator / Cmd-M in Emulator) for the dev menu.
2. Debug opens a debugger in Chrome or VS Code.
3. React Native Debugger is great for state inspection.

For build errors: read the Metro console output. It usually points to the exact line. If it's an import path, check case (macOS is case-insensitive, Linux and many CI systems aren't).

What to watch

• Node version mismatch. Expo requires Node 20+. Older versions produce cryptic errors.
• Expo SDK version drift. Appsanic's exports pin a specific SDK; if you upgrade by hand, make sure your EAS build profile matches.
• Lock files. When you install a new dependency, commit package-lock.json so CI installs the same versions.

Next

Read Editing Exported Code for patterns when you're taking more control of the codebase.