Jira project page

The jira:projectPage module adds the app in the horizontal tab navigation in Jira.

The page URL is constructed in the form of: /jira/{projectType}/projects/{projectKey}/apps/{appId}/{envId}

This module can be used in Jira and Jira Service Management.

When adding this to your app, use it as a top-level component.

Subpages

By default, the jira:projectPage module registers a top-level page. However, you can create multiple subpages using either a pages or sections field to organize your app's functionality.

Use pages to add individual pages to the app and sections to group related pages together.

This configuration only changes the project page URL structure. You must handle routes inside your Custom UI app using view.createHistory() for proper navigation.

Manifest example

1
2
modules:
  jira:projectPage:
    - key: hello-world-project-page
      resource: main
      resolver:
        function: resolver
      render: native
      title: Hello World!

Properties

i18n object

Page

Manifest example

1
2
modules:
  <module-name>:
    - key: hello-world-jira-module-page-example
      resource: main
      resolver:
        function: resolver
      render: native
      title: Hello World
      pages:
        - title: page example
          route: page-example-1
          icon: https://example.com/icon.png

Properties

Section

Manifest example

1
2
modules:
  <module-name>:
    - key: hello-world-jira-module-section-example
      resource: main
      resolver:
        function: resolver
      render: native
      title: Hello World
      sections:
        - header: example section
          pages:
            - title: page example
              route: page-example-1
              icon: https://example.com/icon.png

Properties

Extension data

UI Kit and Custom UI

Your Jira project page can access contextual project information through extension data. Use the useProductContext hook to access the extension context in UI Kit applications or the getContext bridge method in Custom UI applications.

Frequently asked questions

How do I create a Jira project page?

Add the jira:projectPage module to your Forge app's manifest:

1
2
modules:
  jira:projectPage:
    - key: hello-world-project-page
      resource: main
      resolver:
        function: resolver
      render: native
      title: Hello World!

Using UI Kit with render: native ensures your page has the proper Jira look and feel. UI Kit offers a wide range of pre-built and customizable components that align with Atlassian's design standards.

What's the difference between pages and sections in subpages?

• Pages: Individual subpages that appear directly in your app's navigation
• Sections: Groups of pages organized under section headers for better organization
• You can only use either pages OR sections, not both in the same module

Can I use custom icons for my project page?

Yes, you can specify a custom icon using the icon property. Provide a URL to your icon image. If no icon is specified, a generic app icon will be displayed.

What layout options are available for project pages?

The layout property supports:

• UI Kit: native (default) or basic
• Custom UI: native (default), blank, or basic (deprecated) The layout of the project page defines whether a page is rendered with default controls (native), lays out the entire viewport with a margin on the left and breadcrumbs (basic for UI Kit), or is left blank allowing for full customization (blank for Custom UI).

UI Kit Layouts

• native: Includes all default Jira project page controls and navigation elements
• basic: Provides a simplified layout with left margin, breadcrumbs, and minimal controls

Custom UI Layouts

• native: Includes standard Jira project page chrome and navigation
• blank: Provides a completely empty canvas for full viewport customization
• basic: (Deprecated) Similar to UI Kit's basic layout with left margin and breadcrumbs

How do I handle routing in subpages?

For subpages to work properly, you need to:

1. Define pages or sections in your manifest
2. Implement routing in your Custom UI app using view.createHistory()

1
2
import { view } from "@forge/bridge";

const history = await view.createHistory();

// e.g. URL begins as http://example.atlassian.net/example/apps/abc/123

history.push("/page-1");
// this updates the URL to http://example.atlassian.net/example/apps/abc/123/page-1

history.push("/page-2");
// this updates the URL to http://example.atlassian.net/example/apps/abc/123/page-2

history.go(-2);
// this updates the URL to http://example.atlassian.net/example/apps/abc/123

3. Each page's route property becomes part of the URL path

Can I restrict when my project page appears?

Yes, use the displayConditions property to control when your module is visible. This allows you to show the page only in specific project types or under certain conditions.

Is the project page module compatible with Jira Service Management?

Yes, the jira:projectPage module works in both Jira Software and Jira Service Management. In JSM, the page appears in the left navigation panel.