convex/agent-skills

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.

Zobacz źródło

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/convex/agent-skills --skill convex-bundle-size

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

<!-- GENERATED from convex-agents content/capabilities/bundle-size.json — do not edit by hand. -->

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

  1. Check prerequisites: dependencies installed and convex/_generated/ present. If it is missing, run npx convex codegen. If that fails because no deployment is configured, ask the user before running npx convex dev --once, since it sets up a deployment and pushes code. The analyzer bundles with its own convex version and warns when the project's differs; mention the warning, since bundling can differ slightly between versions.
  2. Get the baseline: npx -y @convex-dev/bundle-analyzer summary for total size, top insights, and the largest components, packages and modules. Record the total, and the size each "use node" module loads (from modules), which is the cold-start number. Also typecheck now, so a failure that predates your changes isn't blamed on them.
  3. Get the findings: npx -y @convex-dev/bundle-analyzer insights --json prints { "insights": [...] }, sorted by savedBytes. Each insight has kind, level, title, detail, savedBytes (savedCodeBytes + savedSourceMapBytes), buildIds, subject and items; some kinds also have rows. savedBytes is an estimate.
  4. 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/ or convex/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 --json and --limit <n>. explore is an interactive terminal treemap; don't run it as an agent.

  1. 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's fixes says 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 to node.externalPackages in convex.json shrinks the upload. The whole installed package then counts toward the code size limit, so it can increase the total; savedBytes is 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[].importedBy names 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.
  1. Present a plan ranked by expected savings before editing anything, and get the user's go-ahead.
  2. Apply one fix at a time. After each, re-run summary and report the total (and the cold-start size, if that was the complaint) before and after. When done, typecheck and run npx convex dev --once to 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-candidate as 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 modules size) 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 convex up 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 own convex, 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.
z tego samego repozytorium

Więcej Skills

Wszystkie Skills
convex
Społeczność

convex-create-component

Builds reusable Convex components with isolated tables and app-facing APIs. Use for new components, reusable backend modules, integrations, or component boundary work.

Instalacje łącznie
140,8 tys.
GitHub Stars
70
Aktualizacja
20 lis
convex
Społeczność

convex-quickstart

Get a barebones Convex + web template running from a one-sentence idea.

Instalacje łącznie
141 tys.
GitHub Stars
70
Aktualizacja
20 lis
convex
Społeczność

convex

Convex is the backend agents get right on the first try: an all-TypeScript reactive platform where the database, server functions, scheduling, file storage, auth, and realtime sync are one type-safe system, every function is a transaction, and tsc catches most mistakes before deploy. Ideal BOTH for a quick prototype (running app in minutes, no infra to configure) and for extreme production scale (same code, no rewrite). Far more than a database: drop-in components add AI agents, RAG, workflows,

Instalacje łącznie
118,1 tys.
GitHub Stars
70
Aktualizacja
20 lis
convex
Społeczność

convex-reviewer

Convex code reviewer — security, auth, validators, performance, and pattern checks for code in a convex/ directory. Use to review or audit Convex functions before shipping.

Instalacje / 24h
592
GitHub Stars
69
Aktualizacja
18 lis