@hubspot/app-functions-dev-server
v0.8.31
Published
A tool for testing HubSpot private app functions locally
Downloads
23,186
Maintainers
Keywords
Readme
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
- There is a project that contains the private app, which contains the app functions.
- The HubSpot CLI has been initialized for the project and a target account.
- 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. - If an app function requires a secret, the developer must supply a value for the secret using a
.env
file in theapp.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 CLIupload
andwatch
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]