App pages reference - HubSpot docs

Below, find reference information for building app pages.

Project structure

To add app pages to an app, create a pages directory within src/app. The pages directory should contain:

A JSON configuration file that defines the pages configuration (Pages-hsmeta.json is recommended).
A React file that renders the pages component (Pages.jsx or Pages.tsx is recommended).
A package.json file to handle any needed dependencies.

project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── pages/
            ├── pages-hsmeta.json
            ├── Pages.tsx
            └── package.json

App pages configuration

In the *-hsmeta.json configuration file for your app pages, include the properties below.

{
  "uid": "my-app-pages",
  "type": "page",
  "config": {
    "entrypoint": "/app/pages/Pages.tsx"
  }
}

Field	Type	Description
`uid`	String	The pages component’s unique identifier. This can be any string, but should meaningfully identify the component.
`type`	String	The type of component, which should be `page` in this case.
`config`	Object	An object containing configuration details.
`entrypoint`	String	The file path of the pages component’s front-end React code.

Building the React front-end

The UI of app pages is created by a React component file, either .jsx or .tsx. This file lives in the pages/ directory alongside the pages configuration JSON file (*-hsmeta.json). In the configuration file, you’ll specify the path of the React file in the entrypoint field. Routes are defined using createPageRouter, which accepts JSX route definitions and returns a React component. For complete examples, see the create app pages guide.

App page URLs

Your app pages can be accessed using the following URL patterns:

Target	URL
Home page	`https://app.hubspot.com/app/{hubId}/{appId}`
Home page with params	`https://app.hubspot.com/app/{hubId}/{appId}?param1Name=param1Value`
Named page	`https://app.hubspot.com/app/{hubId}/{appId}/{pagePath}`
Named page with params	`https://app.hubspot.com/app/{hubId}/{appId}/{pagePath}?param1Name=param1Value`

For example, following the URL path structure above, if a user who installed your app has a HubSpot account ID (i.e., their hubId) of 12345 and your app ID was 67890, they could navigate to their home page at the following URL:

https://app.hubspot.com/app/12345/67890

React page hooks

App pages provide hooks to access routing information within your page components.

usePageRoute

Use the usePageRoute hook to access the current page path and all parameters (both path parameters and query parameters):

import { usePageRoute } from "@hubspot/ui-extensions/pages";

const MyPage = () => {
  const { path, routeId, params } = usePageRoute();
  // path will be "/" for the home page or the current page path like "/docs"
  // routeId is the id assigned to the matched route (e.g., "home", "docs")
  // params contains both path parameters and query parameters

  return (
    <>
      <Text>Current path: {path}</Text>
      <Text>Route: {routeId}</Text>
      <Text>Params: {params.foo}, {params.anotherParam}</Text>
    </>
  );
};

The usePageRoute hook returns an object with:

Property	Type	Description
`path`	String	The current normalized page path (e.g., `"/"`, `"/docs"`).
`routeId`	String	The `id` of the matched route, as defined on the route’s `id` prop. Useful for identifying the active route in layout components.
`params`	Object	An object containing all parameters, including both path parameters (e.g., `:contactId`) and query parameters from the URL.

You can navigate to app pages programmatically using the navigateToPage action from the useExtensionActions hook:

import { Button, hubspot, useExtensionActions } from "@hubspot/ui-extensions";

const MyComponent = () => {
  const { navigateToPage } = useExtensionActions();

  const handleNavigate = () => {
    navigateToPage({
      to: '/docs',
      params: { foo: 'bar', anotherParam: 'abc' }
    });
  };

  return (
    <Button onClick={handleNavigate}>
      Go to Documentation
    </Button>
  );
};

The navigateToPage function accepts an options object with the following properties:

Property	Type	Description
`to`	String	The path to navigate to (e.g., `"/"` for home, `"/docs"` for a named page). The path will be normalized (e.g., `"docs"` becomes `"/docs"`).
`params`	Object	An object containing query parameters to include in the URL (e.g., `{ foo: 'bar' }`).

createPageRouter

The createPageRouter function accepts JSX route definitions and returns a React component that handles routing. Call it at the module level with your <PageRoutes> tree:

import { createPageRouter, PageRoutes } from "@hubspot/ui-extensions/pages";

const PageRouter = createPageRouter(
  <PageRoutes>
    <PageRoutes.IndexRoute component={AppHomePage} />
    <PageRoutes.Route path="/docs" component={AppDocsPage} />
    <PageRoutes.AnyRoute component={AppNotFoundPage} />
  </PageRoutes>
);

function App() {
  return <PageRouter />;
}

Parameters

Parameter	Type	Description
`routes`	`ReactNode`	A `<PageRoutes>` JSX tree defining all routes for your app.

Returns

A React component (PageRouter) that you render in your app to activate routing.

Page routing components

The PageRoutes component and its sub-components are used with createPageRouter to define routing for app pages:

PageRoutes: Container for route definitions. Supports layoutComponent for wrapping child routes with shared UI.
PageRoutes.IndexRoute: Defines the home page (index route) that renders at the root URL of your app.
PageRoutes.Route: Defines a named page route with a path and component.
PageRoutes.AnyRoute: Defines a catch-all route for unmatched paths, useful for custom 404 pages.

Each route sub-component also accepts an optional id prop. When a route matches, the id value is available as routeId from usePageRoute(). See the route IDs section in the routing guide for details. For detailed documentation on routing components including nested routes, path parameters, and wildcard routes, see:

Manage dependencies

You can include dependencies for your app pages in a package.json file within the pages/ directory. By default, when adding app pages through the hs project add command, a package.json file will be created for you with the following dependencies:

@hubspot/ui-extensions
react
typescript

To install dependencies for project components with a package.json file, you can run the hs project install-deps command in your project directory.

{
  "name": "hubspot-example-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}

​Project structure

​App pages configuration

​Building the React front-end

​App page URLs

​React page hooks

​usePageRoute

​Programmatic navigation

​createPageRouter

​Parameters

​Returns

​Page routing components

​Manage dependencies

​Related resources