---
name: shipholm-migrate-from-lovable
description: "Migrate an app from Lovable to Shipholm – frontend-only apps in one step, apps on Supabase or Lovable Cloud via SQLite or Postgres (inventory, export, replace the backend, files and sign-in, cut over). Use when an app was built in Lovable or uses @supabase/supabase-js."
---

# Migrate from Lovable (and Supabase)
Move a Lovable app – with or without Supabase or Lovable Cloud behind it – to Shipholm, step by step.

## 0. Is there a backend at all?
A Lovable project is a Vite + React app in a GitHub repository (connect it in Lovable's GitHub
settings if it is not). Look for `@supabase/supabase-js` in `package.json` and a `supabase/` folder:
- **None** – the app is frontend-only. Follow skill `shipholm-static-site`:
  `create_app(app=..., source_repo="https://github.com/<owner>/<repo>")` builds the Vite app as is.
  Then move the domain (step 6). That is the whole migration.
- **Supabase or Lovable Cloud** – the steps below: inventory, choose where data lives, export,
  replace the backend, files and sign-in, cut over.

Lovable keeps pushing to the repository's default branch while the project is open there. Work on
a branch of your own until the cut-over, and decide with your human whether Lovable stays the
editor afterwards (every push still deploys) or is retired.

Check which branch is the real one before you build anything. `create_app` builds `main` unless
you pass a branch, but the newest work may be on another branch (the repository's default branch,
a branch another agent works on). `git log --oneline main..<other>` and the other way round show
what each has. Several writers are common – Lovable, another agent, a human – so read
`git log main` for commits that are not yours before you merge into it.

Frontend-only apps: after the first deploy, check that the files in `public/` are served as what
they are: `curl -sI https://<app>.shipholm.dev/favicon.png` must say `image/png`. An SPA fallback
answers a missing file with `index.html` and status 200. The page looks fine, but card images and
icons are broken. That usually means the build is not the one you think: the wrong branch, or no
Dockerfile, so Railpack built it.

## 1. Inventory – what does the app really use?
Read the repository before deciding anything:
- `supabase/migrations/*.sql` – tables (`create table`), functions, triggers, enums, storage buckets
  (`storage.buckets`), RLS policies (`create policy`, count them), realtime (`supabase_realtime`).
- `supabase/functions/*` – edge functions (each becomes a route on your own server).
- The frontend: `grep -rE "supabase\.(from|rpc|storage|functions)|auth\." src` – which tables are
  read and written, which sign-in methods (`signInWithPassword`, `signInWithOAuth`, magic links).
