Migrate from Convex

A Convex app already looks like a helipod app. Same query and mutation handlers, the same defineSchema/defineTable schema, the same client hooks. Porting one is mostly a matter of rewriting imports, not rewriting your logic.

helipod migrate automates the mechanical part: import specifiers, package.json, _generated/. For everything it can't do for you, it gives you a concrete, file-and-line list.

Canonical imports in helipod are @helipod/*, never convex/* (see What is helipod?). helipod migrate also renames your app's function directory from convex/ to helipod's own default, helipod/, as part of the same run. Migrating moves your app onto the native import surface; it does not make helipod execute convex/* imports unchanged. There's no compatibility shim to fall back on. The codemod is the whole migration.

This page covers two independent things under one command: helipod migrate rewrites a Convex project's code, and helipod migrate export/import moves an app's data between storage topologies. Most projects only need the first.

What stays the same

Nothing about your function bodies needs to change:

• query/mutation/action still come from ./_generated/server. Your function bodies don't move.
• schema.ts keeps its shape (it just relocates from convex/ to helipod/ along with the rest of the directory, see the rename step below). defineSchema, defineTable, and indexes work the same way; only the import specifier moves.
• useQuery/useMutation keep the same signatures, imported from @helipod/client/react instead of convex/react.

Migrating a project's code

Before you run it

The command detects a Convex project by either signal being present at the project root:

• convex/schema.ts exists, or
• package.json has a convex dependency.

It then refuses to touch a dirty git working tree:

$ helipod migrate
refusing to migrate: /path/to/app has uncommitted changes (commit/stash first, or pass --force)

Commit or stash first, or pass --force to proceed anyway.

warning: /path/to/app is not a git repo, changes will be made in place with no easy revert

The dirty check runs against the parent of --dir (the project root, one level above your Convex app directory), the same directory package.json and helipod.config.ts live in.

Running it

helipod migrate --from convex --dir convex

--dry-run is the safe way to preview a migration: it still writes the full report, but skips every file edit, every scaffold, and _generated/ regeneration entirely. Your convex/ tree is left byte-for-byte as it was.

$ helipod migrate --dry-run --force
[dry-run] 3 files would change, 1 scaffolded. See MIGRATION-REPORT.md

A real run reports what it actually did, and how many items still need you:

$ helipod migrate --force
migrated 3 files. 2 item(s) need manual attention, see MIGRATION-REPORT.md

What it actually does, in order

imports migrated, but codegen failed: <error>
See MIGRATION-REPORT.md; fix the flagged items, then run `helipod codegen`.

The import codemod

The rewrite is symbol-aware, not a blind string replace. It operates on the quoted module specifier, so import, export … from, require(), and dynamic import() are all handled, and it inspects which named symbols a convex/server import pulls in before deciding how (or whether) to rewrite it.

Three specifiers are unambiguous and always rewritten wherever they appear, quoted, in the file:

"convex/server" is different. Convex overloads that one module for schema builders, HTTP routing, and crons, which map to three different places in helipod:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({ notes: defineTable({ body: v.string() }) });

import { defineSchema, defineTable } from "@helipod/values";
import { v } from "@helipod/values";

export default defineSchema({ notes: defineTable({ body: v.string() }) });

./_generated/server imports (query, mutation, action, httpAction) are never touched. A Convex app already imports those from the same relative path helipod uses.

A mixed convex/server import, say import { defineSchema, cronJobs } from "convex/server", is never guessed at. It's left exactly as written and reported action-needed with a fix naming each symbol's real home. Any remaining bare "convex/server" occurrence the codemod's two passes didn't match (a default import, an export * from, a require()) is also caught and flagged, so nothing silently slips through as unsupported-by-omission.

The divergence scan

Independent of the import rewrite, every walked file is also scanned line by line for Convex runtime patterns that helipod's engine doesn't accept, even after the import moves. Every finding names the exact file and line.

Action-needed. A real helipod equivalent exists, but you adapt the call site by hand:

Unsupported. No automatic path; you decide how, or whether, to proceed:

.withIndex/ctx.db.patch/.paginate/ctx.auth are matched anywhere they appear as a substring on a line, so, for example, a comment mentioning .paginate( is flagged too. The scanner is line-based, not AST-based, so it's intentionally over-inclusive rather than risking a missed real call.

Reading the report

MIGRATION-REPORT.md groups every finding by severity, with a one-line count summary up top. A section is omitted entirely if it has no entries:

# Helipod migration report

5 auto-fixed, 3 action-needed, 1 unsupported.

## Auto-fixed (5)

- `convex/`: renamed to helipod/. **Fix:** Your backend functions now live in helipod/. Imports inside that folder are relative and did not change.
- `helipod/schema.ts:1`: import "convex/server" (schema). **Fix:** rewritten to "@helipod/values"
- `helipod/schema.ts:2`: import "convex/values". **Fix:** rewritten to "@helipod/values"
- `helipod/messages.ts:1`: import "convex/react". **Fix:** rewritten to "@helipod/client/react"
- `helipod/http.ts:1`: import "convex/server" (http). **Fix:** rewritten to "./_generated/server"

## Action needed (3)

- `helipod/messages.ts:14`: .withIndex(...) query. **Fix:** Helipod has no .withIndex, use ctx.db.query(table, "index").eq(f, v).gte(f, v).order("asc"|"desc").collect()
- `helipod/messages.ts:22`: ctx.db.patch(...). **Fix:** Helipod has no patch, read the doc, spread-merge, ctx.db.replace(id, { ...doc, ...changes })
- `helipod/crons.ts:1`: Convex crons (cronJobs). **Fix:** Compose defineScheduler() in helipod.config.ts and use cronJobs() from "@helipod/scheduler"

## Unsupported (1)

- `helipod/search.ts:9`: vector/search index. **Fix:** search/vector is not yet supported in Helipod (see roadmap)

Every finding, including the auto-fixed ones, is listed for visibility, not just the ones that need work. It's a full diff of what the tool touched, in one file, without needing git diff.

The scheduler scaffold doesn't wire your crons for you

import { defineConfig } from "@helipod/component";
import { defineScheduler } from "@helipod/scheduler";

// Convex crons map to Helipod's scheduler component. Move your cron definitions into
// a convex/crons.ts using cronJobs() from "@helipod/scheduler".
export default defineConfig({ components: [defineScheduler()] });

Two things to do by hand from there, per Scheduling:

import { cronJobs } from "./_generated/server";

const crons = cronJobs();
crons.interval("cleanup", { minutes: 5 }, internal.maintenance.purge, {});

export default crons;

import { defineConfig } from "@helipod/component";
import { defineScheduler } from "@helipod/scheduler";
import crons from "./helipod/crons";

export default defineConfig({ components: [defineScheduler({ crons })] });

The report's action-needed entry for crons points you at exactly this.

Going deeper

interface MigrationSource {
  id: string;
  detect(projectRoot: string): Promise<boolean>;
  analyze(projectRoot: string, appDir: string): Promise<MigrationPlan>;
}
interface MigrationPlan {
  edits: FileEdit[];       // existing files to overwrite
  scaffold: FileWrite[];   // new files to create (never overwrites an existing one)
  report: ReportEntry[];   // { severity: "auto-fixed" | "action-needed" | "unsupported", file, line?, what, fix }
}

const SOURCES: Record<string, MigrationSource> = { convex: convexSource };

$ helipod migrate --from supabase
unknown migration source "supabase" (available: convex)

Moving data between deployments

helipod migrate export and helipod migrate import move an app's actual rows between two running deployments. Most commonly this means moving between a portable SQLite/Postgres/container deployment and a Cloudflare DO-native one, since those two store data in physically different topologies and data never teleports between them on its own.

Both are HTTP clients, modeled on helipod deploy, that call a running deployment's bearer-gated admin endpoints (GET /_admin/export, POST /_admin/import), authenticated with the same HELIPOD_ADMIN_KEY the dashboard and helipod deploy --allow-deploy use. Both the container serve path and the Cloudflare DO host expose the same /_admin/* handler, so one client works in either direction. A stopped plain-SQLite file has no HTTP endpoint of its own: point a throwaway helipod serve/helipod dev at its data directory first, export from that, then tear it down.

helipod migrate export --url <source-url> --out dump.json
helipod migrate import --url <target-url> --in dump.json

HELIPOD_ADMIN_KEY (env or --admin-key) is required for both verbs. Missing it fails immediately, before any network call:

$ helipod migrate export --url http://localhost:3210 --out dump.json
✗ HELIPOD_ADMIN_KEY is required (or pass --admin-key)

A wrong key against a real deployment gets a clean 401, not a stack trace:

$ helipod migrate export --url http://localhost:3210 --out dump.json --admin-key wrong
✗ unauthorized, check HELIPOD_ADMIN_KEY / --admin-key

Export

$ HELIPOD_ADMIN_KEY=… helipod migrate export --url https://source.example.com --out dump.json
✓ exported 5 documents, 2 index rows → dump.json

The dump is a self-describing JSON file:

{
  "format": "helipod-migration-dump",
  "documents": [ /* every document across every table, with its real _id and _creationTime */ ],
  "indexUpdates": [ /* … */ ],
  "tableNumbers": { "messages": 3, "users": 4 }
}

