finanzen/.agents/skills/convex-create-component/references/packaged-components.md

Packaged Convex Components

Read this file when the user wants a reusable npm package or a component shared across multiple apps.

When to Choose This

• The user wants to publish the component
• The user wants a stable reusable package boundary
• The component will be shared across multiple apps or teams

Default Approach

• Prefer starting from npx create-convex@latest --component when possible
• Keep the official authoring docs as the source of truth for package layout and exports
• Validate the bundled package through an example app, not just the source files

Build Flow

When building a packaged component, make sure the bundled output exists before the example app tries to consume it.

Recommended order:

1. npx convex codegen --component-dir ./path/to/component
2. Run the package build command
3. Run npx convex dev --typecheck-components in the example app

Do not assume normal app codegen is enough for packaged component workflows.

Package Exports

If publishing to npm, make sure the package exposes the entry points apps need:

• package root for client helpers, types, or classes
• ./convex.config.js for installing the component
• ./_generated/component.js for the app-facing ComponentApi type
• ./test for testing helpers when applicable

Testing

• Use convex-test for component logic
• Register the component schema and modules with the test instance
• Test app-side wrapper code from an example app that installs the package
• Export a small helper from ./test if consumers need easy test registration

Checklist

• Packaging is actually required
• Build order avoids bundle and codegen races
• Package exports include install and typing entry points
• Example app exercises the packaged component
• Core behavior is covered by tests