{"id":13388,"library":"jira-client","title":"Jira Client for Node.js","description":"jira-client is an actively maintained, open-source Node.js module that provides an object-oriented wrapper for the Jira REST API. It aims to simplify programmatic interaction with Jira by abstracting HTTP requests into easy-to-use method calls, handling authentication, and parsing responses. The current stable version is 8.2.2. The project generally follows a regular release cadence with patch and minor updates for bug fixes, dependency bumps, and new API method support. Major versions, occurring less frequently, typically introduce breaking changes such as dropping support for older Node.js versions or swapping underlying HTTP client libraries. Its core value lies in offering a consistent, promise-based API for common Jira operations, making it suitable for developing automation scripts, integrations, and custom tools that interact with Jira in a Node.js environment.","status":"active","version":"8.2.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/jira-node/node-jira-client","tags":["javascript"],"install":[{"cmd":"npm install jira-client","lang":"bash","label":"npm"},{"cmd":"yarn add jira-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add jira-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal HTTP client library for making requests to the Jira API. Replaced 'request' in v8.0.0.","package":"postman-request"},{"reason":"Internal utility for generating unique IDs, used within the client's operations.","package":"nanoid"}],"imports":[{"note":"The JiraApi class is exported as a default export in ESM. Attempting a named import will result in 'JiraApi is not a constructor'.","wrong":"import { JiraApi } from 'jira-client';","symbol":"JiraApi","correct":"import JiraApi from 'jira-client';"},{"note":"In CommonJS, the JiraApi class is the module's default export. Destructuring it will result in an undefined value, leading to 'JiraApi is not a constructor'.","wrong":"const { JiraApi } = require('jira-client');","symbol":"JiraApi","correct":"const JiraApi = require('jira-client');"},{"note":"The JiraApi constructor expects a single configuration object with all options (protocol, host, username, password, etc.), not individual positional arguments.","wrong":"new JiraApi('https', 'jira.example.com', 'user', 'pass');","symbol":"JiraApi client initialization","correct":"new JiraApi({ host: 'jira.example.com', username: 'user', password: 'pass' });"}],"quickstart":{"code":"import JiraApi from 'jira-client';\nimport process from 'process';\n\nasync function getJiraIssueStatus(issueNumber: string) {\n  // It's crucial to avoid hardcoding sensitive credentials in source code.\n  // Use environment variables or a secure configuration management system.\n  const jira = new JiraApi({\n    protocol: 'https',\n    host: process.env.JIRA_HOST ?? 'jira.example.com', // Replace with your Jira host\n    username: process.env.JIRA_USERNAME ?? 'your_username',\n    password: process.env.JIRA_PASSWORD ?? 'your_password',\n    apiVersion: '2',\n    strictSSL: true // Set to false if using self-signed certs (not recommended for production)\n  });\n\n  try {\n    const issue = await jira.findIssue(issueNumber);\n    console.log(`Issue ${issueNumber} status: ${issue.fields.status.name}`);\n    console.log(`Summary: ${issue.fields.summary}`);\n    console.log(`Assignee: ${issue.fields.assignee ? issue.fields.assignee.displayName : 'Unassigned'}`);\n  } catch (err) {\n    console.error(`Error fetching issue ${issueNumber}:`, err);\n    if (err.statusCode === 401) {\n      console.error(\"Authentication failed. Check your username and password and ensure proper permissions.\");\n    } else if (err.statusCode === 404) {\n      console.error(`Issue ${issueNumber} not found.`);\n    }\n  }\n}\n\n// To run this example, replace 'YOUR-ISSUE-KEY' with a valid Jira issue key\n// and ensure JIRA_HOST, JIRA_USERNAME, JIRA_PASSWORD environment variables are set\n// or provide them directly (for testing).\ngetJiraIssueStatus('YOUR-ISSUE-KEY');","lang":"typescript","description":"Demonstrates how to initialize the JiraApi client and fetch the status, summary, and assignee of a specific Jira issue using async/await."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer, or pin your `jira-client` dependency to a version prior to 8.0.0.","message":"Node.js 12 support was officially removed in `v8.0.0`. Projects still on Node.js 12 must either remain on `jira-client@7.x` or upgrade their Node.js environment to version 16 or newer.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Review your `JiraApi` client initialization options and any custom `doRequest` overrides to ensure compatibility with `postman-request`. Consult its documentation for migration details if you leveraged specific `request` features.","message":"The underlying HTTP request library changed from `request` to `postman-request` in `v8.0.0`. This change might affect custom configurations related to proxies, SSL certificates, or advanced request options previously tailored for the `request` library.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Test the `addIssueToSprint()` functionality thoroughly after upgrading to `v7.0.0` or higher to confirm it interacts correctly with your Jira instance's API and desired sprint management.","message":"The `addIssueToSprint()` method changed its internal API endpoint in `v7.0.0`. While the method signature remains the same, its interaction with the Jira API differs from previous versions.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Always attach a `.catch()` block to your promise chains or wrap `await` calls in `try...catch` blocks to handle potential errors gracefully. For example: `jira.findIssue(...).then(...).catch(err => console.error(err));`","message":"Promise rejections from API calls are not automatically handled and can be 'swallowed' if not explicitly caught, leading to silent failures. This is standard JavaScript Promise behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If connecting to a Jira instance with a self-signed certificate (e.g., in development), set `strictSSL: false` in the JiraApi constructor options. For production, consider configuring your environment to trust the certificate or using a properly signed, publicly trusted certificate.","message":"The `strictSSL` option in the JiraApi constructor defaults to `true`. If your Jira instance uses a self-signed or otherwise untrusted SSL certificate, connections will fail with an SSL error. Setting `strictSSL: false` for production is generally discouraged due to security implications.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For development environments, set `strictSSL: false` in the JiraApi client configuration. For production, ensure your environment trusts the certificate authority (CA) that signed the Jira server's certificate, or configure Jira to use a publicly trusted certificate.","cause":"The Jira server is using a self-signed SSL certificate, and the `jira-client` is configured to enforce strict SSL verification (`strictSSL: true`).","error":"Error: self signed certificate in certificate chain"},{"fix":"For ESM, use `import JiraApi from 'jira-client';`. For CommonJS, use `const JiraApi = require('jira-client');`. Do not use `{ JiraApi }` in either scenario.","cause":"The `JiraApi` class was not correctly imported or required, typically due to attempting a named import/destructuring for a default export.","error":"TypeError: JiraApi is not a constructor"},{"fix":"Ensure all API calls are followed by a `.catch()` method or wrapped in a `try...catch` block when using `async/await` to properly handle and log potential errors.","cause":"A Promise returned by a Jira API method rejected (e.g., due to a network error or a Jira API error response) but was not explicitly handled by a `.catch()` block or `try...catch` statement.","error":"UnhandledPromiseRejectionWarning: Unhandled promise rejection."},{"fix":"Verify the `username` and `password` in your JiraApi client configuration. Additionally, check the permissions of the Jira account to ensure it can perform the desired actions.","cause":"The provided `username` or `password` for authentication with Jira is incorrect, or the authenticated account lacks the necessary permissions for the requested operation.","error":"Error: statusCode: 401, data: { errorMessages: [ 'You are not authenticated.' ] }"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}