Import

$ HELIPOD_ADMIN_KEY=… helipod migrate import --url https://target.example.com --in dump.json
✓ imported 5 documents, 2 index rows

$ helipod migrate import --url https://target.example.com --in dump.json --admin-key …
✗ import failed: wrong table number for "messages" (dump has 12348, target has 3)

A rejected import never applies partially. The target is exactly as it was before the call. Once a dump imports cleanly, the target is immediately live: new mutations commit on top of the imported rows without a timestamp collision, and every row, including _id and _creationTime, reads back byte-identical to the source.

After migrating

Compatibility at a glance

One table for "will my app port?". Every "not available" row is exactly what the divergence scan flags at the call site, so nothing here surprises you at runtime.

Honest compatibility notes

Near-free, by design, not a coincidence. helipod's runtime already executes Convex-shaped query/mutation/action functions natively, so migrating is overwhelmingly an import-specifier rewrite plus _generated/ regeneration, not a rewrite of your handlers, your schema shape, or your client code.

The divergences that do exist are real, not cosmetic, and the scanner is built specifically to catch every one of them at the call site rather than let them surface later as a runtime bug:

• No ctx.db.patch. helipod's writer is insert/replace/delete only. A Convex patch call becomes a read, spread-merge, and replace. See Mutations.
• No .withIndex(...). helipod's query builder is ctx.db.query(table, index) with chained .eq/.gt/.gte/.lt/.lte/.order/.where. See Queries.
• A mutation's promise resolves at commit, not at gate-time. If your client code relied on a Convex-specific gate-time resolution timing for optimistic-update sequencing, revisit it against Optimistic updates's documented promise-timing migration note.
• No full-text or vector search. .searchIndex(...)/.vectorIndex(...) have no helipod equivalent. The scan flags every occurrence as unsupported rather than silently dropping it.
• Crons need an explicit component. cronJobs() only takes effect once composed into helipod.config.ts via defineScheduler({ crons }). Convex's implicit registration doesn't carry over.
• ctx.auth is a string token, not a JWT-claims object, resolved via a context provider (e.g. @helipod/auth) rather than baked into the runtime.
• Convex Components and Convex Auth don't map 1:1. Recompose the equivalent helipod component(s): @helipod/auth, @helipod/scheduler, @helipod/workflow, @helipod/triggers, @helipod/notifications, via helipod.config.ts.

@helipod/* is the canonical surface, permanently. This isn't a temporary migration artifact. helipod's own default function directory is helipod/, not convex/; convex/ was never the target, only where a Convex app starts from, and helipod migrate renames it as part of the same run. There's no alias path back to convex/* imports to maintain: once migrated, you're simply writing a native helipod app.

Related

• What is helipod?: why the canonical surface is @helipod/*, not convex/*.
• CLI reference: the terse flag reference for every helipod subcommand, including migrate/migrate export/migrate import.
• Testing: @helipod/test vs. convex-test.
• Scheduling: the full cronJobs()/defineScheduler() surface a migrated crons.ts needs.
• Cloudflare: why migrate export/import exists, to move data between the portable and DO-native storage topologies.
• Queries and Mutations: the real ctx.db surface a migrated app's .withIndex/ctx.db.patch call sites need to target.