hubspot-functions-server v1.0.1

HubSpot Functions Server

Why This Tool?

While HubSpot's serverless functions provide a powerful way to extend HubSpot's functionality, the development and testing process can be challenging. Currently, HubSpot doesn't provide a local development environment for testing serverless functions, requiring developers to:

1. Write their function.
2. Deploy to HubSpot.
3. Wait for deployment.
4. Test the function.
5. Repeat if changes are needed.

This process is time-consuming and inefficient, especially during active development.

Solution

HubSpot Functions Server bridges this gap by providing a local development environment that:

• ⚡️ Runs your HubSpot functions locally
• 🔄 Hot-reloads changes instantly
• 🔑 Uses your actual HubSpot credentials
• 📁 Works with your existing serverless.json configuration
• 🛠️ Provides immediate feedback
• 🪲 Shows detailed error messages and logs

Instead of waiting for deployments, you can:

• Test functions instantly.
• See console.log outputs.
• Debug step by step.
• Iterate quickly.

This tool is essential for any developer working with HubSpot serverless functions who wants to maintain a rapid development cycle and catch issues early in the development process.

Installation

npm install hubspot-functions-server

Usage

Configuration

Your serverless.json should follow the HubSpot format:

{
  "appFunctions": {
    "getSubscriptions": {
      "file": "getSubscriptions.js",
      "secrets": ["HSKEY"],
      "endpoint": {
        "path": "get-subscriptions",
        "method": ["GET"]
      }
    }
  }
}

Command Line Parameters

When running the functions server, you can use the following parameters:

hubspot-functions-server [options]

Options:
  --accessToken     [Required] Your HubSpot private app access token
  --accountId       [Required] Your HubSpot account ID
  --port            [Optional] Port to run the server on (default: 4000)
  --projectPath     [Optional] Directory of your functions project. It should
                    contain the serverless.json file and either a list of
                    functions or the folder containing them.
                    Default: /app/app.functions.
  --debug           [Optional] Enable debug mode.

Examples

Basic usage:

hubspot-functions-server --accessToken your_token --accountId your_account_id

Custom port:

hubspot-functions-server --accessToken your_token --accountId your_account_id --port 4001

Custom project path:

hubspot-functions-server --accessToken your_token --accountId your_account_id --projectPath /path_to_serverless_json_file

With debug mode:

hubspot-functions-server --accessToken your_token --accountId your_account_id --debug

Integration in you current HubSpot project

This is an example of a project where the React frontend and the serverless functions are part of the same project. You should adapt the commands to suit your needs and environment variables.

1. Install required libraries:

npm install concurrently dotenv-cli

2. Add to your package.json:

{
  "scripts": {
    "functions-server": "hubspot-functions-server --accessToken $HSKEY --accountId $HS_ACCOUNT_ID",
    "dev": "concurrently -n \"web,server\" -c \"blue,magenta\" \"npm run start\" \"dotenv npm run functions-server\""
  }
}

3. Then run:

# Run HubSpot functions server and the fronted project
npm run dev

# OR

# Starts only the HubSpot functions server
npm run functions-server

4. After successfully starting the project, you can access the following locations:

Frontend Application: http://hslocal.net:3000

Serverless Functions: http://localhost:4000

IMPORTANT

The script to start the server must be defined in the root package.json file. It's important that the start script is in the root of the project because we have detected unexpected errors when the script was placed in a nested folder.

Features Details

Hot Reloading

The server watches for changes in:

• Function files in app/app.functions/.
• Configuration file in app/app.functions/serverless.json.

Error Handling

• Full stack traces for errors
• Console output from functions
• Detailed error responses

Request Context

Your functions receive the same context as in HubSpot's environment:

• params
• body
• query
• headers

Note: params and query are passed to params (It's what HubSpot does).

Debug mode

When debug mode is enabled, you'll see detailed information about the functions execution.

The output includes:

• Function loading and execution
• Request/response data
• Performance timings
• API calls
• Error details

Local Development

To work on this package locally while testing it with your project, you can use npm's linking feature.

In this package's directory, build the project:

npm run build

Link it globally:

npm link

In your project directory, link to this package:

npm link hubspot-functions-server

Tests (Vitest)

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run with watch mode
npm run test:watch

Linting (Biome)

# Check for issues
npm run lint

# Fix issues automatically
npm run lint:fix

# Format code
npm run format

# Format and fix
npm run format:fix

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change 😬

License

MIT