Jira REST API Client

Common errors

• mime.getType is not a function

  cause 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'

  cause 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

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

  cause 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`.

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: Upgrade your Node.js runtime environment to version 20.0.0 or higher.
• deprecated Several 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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install jira.js npm
• yarn add jira.js yarn
• pnpm add jira.js pnpm

Imports

• Version3Client
  wrong:

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

  correct:

  import { Version3Client } from '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
  wrong:

  import { BasicAuth } from 'jira.js';

  correct:

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

  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
  wrong:

  import { Issue } from 'jira.js';

  correct:

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

  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.

Quickstart

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();