Create a new app using the CLI

• Run the command below in your terminal to create a new project with a boilerplate template to get you started.

hs project create

• Follow the commands to set up your project. When prompted to select the base contents of your project, select App.
• Continue to follow the CLI prompts to configure your app details, including:
  • [—distribution]: select whether you plan to distribute your app on the HubSpot App Marketplace or if want to restrict installation to a specific HubSpot accounts.
  • [—auth]: select whether you want to use OAuth for the ability to authenticate multiple accounts, or opt for a static token to limit installation to a specific account.
  • [—features]: select which app features to include, which will create a directory for each feature, along with the respective config files you’ll need to get started. Press spacebar to select a feature, the a key to toggle all features, the i key to invert your current selection, and the enter key to proceed. The following app features are available:
    • Card: an app card that will appear on a CRM record page.
    • App Function: add support for CMS serverless functions.
    • Settings: add an app settings page.
    • Webhooks: add a configuration file to specify webhook subscriptions.
    • Custom Workflow Action: add a custom workflow action.
  After selecting your app features, the HubSpot CLI will create a top-level project directory, as well as subdirectories for the app features you chose. Next, you’ll customize the configuration for the app and any of its associated features.

​

Configure UIDs and initial app features

• Change the uid property of the app in the top-level app-hsmeta.json file and give a unique name to represent your new app.
• If you opted for static authentication for a privately distributed app, remove the redirectUrls sub-property within the auth field of your app-hsmeta.json configuration (see line 10 in the example code block below).

{
  "uid": "new_developer_platform_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with developer projects.",
    "name": "my first app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

• For any features you want to include (e.g., app cards), update the UID within any associated *-hsmeta.json configuration files in your project.

​

Set up OAuth (if applicable)

• Add one or more valid redirect URLs to the app-hsmeta.json file based on your local (or another non-production) OAuth server configuration.
• If you don’t have a backend service set up already, you can get started by using the sample OAuth Node.js example and run it locally. It’s already set up to work with https://localhost:3000/oauth-callback as the redirect URL configured in the boilerplate example code from the hs project create command you ran in the previous step.

{
  "uid": "new_developer_platform_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with developer projects.",
    "name": "my first app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

​

Upload your project

• In the terminal, run hs project open from within your local project directory to open the project details page in HubSpot.
• Under Project Components, click the name of your app.

• Click the Auth tab.
• Under Client credentials, copy the Client ID and Client secret from your new app and paste them into the corresponding locations in your OAuth server’s configuration, then restart your OAuth server.

• Navigate to Test accounts in the Development navigation menu, then click Create developer test account. Follow the prompts to create your new test account.
• In the left sidebar menu, navigate to Projects, click the name of your new project, then click the UID of your app in the component list.
• On the Auth tab, copy your app’s install link.
• Use this link to install the app in your developer test account.
• Open the test account and navigate to the Connected Apps page, where you should see your installed app listed.