npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hubspot/app-functions-dev-server

v0.8.31

Published

A tool for testing HubSpot private app functions locally

Downloads

27,237

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

  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]