Local development for UI extensions (BETA)

When building a UI extension, you can run a local development server to iterate and test functionality in real-time without needing to re-upload the project. The local development server is only available for the frontend portion of the app, and assumes the back-end is either running locally or is hosted.

Your app must be uploaded to your development account for the server to work. The local development server will only pick up changes made to React files. For changes to configuration files, you'll need to use hs project upload.

Prerequisites

To run a local development server, ensure that you meet the following prerequisites.

  • Your project must be already uploaded to your account (hs project upload).
  • You must install the necessary dependencies in your extensions directory. If you haven't done so yet, navigate into the /src/app/extensions directory and run npm install.
  • You must be running v6.1.0 of the HubSpot CLI or above. You can check your version by running hs --version, and update by running npm i -g @hubspot/cli@latest.
cd src/app/extensions npm install

Start a local development server

Before starting local development, keep in mind the following for public apps:

  • If you're building a public app that's installed in production accounts, you should not use the production app for local development. Instead, work with a duplicate of the app to avoid making updates to the production app. You can clone an existing public app by running hs project clone-app.
  • If you have a locally running back-end, you can set up a proxy to remap hubspot.fetch() requests made during local development. This proxy is configured through a local.json file in your project. Learn more about proxying requests to a locally running back-end.

To start a local development server:

  • In the terminal, run hs project dev command in your working project directory.
hs project dev
  • You'll then be prompted to select the account to run the server for. This should be the account that the app is installed in.
    • If you're building a public app, you'll only be able to select from your connected developer test accounts.
      cli-select-developer-test-account
    • If you're building a private app, you can select a production account or one of its development sandboxes, or you can create a new development sandbox.
Please note: when creating a new development sandbox, if you receive the error The personal access key you provided doesn't include sandbox permissions, you'll need to deactivate the account's Personal Access Key, then create a new one with sandbox permissions. To do so, run hs auth, then follow the prompts to select your account. Then, click Deactivate next to the personal access key, and generate a new one with the proper scopes.
  • If your project has multiple extensions, you'll be prompted to select which extension to run. You can run multiple extensions from the same app, but not multiple extensions across multiple apps.

After selecting the account and extension, the local development server will then start. To view the locally running version of your UI extension:

  • In your browser, navigate to where the app's UI extension is located, or refresh the page if it's already loaded.
  • The extension will be updated with a Developing locally tag, which indicates that changes to your React files will now be picked up automatically on save without needing to refresh. Changes made to configuration files will not be picked up by the local development server, and will instead need to be uploaded with hs project upload.
    public-app-developing-locally

When you're ready to push your changes to HubSpot, end the server by pressing q in the terminal, then run hs project upload. If your project is not enabled for auto-deploy, you can then deploy it after successful build by running hs project deploy.

Authenticating private app requests

For private apps, the private app access token, and any secrets you might need to use, will need to be made available to the local development server through a .env file within the .functions directory. You can find the private app access token in the app's settings in HubSpot.

Learn more about serverless functions.

PRIVATE_APP_ACCESS_TOKEN=pat-na1-****** ANOTHER_SECRET=my-secret-value
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.