jira.js

library5.3.1jsnpmunverified

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.

crm-productivity

npm install jira.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JIRA.JS

jira.js

crm-productivityjavascriptv5.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Version3Client

✓ import { Version3Client } from 'jira.js';

✗ const { Version3Client } = require('jira.js');

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.

BasicAuth

✓ import { BasicAuth } from 'jira.js/auth';

✗ import { BasicAuth } from 'jira.js';

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.

Issue

✓ import { Issue } from 'jira.js/api';

✗ import { Issue } from 'jira.js';

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.

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.

import { Version3Client } from 'jira.js'; import { BasicAuth } from 'jira.js/auth'; const host = process.env.JIRA_HOST ?? 'https://your-domain.atlassian.net'; const email = process.env.JIRA_EMAIL ?? 'your-email@example.com'; const apiToken = process.env.JIRA_API_TOKEN ?? 'YOUR_JIRA_API_TOKEN'; const client = new Version3Client({ host, authentication: new BasicAuth({ email, apiToken }), }); async function createJiraIssue() { try { const issue = await client.issues.createIssue({ fields: { project: { key: 'YOURPROJECTKEY', // e.g., 'TEST' }, summary: 'Example issue created by jira.js client', issuetype: { name: 'Task', // Or 'Bug', 'Story' etc. }, description: { type: 'doc', version: 1, content: [ { type: 'paragraph', content: [ { type: 'text', text: 'This is a test issue created programmatically using jira.js.', }, ], }, ], }, priority: { name: 'Medium', }, }, }); console.log(`Issue created successfully: ${issue.key} at ${host}/browse/${issue.key}`); return issue; } catch (error) { console.error('Error creating Jira issue:', error); if (error.response) { console.error('Jira API Response Error:', error.response.status, error.response.data); } throw error; } } // To run this example, ensure JIRA_HOST, JIRA_EMAIL, and JIRA_API_TOKEN are set // in your environment variables or replace the placeholders directly. // createJiraIssue();

Debug

Known issues

breakingVersion 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.

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.

affects: >=5.0.0

breakingThe 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.

fix

Upgrade your Node.js runtime environment to version 20.0.0 or higher.

affects: >=5.0.0

deprecatedSeveral issue search methods have been deprecated in favor of enhanced alternatives: `IssueSearch.searchForIssuesUsingJql`, `IssueSearch.searchForIssuesUsingJqlPost`, and `IssueSearch.searchForIssuesIds`.

fix

Use `IssueSearch.searchForIssuesUsingJqlEnhancedSearch` or `IssueSearch.searchForIssuesUsingJqlEnhancedSearchPost` for improved JQL searching functionality.

affects: >=5.1.0

gotchaThe `~` 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.

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.

affects: >=5.2.1

gotchaPast 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.

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.

affects: >=5.0.0 <5.3.1

Errors

Common errors & fixes

mime.getType is not a function

The CommonJS build of jira.js was attempting to use an ESM-only dependency (`mime`) which led to this error in CJS environments.

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.

Error: Cannot find module 'jira.js/some-internal-path'

Reliance on internal aliases or incorrect module paths, particularly the `~` alias, which was removed due to build system incompatibilities.

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.

Jira API Response Error: 400 ... 'projectId' must be specified multiple times

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.

fix

Upgrade jira.js to version 5.3.0 or later. This version fixed the serialization logic for multiple project IDs in `getWorkflowSchemeProjectAssociations`.

TypeError: client.version2.issues.bulkFetchIssues is not a function

Incorrect URL generation for the `bulkFetchIssues` method within the `Version2Client`.

fix

Upgrade jira.js to version 5.2.2 or later to ensure the correct URL is generated for `version2.issues.bulkFetchIssues`.

Upgrade

Version history

5.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/MrRefactoring/jira.js ↗

packagehttps://www.npmjs.com/package/jira.js ↗

homepagehttps://mrrefactoring.github.io/jira.js ↗