In this guide
Choose packages for the runtime your action uses, then test the built action. A successful install is only the first check: the library’s behavior and resource use must fit your workload.
Project dependencies
Project-based actions declare dependencies in files alongside the handler:
| Runtime | Dependency manifest | Lockfile |
|---|---|---|
| JavaScript | package.json |
package-lock.json |
| Python | requirements.txt |
requirements.lock |
The project’s action.json selects the runtime and entrypoint. Keep the dependency manifest and lockfile together when updating the project. A build can reject a missing or stale lockfile.
Import or require the installed library in the handler using its normal package name. An import is not a substitute for declaring the project’s dependencies.
Pinning
JavaScript project builds check that package-lock.json matches the manifest and includes registry integrity metadata. Python project locks require exact versions and SHA-256 hashes.
These checks make the dependency input explicit. They do not prove a package is trustworthy or free of vulnerabilities. Review the package, its license and its dependencies before adding it.
Older single-file actions use a separate import-resolution and package-installation path. Do not assume that path has the same lockfile or integrity guarantees as a project build.
Build and test
- Update the dependency manifest and lockfile together.
- Build the project and inspect any installation or build errors.
- Test the resulting action with representative input, including edge cases.
- Publish the tested version and verify its output mapping in HubSpot.
A dependency update can change parsing, rounding or output shapes even when the handler itself is unchanged. Keep an expected-result test for the behavior your workflow relies on.
Compatibility
Package sources. Project lock validation restricts registry sources. Private registries, repository URLs and local linked packages should not be assumed to work.
Native dependencies. Packages that need compilation or system libraries depend on what the build and execution environments provide. Test the actual package and version rather than assuming every npm package or Python wheel is supported.
Resources. A large dependency or dataset can exceed the action’s memory or time budget. See the current plan allowances and inspect the action’s configured limits.
Filesystem persistence. Do not rely on files surviving a run. Use ctx.store for supported persistent key-value state.
Supply-chain review
Dependency pinning is not a security scan. Do not rely on this documentation as a promise of automatic vulnerability or typosquatting detection. Review updates and avoid logging package configuration that contains credentials.
For an outcome-focused example, see the phone-normalization recipe or personalized document workflow.