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
.
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 runnpm 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 runningnpm i -g @hubspot/cli@latest
.
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 alocal.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.
- 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.
- 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.
- If you're building a public app, you'll only be able to select from your connected developer test accounts.
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
.
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
.
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.
Thank you for your feedback, it means a lot to us.