- Count the rows (Supabase SQL editor, or the Lovable connector's `query_database`):
  `select count(*) from <table>` for every table, and `auth.users`, `storage.objects`.
Write the result down as a table: what is used, how much data, what can go. Often features that
were generated "just in case" (comments, profiles, notifications) have no data at all – dropping
them is the biggest simplification.

## 2. Choose where the data lives
- **SQLite on a disk** (`storage=true`, skill `shipholm-sqlite-app`) – the default for small apps: no
  database server, it sleeps with the app. You rewrite the schema in SQLite (uuid → TEXT,
  timestamptz → TEXT ISO 8601, enums → TEXT with CHECK, jsonb → TEXT JSON), which is quick
  when the backend is rewritten anyway.
- **Postgres** (`database=true`, skill `shipholm-postgres-app`) – when you want to keep the SQL nearly as
  is, need several replicas or many concurrent writers. Drop the Supabase-specific parts
  (`auth.*`, `storage.*`, RLS policies that call `auth.uid()`, the realtime publication).
Keep the existing ids (uuids) so links like `/app/<id>` keep working.

## 3. Export the data
- Public tables: the Supabase REST API with the project's public key, one file per table:
  `curl "$SUPABASE_URL/rest/v1/<table>?select=*" -H "apikey: $KEY" -H "Authorization: Bearer $KEY" > <table>.json`
  (rows hidden by RLS need the service key or SQL access).
- Everything, as SQL: `pg_dump --schema=public --data-only --no-owner` with the database
  connection string, when you have it (Supabase dashboard → Database). Lovable Cloud projects
  without dashboard access: the Lovable connector's `query_database` runs SELECTs.
- Leave out what you do not need, and personal data you do not need: emails, user ids. Keep
  export files local and temporary; never commit them.
- Shape the export as the import expects it: one JSON object with an array of rows per table
  (`{"categories": [...], "apps": [...], ...}`). Replace a `user_id` you drop with what the
  app shows instead (e.g. `creator_name`).

## 4. Replace the backend
- Add a small server to the repository (Node with `node:sqlite`, or anything that listens on
  `$PORT`): it serves the built frontend, a JSON API and the former edge functions as routes.
- Replace each `supabase.from(...)` call with a call to your API. Keep the shapes the components
  expect: rewrite the data hooks (e.g. `src/hooks/*`), and most pages stay untouched.
- RLS policies become checks in the server: who may read or change what. Realtime becomes
  polling or server-sent events.
- Add an import endpoint (protected by a secret admin key, `set_env(..., secret=true)`) that takes
  the export and upserts it in one transaction – safe to run twice. That is how data reaches
  the app's disk or database; it never goes through git.
- Remove `@supabase/supabase-js`, the generated client and the committed `.env` with Supabase keys
  (`VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`). Also remove Lovable's leftovers:
  `lovable-tagger` in `vite.config.ts` and `package.json`, `.lovable/`, `bun.lockb` when you use
  npm. Put `.env` in `.gitignore` and commit a `.env.example`.
- Serve `/healthz` from the server (it answers 200 once the database opens), and `llms.txt` and
  `sitemap.xml` from the data rather than as static files that go stale.
- A canonical address: when `SITE_URL` is `https://www.<domain>`, redirect the bare domain to it
  in the server (301, path and query kept), and skip `/healthz`.
- Start even without the disk: if `DATA_DIR` is not writable, fall back to a temporary directory
  and log a warning. A missing disk then shows in the logs instead of a pod that never gets ready.

## 5. Files and sign-in
- Storage buckets: the import downloads every file it finds (image URLs in rows and settings)
  into `DATA_DIR/images` and rewrites the URLs to the app's own `/images/...`.
- Sign-in, if the app keeps it: Supabase stores bcrypt hashes in `auth.users.encrypted_password`,
  so users can keep their passwords if you verify bcrypt in your server; or switch to magic links
  by email. Often the better move is no accounts at all – e.g. a form that takes an email and a
  confirmation link.
- Email (confirmations, notifications) needs a mail service; Supabase sent its own auth mails.
  Ship with a stub that only logs the mail until there is a provider (`MAIL_API_URL`,
  `MAIL_API_KEY`, `MAIL_FROM`). The rest of the app does not have to wait for it.
- Without accounts, protect what anyone can post with rate limits per IP, e.g. submissions and
  upvotes. Gate the admin pages and the app's own MCP endpoint, if it has one, with the admin key.

## 6. Cut over
1. Set up the app before the pull request is built. A preview copies the parent app's
   settings when it is built: `storage=true` (or `database=true`), `previews=true` and the
   secrets (`set_env(..., app=..., secret=true)` for the admin key). Keep the old health path
   until the new server runs in production.
2. Work on a branch with `previews=true`: the pull request gets `<app>-pr<N>.shipholm.dev`. If the
   repository is synced with Lovable, do not push to the branch Lovable deploys until the cut-over.
3. Import into the preview and check every page. The import's answer lists every file it could
   not download. A download that returned HTML means the source app has the problem above, not
   the import. Fix it there and run the import again; it fetches only the files it is missing.
4. Add both domains (`add_domain` for `<domain>` and `www.<domain>`) and create their TXT records
   now. Verification needs only the TXT record, so the old site keeps running.
5. Merge, then set `health_path="/healthz"`. Wait until `https://<app>.shipholm.dev/healthz`
   answers JSON from the new server (the old SPA answers HTML). Import into production and
   compare the row counts with the source. Then `verify_domain` both domains.
6. Switch DNS last. Lovable serves a custom domain from an A record (185.158.133.1 when we moved one; proxied in
   Cloudflare). Delete it and add one A record per address that `add_domain` returned for the
   apex, plus a CNAME `www` → `<app>.shipholm.dev`. Make both DNS only, not proxied: the
   certificate is issued once traffic arrives, usually within two minutes.
7. Check both hosts over HTTPS (`/`, `/healthz`, a few pages, the API), and that the apex
   redirects to www.
8. Remove the domain from the Lovable project. Keep the Supabase project read-only for a while
   before you delete it.
