{"id":16834,"library":"jira.js","title":"Jira REST API Client","description":"Jira.js is a robust, production-ready JavaScript and TypeScript library designed for seamless interaction with Atlassian Jira Cloud APIs. Currently in version 5.3.1, it provides comprehensive coverage for Jira Cloud REST API v2/v3, Jira Agile Cloud API, and Jira Service Desk Cloud API. The library is actively maintained with regular updates to incorporate new Jira API features and bug fixes, typically releasing patches and minor versions frequently. Its key differentiators include full TypeScript support with exhaustive type definitions, tree-shakability for optimized bundle sizes in browser environments, universal compatibility with Node.js (v20+) and modern browsers, and complete API coverage. It adheres to a modern stack, supporting both ES Modules and CommonJS, and is widely used in production for building Jira integrations, automation tools, webhooks, and custom applications.","status":"active","version":"5.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/MrRefactoring/jira.js","tags":["javascript","jira","jira-api","jira api","jira rest api","jira cloud","jira cloud api","jira v3","jira v2","typescript"],"install":[{"cmd":"npm install jira.js","lang":"bash","label":"npm"},{"cmd":"yarn add jira.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add jira.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v5.0.0, jira.js primarily uses ESM. While a CJS build exists, ESM imports are the recommended and most reliable method, especially in modern Node.js environments. For older CommonJS projects, use require, but be aware of potential past issues like those fixed in v5.1.1 and v5.3.1.","wrong":"const { Version3Client } = require('jira.js');","symbol":"Version3Client","correct":"import { Version3Client } from 'jira.js';"},{"note":"Authentication strategies are typically imported from the dedicated 'jira.js/auth' sub-path for better tree-shaking and module separation. This applies to other auth methods like OAuth2Auth as well.","wrong":"import { BasicAuth } from 'jira.js';","symbol":"BasicAuth","correct":"import { BasicAuth } from 'jira.js/auth';"},{"note":"TypeScript users can import core types like 'Issue' from the 'jira.js/api' path to get type definitions for API responses and request bodies without pulling in the entire client implementation.","wrong":"import { Issue } from 'jira.js';","symbol":"Issue","correct":"import { Issue } from 'jira.js/api';"}],"quickstart":{"code":"import { Version3Client } from 'jira.js';\nimport { BasicAuth } from 'jira.js/auth';\n\nconst host = process.env.JIRA_HOST ?? 'https://your-domain.atlassian.net';\nconst email = process.env.JIRA_EMAIL ?? 'your-email@example.com';\nconst apiToken = process.env.JIRA_API_TOKEN ?? 'YOUR_JIRA_API_TOKEN';\n\nconst client = new Version3Client({\n  host,\n  authentication: new BasicAuth({ email, apiToken }),\n});\n\nasync function createJiraIssue() {\n  try {\n    const issue = await client.issues.createIssue({\n      fields: {\n        project: {\n          key: 'YOURPROJECTKEY', // e.g., 'TEST'\n        },\n        summary: 'Example issue created by jira.js client',\n        issuetype: {\n          name: 'Task', // Or 'Bug', 'Story' etc.\n        },\n        description: {\n          type: 'doc',\n          version: 1,\n          content: [\n            {\n              type: 'paragraph',\n              content: [\n                {\n                  type: 'text',\n                  text: 'This is a test issue created programmatically using jira.js.',\n                },\n              ],\n            },\n          ],\n        },\n        priority: {\n          name: 'Medium',\n        },\n      },\n    });\n    console.log(`Issue created successfully: ${issue.key} at ${host}/browse/${issue.key}`);\n    return issue;\n  } catch (error) {\n    console.error('Error creating Jira issue:', error);\n    if (error.response) {\n      console.error('Jira API Response Error:', error.response.status, error.response.data);\n    }\n    throw error;\n  }\n}\n\n// To run this example, ensure JIRA_HOST, JIRA_EMAIL, and JIRA_API_TOKEN are set\n// in your environment variables or replace the placeholders directly.\n// createJiraIssue();\n","lang":"typescript","description":"This example demonstrates how to initialize the Jira.js client using basic authentication (email and API token) and then create a new Jira issue within a specified project."},"warnings":[{"fix":"Migrate CommonJS `require()` statements to ES Modules `import` syntax where possible. If strictly needing CommonJS, ensure your build system is configured to handle `module` resolution for packages like jira.js that ship both ESM and CJS builds. Refer to Node.js documentation on ES Modules and package.json 'exports' field.","message":"Version 5.0.0 introduced full ESM (ECMAScript Modules) support and removed all telemetry-related code. This means that direct `require()` statements might behave differently or fail for certain module paths compared to prior versions if not correctly configured for hybrid ESM/CJS environments.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js runtime environment to version 20.0.0 or higher.","message":"The minimum required Node.js version has been updated to Node.js 20 or newer. Running jira.js on older Node.js versions will result in compatibility errors.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Use `IssueSearch.searchForIssuesUsingJqlEnhancedSearch` or `IssueSearch.searchForIssuesUsingJqlEnhancedSearchPost` for improved JQL searching functionality.","message":"Several issue search methods have been deprecated in favor of enhanced alternatives: `IssueSearch.searchForIssuesUsingJql`, `IssueSearch.searchForIssuesUsingJqlPost`, and `IssueSearch.searchForIssuesIds`.","severity":"deprecated","affected_versions":">=5.1.0"},{"fix":"Ensure all imports refer to explicit file paths or named exports from the package root. Do not rely on internal aliases that are not part of the public API surface.","message":"The `~` alias, previously used for certain internal paths, was removed due to compatibility issues with various build systems. Projects relying on this alias for direct imports would have failed.","severity":"gotcha","affected_versions":">=5.2.1"},{"fix":"Upgrade to jira.js v5.3.1 or newer to ensure stability of the CommonJS build. If possible, consider migrating to ES Modules for future-proofing and better interoperability with modern JavaScript ecosystems.","message":"Past versions (prior to v5.3.1 and v5.1.1) experienced issues with the CommonJS build, including `mime.getType is not a function` errors and general `CommonJS requiring` problems, impacting projects that explicitly used the CJS distribution.","severity":"gotcha","affected_versions":">=5.0.0 <5.3.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade jira.js to version 5.3.1 or later. This version replaced the problematic `mime` dependency with `mime-types` which supports both ESM and CJS.","cause":"The CommonJS build of jira.js was attempting to use an ESM-only dependency (`mime`) which led to this error in CJS environments.","error":"mime.getType is not a function"},{"fix":"Review your import statements. Ensure you are importing from documented public API paths (e.g., `jira.js` or `jira.js/auth`) and not relying on internal aliases that are subject to change or removal.","cause":"Reliance on internal aliases or incorrect module paths, particularly the `~` alias, which was removed due to build system incompatibilities.","error":"Error: Cannot find module 'jira.js/some-internal-path'"},{"fix":"Upgrade jira.js to version 5.3.0 or later. This version fixed the serialization logic for multiple project IDs in `getWorkflowSchemeProjectAssociations`.","cause":"When calling `getWorkflowSchemeProjectAssociations`, multiple project IDs were being serialized as a single comma-separated query parameter instead of multiple `projectId=` parameters, which Jira's API did not correctly parse.","error":"Jira API Response Error: 400 ... 'projectId' must be specified multiple times"},{"fix":"Upgrade jira.js to version 5.2.2 or later to ensure the correct URL is generated for `version2.issues.bulkFetchIssues`.","cause":"Incorrect URL generation for the `bulkFetchIssues` method within the `Version2Client`.","error":"TypeError: client.version2.issues.bulkFetchIssues is not a function"}],"ecosystem":"npm","meta_description":null}