@hubspot/app-functions-dev-server

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

Running a stand-alone dev server for app.functions

The following will start a server on http://localhost:6789:

npm install
npm start <app_dir>

Pass the path to the app's base directory, e.g., /path/to/src/app. The app directory must contain a app.functions directory and a app.functions/serverless.json file serving as a manifest for available app functions. For example:

# Content of ./serverless.json
{
  "runtime": "nodejs18.x",
  "version": "1.0",
  "appFunctions": {
    "example": {
      "file": "example-function.js",
      "secrets": []
    }
  }
}

# Content of ./example-function.js
exports.main = async (context = {}, sendResponse) => {
  sendResponse('text is okay');
};

To execute the app function named "example", run:

curl -H "Content-Type: application/json" http://localhost:6789/action/function/101 -d '{"serverlessFunction": "example"}'
# Expected response: { logId: "n/a", response: "text is okay" }

Running as middleware on another server

The AppFunctionExecutionService can also be used as middleware on another express server. For example, we can add a route in the ui-extension dev server like this:

import { AppFunctionExecutionService } from '@hubspot/app-functions-dev-server';

const mainApp = express();

mainApp.use('/api/crm-extensibility/execution/internal/v3', AppFunctionExecutionService({app: {path: '/path/to/src/app'}}));

// ...vite middleware for handling extensions...

mainApp.listen(5173, () => {...});

Development

Testing as a stand-alone server

Running in watch mode

Replacing npm start with npm run start:nodemon will start the server and watch for file changes in ./src.

Debugging in VS Code

To use the Node.js debugging support in VS Code, first define the following launch configuration in <repoRoot>/.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "start:nodemon",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run start:nodemon /path/to/src/app",
      "cwd": "${workspaceRoot}/public-packages/app-functions-dev-server"
    }
  ]
}

Be sure to replace /path/to/src/app with the actual path to your project's app directory. It is also assumed that from the current working directory, the HubSpot CLI would be able to detect a default account with a valid Personal Access Key. This is needed for the server to make API calls.

Once the configuration is added, go to the "Run and Debug" view in VS Code, select the "start:nodemon" config, and click the green play button. This will launch a terminal and run npm run start:nodemon with a debugger attached. Now you can set breakpoints and have fun debugging.

Testing as middleware in the UI extensions dev server

Suppose you are working on cool-branch, and you want to test the local dev workflow locally.

Link local dependencies (one-time setup)

Register the local version of @hubspot/ui-extensions-dev-server using npm link or yarn link:

cd /path/to/ui-extensions-dev-server
yarn link

Use the local version where you want it:

cd <project>/src/app/extensions
yarn
yarn link @hubspot/ui-extensions-dev-server

Test the UIE dev server in a project

Run the dev server for both the selected extension and its app functions in a project directory:

cd <project>/src/app/extensions
yarn run dev [-e <extension>.tsx]

Update to reflect code changes

Anytime a change is made in app-functions-dev-server, run the following to pull it into ui-extensions-dev-server:

cd /path/to/app-functions-dev-server
npm run build
cd /path/to/ui-extensions-dev-server
yarn

Finally restart the dev server with yarn run dev [-e <extension>.tsx]