convex-bundle-size
Debug and shrink a Convex deployment's bundle with @convex-dev/bundle-analyzer: find duplicate packages, "use node" code leaking into the Convex runtime, dev dependencies and test files in deployed code, then fix and measure before/after. TRIGGER on 'Total module size exceeded the unzipped maximum' (ModulesTooLarge), out-of-memory during push, slow "use node" cold starts, or 'why is my Convex bundle/push so big'. SKIP slow-query and spend questions.
How do I install this agent skill?
npx skills add https://github.com/convex/agent-skills --skill convex-bundle-sizeIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides instructions for optimizing and debugging the bundle size of Convex deployments using vendor-official tools. It executes standard development commands and interacts with project configuration files.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 2 issues
What does this agent skill do?
Debug Convex bundle size
Convex bundles each runtime's functions with esbuild. A deployment's code, including external packages, has to fit within Convex's code size limits; a push over them fails with ModulesTooLarge ("Total module size exceeded the unzipped maximum"). A large bundle can also fail a push or analysis with "ran out of memory". Large "use node" bundles slow cold starts. @convex-dev/bundle-analyzer reproduces the bundle locally and says what to cut. The limits are changing, so read the current ones from https://docs.convex.dev/functions/bundling#code-size-limits rather than assuming a number. Analyzer docs: https://docs.convex.dev/functions/bundling#debugging-bundle-size
Workflow
- Check prerequisites: dependencies installed and
convex/_generated/present. If it is missing, runnpx convex codegen. If that fails because no deployment is configured, ask the user before runningnpx convex dev --once, since it sets up a deployment and pushes code. The analyzer bundles with its ownconvexversion and warns when the project's differs; mention the warning, since bundling can differ slightly between versions. - Get the baseline:
npx -y @convex-dev/bundle-analyzer summaryfor total size, top insights, and the largest components, packages and modules. Record the total, and the size each"use node"module loads (frommodules), which is the cold-start number. Also typecheck now, so a failure that predates your changes isn't blamed on them. - Get the findings:
npx -y @convex-dev/bundle-analyzer insights --jsonprints{ "insights": [...] }, sorted bysavedBytes. Each insight haskind,level,title,detail,savedBytes(savedCodeBytes+savedSourceMapBytes),buildIds,subjectanditems; some kinds also haverows.savedBytesis an estimate. - Look past the insights. They only fire above size thresholds and don't detect unused imports, so the largest win can have no insight. Read the largest-packages table in
summary, and for each large package check that a deployed function actually calls it. Drill in with:packages <name>: which entry points import a package, with import chains.files <path-fragment>(e.g.zod@3.25.76/orconvex/lib/): which modules a file is bundled into and what imports it.modules [module]: how much code loads to run one function module, which drives cold start and memory.components: size per component per runtime, to pick which component to look at first. These take--jsonand--limit <n>.exploreis an interactive terminal treemap; don't run it as an agent.
- Fix by insight
kind:duplicate-package: align the versions in package.json, or dedupe with the project's package manager.alternate-package-implementations: the ESM and CJS builds of one package are both bundled; standardize imports on one entry point.use-node-file-in-convex-runtime: a non-node file imports a"use node"file. Each item'sfixessays whether to add"use node"to the importer (add-use-node, which only works if the importer defines no queries or mutations, since"use node"files can only define actions) or move the shared code into a file without"use node"(move).package-in-both-runtimes: remove its use from the runtime that doesn't need it.external-package-candidate: only"use node"code uses it (the analyzer names the dependency from package.json that brings it in), so adding it tonode.externalPackagesin convex.json shrinks the upload. The whole installed package then counts toward the code size limit, so it can increase the total;savedBytesis 0 for this kind on purpose. Use it when upload size or bundling is the problem, not the total.dev-dependency-bundled: either a runtime dependency is listed under devDependencies (move it), or test or script code reaches a deployed module (cut that import;items[].importedBynames the importing files).test-file-bundled: a test file is bundled; stop importing it or move or rename it so it isn't a function module.package-in-many-components: each component bundles its own copy; expected for components, so only act if one copy is large.
- Present a plan ranked by expected savings before editing anything, and get the user's go-ahead.
- Apply one fix at a time. After each, re-run
summaryand report the total (and the cold-start size, if that was the complaint) before and after. When done, typecheck and runnpx convex dev --onceto confirm the push succeeds.
Rules
- Measure with the analyzer before changing anything, and report before and after sizes for every fix.
- Present the plan before editing; package.json, convex.json and
"use node"changes affect every function in the bundle. - Don't count
external-package-candidateas a saving: externals shrink the upload but the whole installed package counts toward the code size limit. - For Node cold starts, the code a module loads (the
modulessize) matters more than gzipped size. Move code out of"use node"when it can run in the Convex runtime. - The usual culprits are WASM or native binary dependencies and SDKs that don't tree-shake (e.g. aws-sdk, snowflake-sdk). If one dependency can't be shrunk, move it behind a sandbox component or an external service.
- Keep
convexup to date: newer versions can bundle more efficiently. Projects on a version before 1.31.5 get a large saving from upgrading alone, since bundled source maps no longer include source code. The analyzer always bundles with its ownconvex, so it can't show what an upgrade saves; compare pushes instead. - Slow queries and spend are not bundle size problems; this skill does not cover them.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/convex/agent-skills/convex-bundle-size">View convex-bundle-size on skillZs</a>