How to document your app so someone else can take it over
What to write down before handing your app to a new developer or agency: accounts, setup, architecture, data, deployment, known issues and a handoff checklist.
Leer en español →
To hand an app to someone else, document six things: which accounts and services it runs on, how to run it locally, how the parts fit together, where the data lives, how to deploy and roll back, and what's known to be broken. A short, accurate document covering those beats a long one nobody updates, and it saves a new developer days of guesswork.
This guide explains what to write for each part, how to collect it if you didn't build the app yourself, where to keep it and how to check it actually works.
Why is documentation worth the effort?
Without it, the next person has to rediscover everything by reading code and clicking around dashboards. That's slow, and they'll miss things: a cron job nobody mentioned, an environment variable set only in production, a webhook pointing at an old URL. Each surprise costs time and sometimes an outage.
Documentation also protects you. If a freelancer disappears or an agency relationship ends, the knowledge of how your app works shouldn't leave with them.
What should the handoff document include?
1. Accounts and services
A table of every service the app depends on:
| Service | What it does for the app | Account owner | Who has access |
|---|---|---|---|
| GitHub | Source code | Company account | You, current developer |
| Vercel | Hosting the frontend | Company account | You |
| Supabase | Database, login, file storage | Company account | You, current developer |
| Stripe | Payments | Company account | You |
| Email provider | Transactional email | Company account | You |
| Domain registrar | The domain and DNS | Company account | You |
Never put passwords or keys in this document. Write where they live (for example, "in the hosting project's environment variables") and give access by inviting the new person to each service with their own account.
2. How to run it locally
The exact steps to go from a fresh clone to a working app on a laptop:
- Required tools and versions (for example, the Node.js version).
- How to install dependencies.
- Which environment variables are needed, by name only, with a sample file such as
.env.example. - How to start the app and which URL to open.
- How to get test data or a test account.
Have someone follow these steps on a clean machine. If they get stuck, the step is missing.
3. How the parts fit together
A one-page overview, in plain words, is enough: what the frontend is built with, what the backend does, which external APIs are called and why. A simple diagram helps, even a photo of one drawn on paper. Note anything unusual, such as "prices are calculated in a database function, not in the app".
4. The data
- Where the database is and how it's backed up.
- The main tables and what they represent.
- Who can read and write what (for example, Row Level Security policies in Supabase).
- How schema changes are made: through migration files, or by hand in a dashboard. See Supabase migrations with the CLI if they're still made by hand.
5. Deployment
- How code gets to production: automatic on merge, or a manual step.
- Where staging is, if there is one.
- How to roll back a bad release.
- Scheduled jobs, webhooks and background tasks, with what triggers them.
6. Known issues and decisions
A short, honest list: bugs you know about, workarounds in place, features half finished, and decisions that look odd but were deliberate. This is the section new developers find most useful, and the one most often missing.
How do you collect this if you didn't build the app?
If the app was made with an AI builder or by someone who's gone, you can still assemble most of it:
- Start with your bills. Every service you pay for is one the app probably uses.
- Look at the environment variables in your hosting dashboard. Their names (not values) tell you which services the app talks to.
- Read the package file (
package.jsonin JavaScript projects). It lists the libraries in use. - Ask the AI tool. In a code-aware tool, prompts like "list every external service this project calls and where" or "write a README explaining how to run this project" give a useful first draft. Check it against reality, as it can be wrong.
- Check webhooks and scheduled jobs in Stripe, Supabase and your hosting provider.
Where should the documentation live?
Keep it in the code repository, as a README.md at the root and a docs/ folder for longer pages. It stays next to the code, it's versioned with it and anyone with access to the code can find it. GitHub's guide to README files covers the basics.
How do you keep it up to date?
- Update the document in the same change that alters the setup: a new service, a new environment variable or a new deployment step.
- Review it whenever someone new joins. Their questions show what's missing.
- Keep it short. Long documents go stale fastest.
Quick answers
How long should handoff documentation be? Often a few pages is enough for a small app. Accurate beats long.
Should I share passwords in the handoff? No. Invite the new person to each service with their own login, and remove access for people who've left.
Can the AI tool write the documentation for me? It can write a good draft from the code. Someone still has to verify it, especially accounts, data and deployment.
What's the most commonly forgotten item? Things outside the code: webhooks, scheduled jobs, DNS records and environment variables set only in production.
Handing over to a new team?
If you're moving your app to a new developer, see our guide on handing off an AI agent project to a developer. We can also take over an app and document it as part of our maintenance and support. Start with the free App Health Check or get in touch.
