seed functions only for preview | Convex Community | Page 1

merry moat · 2026-02-25T08:24:11.084Z

how can i define a preview seed function that won't be accessible from production environment?

Hi @merry moat. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

You can’t define a function that “doesn’t exist” in production, but you can:

Make the seed function internal-only
Define it as an internalMutation (or internal action) so it’s never callable from clients, only from CLI / dashboard / other functions:
```
// convex/init.ts
import { internalMutation } from "./_generated/server";

const init = internalMutation({
  args: {},
  handler: async (ctx) => {
    // seed logic here
  },
});

export default init;
```
This keeps it out of your public API while still usable with --preview-run or npx convex run. [Internal funcs; internalMutation]
Only run it on preview deployments
Configure your CI/build so that --preview-run is only used when deploying previews, not when deploying to prod. For example with Vercel/Netlify:
```
npx convex deploy --cmd 'npm run build' --preview-run init
```
This init function will run only for preview deployments created via a Preview Deploy Key; it’s ignored for normal production deploys. [Deploy CLI; Vercel previews; Netlify previews]
Recommended workflow
The Convex team’s suggested pattern is exactly this: put your seed logic in convex/init.ts as an internal mutation/action, and wire --preview-run init into your preview deploy command. [Seeding summary; Workflow preference]

So: the same internal function is deployed to both environments, but only preview deployments ever execute it automatically, and no public client can call it.