# Apps FAQ This page answers common questions about planning, building, and distributing apps for YouTrack. ## Planning an App What is the difference between a workflow and an app? : An app is the general package for custom YouTrack functionality. A pure workflow is a simple app package that contains workflow rules only. : : : : Apps are the primary choice for new development because they can combine workflow rules with widgets, custom HTTP endpoints, custom MCP tools, settings, and app-owned data. Pure workflows remain available for focused automation created and managed with the dedicated workflow tools in YouTrack. : : : : Rules supplied by apps can appear in workflow administration views so project administrators can see which automation affects a project, but the app and its configuration are managed through the app administration views. For details, see [YouTrack JavaScript Runtime Environment](app-architecture.html). What can I add to YouTrack with an app? : An app can add widgets to supported locations in the YouTrack UI, expose custom HTTP handlers, declare app settings, store custom values in extension properties, and include JavaScript-based modules such as workflow rules. Starting from YouTrack 2025.3, apps can also provide [custom MCP tools](custom-ai-tools.html). : : : : For an overview of an app package, see [App Package Overview](app-overview.html). For the full list of widget locations, see [Extension Points for Widgets](apps-reference-extension-points.html). Can an app change built-in YouTrack pages? : An app can add content only to supported widget locations. It cannot rewrite arbitrary parts of the YouTrack UI or change the behavior of built-in controls directly. : : : : If you need to show custom controls on an issue, article, dashboard, project page, project settings tab, or another supported location, use a widget. If you need to react to changes in YouTrack data, use a workflow rule or HTTP handler. Can I build a dashboard widget or a full app page? : Yes. Use a `DASHBOARD_WIDGET` for a widget that appears on a dashboard, or use `MAIN_MENU_ITEM` or `ADMINISTRATION_MENU_ITEM` for a full app page. Use `PROJECT_TAB` for a project-specific page that opens from the project sidebar. Use `PROJECT_SETTINGS` when the app needs a project-specific settings tab instead of a project page. The widget can read YouTrack data with the Host API or call app HTTP handlers that prepare data on the backend. : : : : These locations display app-owned widgets or pages. Apps cannot currently add custom reports to the built-in Reports area. : : : : For available locations, see [Extension Points for Widgets](apps-reference-extension-points.html). For communication between widgets and YouTrack, see [Host API](apps-host-api.html). Can I build a time tracker or timer as an app? : Yes. A timer app usually combines an issue widget with custom HTTP handlers. The widget provides the start, stop, and save controls. The handlers read and update work items or store intermediate timer state. : : : : For a complete example, see [App Use Case: Simple Timer](app-uc-simple-timer.html). ## Data and Integrations How do apps store data? : Apps can store data in several common ways: : : : : * Starting from YouTrack 2026.2, you can use [host.storage](apps-host-api.html#storage) when the value should persist in the user's browser and be shared by widgets from the same app. : : * Use YouTrack fields and entities when the data belongs to the regular project model. : : * Use extension properties when the app owns the value and needs to attach it to an issue, article, project, user, or another supported entity. : : * Use app global storage when the value belongs to the app rather than to a specific YouTrack entity. : : : : For server-side app storage, see [Extension Properties](apps-extension-properties.html). Can an app use browser local storage or cookies? : App widgets run in a sandboxed IFrame and do not have direct access to `localStorage`, `sessionStorage`, web cookies, or other uncontrolled browser storage APIs. : : : : Starting from YouTrack 2026.2, you can use [host.storage](apps-host-api.html#storage) for controlled persistent app data stored locally in the browser. Use YouTrack data, extension properties, or app global storage for data that must be available outside the current browser or protected by YouTrack permissions. Can an app integrate with external services? : Yes. Widget code can send HTTP requests to third-party services. For server-side integration logic, credentials, logic shared by several widgets, or calls that should run in YouTrack's backend sandbox, use custom HTTP handlers. : : : : HTTP handlers can use modules from the YouTrack workflow API package `@jetbrains/youtrack-scripting-api`, including the `http` module, to communicate with external services. Widgets can call these handlers with `host.fetchApp()`. : : : : Apps can also expose custom HTTP handlers as webhook endpoints for external services. For an example, see [Webhook Triggers](https://www.jetbrains.com.cn/en-us/help/youtrack/cloud/webhook-triggers.html). : : : : Store tokens, passwords, and API keys as secret app settings. For details, see [Use Workflow API Modules in HTTP Handlers](apps-reference-http-handlers.html#workflow-modules-in-http-handlers) and [Working with Settings for Secrets](app-settings.html#working-with-secrets). Should I call the YouTrack REST API directly from a widget? : Use the Host API from widgets whenever possible. Requests sent through `host.fetchYouTrack()` use the current user's YouTrack session and do not require an authorization header in the widget code. : : : : If you need to combine several requests, hide integration details, call an external service, or perform backend-only logic, call an app HTTP handler from the widget instead. Can an app create recurring issues or scheduled updates? : Yes, but the scheduled part is usually implemented as a workflow rule. Use an on-schedule rule to create or update issues at a configured interval. Package the workflow in an app if you also need a widget, app settings, or a reusable distribution package. : : : : For workflow schedules, see [On-schedule Rules](on-schedule-rules.html). How do I request only specific custom fields from issues? : When you request issues with the REST API, include the `customFields` attribute in the `fields` request parameter, then add a separate `customFields` request parameter for each field that you want to return. : : : : For example, this widget request returns only the Score custom field for unresolved issues: : : : : : ```JAVASCRIPT : const host = await YTApp.register(); : const issues = await host.fetchYouTrack( : 'issues?query=%23Unresolved' : + '&fields=idReadable,summary,customFields(name,value(presentation,name))' : + '&customFields=Score' : ); : ``` : : : : To request multiple custom fields, repeat the `customFields` parameter in the URL. Can I search for issues by app extension properties? : Yes, from JavaScript modules that run in YouTrack. The `@jetbrains/youtrack-scripting-api/search` module accepts an object query with an `extensionPropertiesQuery` block. : : : : : ```JAVASCRIPT : const search = require('@jetbrains/youtrack-scripting-api/search'); : : const query = { : query: 'State: {In Progress}', : extensionPropertiesQuery: { : score: 1500 : } : }; : : const issues = search.search(ctx.issue.project, query, ctx.currentUser); : ``` : : : : Extension property queries match explicit property values. They are not a replacement for regular issue search fields when you need range queries, query completion, or sorting in the YouTrack issue list. Use a YouTrack custom field for values that users need to search or sort in the UI. ## Widgets and Layout How do I control the size of a widget opened from an issue or article options menu? : Widgets for `ISSUE_OPTIONS_MENU_ITEM` and `ARTICLE_OPTIONS_MENU_ITEM` open in a modal window. Set the `expectedDimensions` object in the widget manifest to request the modal size in pixels. : : : : : ```JSON : { : "key": "issue-action", : "name": "Issue Action", : "extensionPoint": "ISSUE_OPTIONS_MENU_ITEM", : "indexPath": "issue-action/index.html", : "expectedDimensions": { : "width": 800, : "height": 600 : } : } : ``` : : : : YouTrack tries to display the widget with these dimensions when the monitor settings allow. Dynamic resizing of an already opened modal is not currently exposed through the Host API. Can I add widgets to attachment or comment options menus? : Currently, there are no dedicated extension points for attachments or comments. : : : : If you need to add an action to the Show more menu for a comment or attachment, use a [workflow action rule](action-rules.html) instead. Starting from YouTrack 2024.2, action rules can be applied to issue comments, article comments, issue attachments, and article attachments. : : : : You can also use a supported issue, article, or Markdown extension point instead. For the current list of supported extension points, see [Extension Points for Widgets](apps-reference-extension-points.html). Can a full-page widget force itself to 100% of the available page height? : Full-page and page-level widgets such as `MAIN_MENU_ITEM`, `ADMINISTRATION_MENU_ITEM`, and `PROJECT_TAB` are hosted in an iframe. In YouTrack 2026.2 and later, these widgets take at least the available page height when no explicit height is set. : : : : Use the widget's own CSS to define the height of its root element and content. If your widget needs the automatic full-height layout, don't set the `height` attribute in the `expectedDimensions` manifest field. Set `expectedDimensions.height` only when you need a fixed pixel-height display hint. ## Access and Configuration How do I decide whether an app feature is global or project-specific? : Project scope applies to features associated with a project, including issue and article widgets, project pages, project settings, helpdesk channels, workflow rules, and project-level HTTP handlers. Attach the app to each target project so its project-scoped rules, widgets, and HTTP handlers are active there. Project administrators with the Update Project permission can manage these features for their projects. : : : : Global scope applies to features that are not bound to a project, including user-related widgets, main menu and administration pages, dashboard and Markdown widgets, and global HTTP handlers. Global features are managed at the system level by system administrators. Managing global HTTP handlers requires the Low-level Admin Write permission. : : : : For details, see [Global and Project Scopes](apps-global-project-level.html). How do I let each project configure the app differently? : Define app settings in `settings.json` and use the appropriate scope for each setting. Project administrators can configure project-level settings in the projects where the app is attached. System administrators can configure global settings for the whole YouTrack service. : : : : For details, see [App Settings](app-settings.html). How do I control who sees a widget? : Use the `permissions` field in the widget manifest to require YouTrack permissions, and use widget guards to show a widget only when the current entity matches your conditions. : : : : Permission restrictions are useful for access control. Guards are useful for context, for example showing an issue widget only for issues with a specific type or state, or showing a project widget only for selected projects. : : : : For details, see [App Permissions](app-permissions.html) and [Guard Entity Reference](apps-widget-guards.html#guard-entity-reference). Do app scripts need their own YouTrack credentials? : No. JavaScript modules that run inside YouTrack do not need separate YouTrack credentials. Widget requests made through the Host API are authenticated as the current user. : : : : If code outside the Host API calls the YouTrack REST API or Hub REST API, follow the authentication rules for these APIs. For details, see [Authentication for Apps](apps-authentication.html). Who can upload and attach apps? : Installing and updating apps from JetBrains Marketplace require the Low-level Admin Write permission. Uploading a custom app package to YouTrack requires either the global Update Project permission or the system Low-level Admin Write permission. : : : : For development and testing, the upload command generated by the YouTrack app generator can use a permanent token for an account with Update Project permission. To attach project-level app modules to projects, a user needs Update Project permission for the corresponding projects. : : : : Global HTTP handler modules require additional administrative permissions to manage. For details, see [Scopes for HTTP Handlers](apps-global-project-level.html#scopes-http-handlers). ## Development and Distribution What is the fastest way to start building an app? : Use the YouTrack app generator: : : : : : ```SHELL : npm create @jetbrains/youtrack-app@latest : ``` : : : : The generator creates the app package structure and can scaffold widgets and other app elements. For details, see [App Quick Start Guide](apps-quick-start-guide.html). Should I use the TypeScript Enhanced DX toolchain? : Use the experimental TypeScript-based toolchain when you want file-based routing, generated API types, and stronger type checking for widgets, handlers, app settings, and extension properties. : : : : For details, see [Enhanced DX for TypeScript Apps](apps-enhanced-dx-typescript.html). How should I package and test an app before sharing it? : Build the app package, check that `manifest.json` is at the root of the package, confirm that widgets and JavaScript modules are stored in their expected locations, and upload the resulting ZIP file to a test YouTrack service. : : : : For details, see [Launch Checklist](app-launch-checklist.html) and [Upload the App to YouTrack](apps-quick-start-guide.html#add-app-to-youtrack). Where can I find examples? : Start with the [Simple Timer](app-uc-simple-timer.html) tutorial, the public [YouTrack apps repository](https://github.com/JetBrains/youtrack-apps), and the [YouTrack Demo App repository](https://github.com/JetBrains/youtrack-demo-app). How do I make a widget match the YouTrack user interface? : App widgets run in a sandboxed iframe, so YouTrack's frontend styles don't apply to widget content directly. : : : : Use [Ring UI](https://jetbrains.github.io/ring-ui) components for visible controls when practical, and add widget-specific CSS for layout and spacing. This helps custom widgets look consistent with the surrounding YouTrack user interface while keeping their styles isolated. Can apps be installed from JetBrains Marketplace? : Yes. YouTrack administrators can install apps directly from JetBrains Marketplace when the YouTrack site has internet access. : : : : Installing an app from Marketplace preserves the link between the app and Marketplace, so updates can be installed from YouTrack when a new version is published. Installing and updating Marketplace apps requires the Low-level Admin Write permission. You can still upload a ZIP file manually for custom apps that aren't distributed through Marketplace if you have the required upload permissions. : : : : For installation instructions, see [Install an App from Marketplace](install-apps-from-marketplace.html). How do I publish an app on JetBrains Marketplace? : You can submit a packaged YouTrack app to JetBrains Marketplace for public distribution. Publication requires a JetBrains Account and a vendor profile. The app is added to the public directory after a Marketplace moderator reviews and approves it. : : : : For step-by-step instructions, see [Publish the App](apps-quick-start-guide.html#publish-app).