1# Packaged Convex Components
2 
3Read this file when the user wants a reusable npm package or a component shared
4across multiple apps.
5 
6## When to Choose This
7 
8- The user wants to publish the component
9- The user wants a stable reusable package boundary
10- The component will be shared across multiple apps or teams
11 
12## Default Approach
13 
14- Prefer starting from `npx create-convex@latest --component` when possible
15- Keep the official authoring docs as the source of truth for package layout and
16  exports
17- Validate the bundled package through an example app, not just the source files
18 
19## Build Flow
20 
21When building a packaged component, make sure the bundled output exists before
22the example app tries to consume it.
23 
24Recommended order:
25 
261. `npx convex codegen --component-dir ./path/to/component`
272. Run the package build command
283. Run `npx convex dev --typecheck-components` in the example app
29 
30Do not assume normal app codegen is enough for packaged component workflows.
31 
32## Package Exports
33 
34If publishing to npm, make sure the package exposes the entry points apps need:
35 
36- package root for client helpers, types, or classes
37- `./convex.config.js` for installing the component
38- `./_generated/component.js` for the app-facing `ComponentApi` type
39- `./test` for testing helpers when applicable
40 
41## Testing
42 
43- Use `convex-test` for component logic
44- Register the component schema and modules with the test instance
45- Test app-side wrapper code from an example app that installs the package
46- Export a small helper from `./test` if consumers need easy test registration
47 
48## Checklist
49 
50- [ ] Packaging is actually required
51- [ ] Build order avoids bundle and codegen races
52- [ ] Package exports include install and typing entry points
53- [ ] Example app exercises the packaged component
54- [ ] Core behavior is covered by tests
55