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.
- An Android phone with Expo Go for SDK 54, or a compatible simulator/emulator. The current iPhone App Store version cannot open SDK 54 projects.
Step 1: Clone the repo
git clone https://github.com/you/your-app.git
cd your-appStep 2: Install dependencies
npm installTakes 30 seconds to 2 minutes; Expo projects pull in a fair amount of React Native core.
Step 3: Environment variables
There is no client .env file to set up for Appsanic's generated public connector values. Publishable values (the Supabase anon key, Mapbox public token, and similar) are inlined in a shared client configuration module because the provider designed them to be visible. Secret keys are never bundled and are not served to the app from connector storage. A secret-backed feature needs a separately deployed backend whose runtime credential you provision directly. See Environment Variables.
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 startMetro bundler runs at http://localhost:8081, with a QR code in the terminal.
- Android device: scan the QR with Expo Go for SDK 54.
- iPhone: the current App Store Expo Go cannot run this SDK 54 project. For native testing, configure your own development build from the exported project as described below.
- 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 configNote: 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. Appsanic generates complete review-first SQL files or dashboard instructions for schema changes; it does not automatically execute arbitrary SQL against your 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, ask the agent in Appsanic to prepare the SQL and Row Level Security policies, review the generated file, then apply it in Supabase's SQL Editor or with the Supabase CLI. If you author migrations outside Appsanic, keep them with your own migration workflow because Appsanic cannot infer that external history.
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 development build, which you run yourself from your exported project against your own EAS account - it is not something Appsanic triggers for you:
eas build --profile development --platform iosInstall the resulting Dev Client and use it instead of Expo Go.
Lint and type-check
npm run lint
npx tsc --noEmitCreate a production build
eas build --platform ios
eas build --platform androidRequires 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 changedMetro 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-timezoneOpen 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:
- Shake the device (or Cmd-D in Simulator / Cmd-M in Emulator) for the dev menu.
- Debug opens a debugger in Chrome or VS Code.
- 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.jsonso CI installs the same versions.
Next
Read Editing Exported Code for patterns when you're taking more control of the codebase.