Overview

Serverless functions provide a way for private apps to run server-side code on HubSpot's infrastructure, typically to interact with HubSpot or third-party APIs on behalf of the app's React frontend that runs in a user's browser. Serverless functions for private apps are also called app functions.

The app functions dev server allows for app functions to run locally on a developer's machine instead of on HubSpot. This is useful for quick iterative development, epsecially when also running the React extension in local dev mode. However, there may differences between local and production execution.

Pre-requisites

1. There is a project that contains the private app, which contains the app functions.
2. The HubSpot CLI has been initialized for the project and a target account.
3. The developer has a valid Personal Access Key (PAK) for the account. The PAK must contain at least the same scopes as those specified for the private app in the app.json file.
4. If an app function requires a secret, the developer must supply a value for the secret using a .env file in the app.functions directory. This applies to the PRIVATE_APP_ACCESS_TOKEN, too. See dotenv for more information about .env files and their variants.

CAUTION: Add the pattern ".env*" to your .gitignore file so that secrets do not get committed to a repository by mistake. Hidden files are automatically ignored when using the CLI upload and watch commands.

Usage

app-functions-dev-server runs as part of the ui-extensions-dev-server. To run and develop this codebase, follow the contribution guidelines in the dev server repository.

Deploying Changes

Because this package is a dependency of other tools, rather than something used directly, there are a few steps involved in deploying changes. First, the package is released to NPM. Then, the dependency version is bumped in the consuming ui-extensions-dev-server package.

Releasing the NPM Packages

[!NOTE] This guide is intended for @HubSpot/ui-extensibility engineers, who've already logged into public npm via bend yarn npm:login and have publishing credentials stored locally in ~/.npmrc.public_publish. If you don't have that file locally, or aren't sure what this means, reach out in #ui-extensibility.

When ready to publish your changes, the process is similar to how we publish other UIE assets, but changesets is refreshingly simple when compared to lerna.

The Changesets CLI calculates the appropriate version based on all the changes queued up for release in the .changeset/ directory, and prepares your packages for release. This "versioning resolution" process is entirely automated and doesn’t require you to manually intervene.

1. Ask your teammates to hold off on merging until you're done with this process\
2. Check the .changeset directory to see if there is a .md file for this release. If not, generate one with yarn changeset. Open a PR with these changes before continuing on.
3. Make sure you've got all git tags pulled down locally, via git pull --tags -f
4. Run npm run changeset:version to generate the new version number, and update the package.json accordingly. This delegates to the npx changeset version command with your npm credentials properly applied
5. Run npm run changeset:publish to ship your updates to the public registry! This delegates to the npx changeset publish under the hood
6. Check the @hubspot/app-functions-dev-server package on npmjs.com to see the updated contents (or use the CLI to inspect it a la npm show @hubspot/app-functions-dev-server) and verify you can install and use the new version
7. Run git push --tags to push the generated tags to the remote repo
8. Open up a PR with the changes from your release.

Updating Package Consumers

Releasing the NPM package isn't enough. You also need to update the consumers of the package before the change is considered "fully released". Some changes require just a CLI bump, others require just an Artifactor bump, and some will need both.

If the changes impact the CLI, put in a PR in their repo to bump the version.

If the changes impact the remote build, put in a PR in Artifactor and use our docs to help test and release the version bump.