Jira.js - Jira Cloud API library

JavaScript / TypeScript library for Node.js and browsers to interact with Atlassian Jira APIs

About

Jira.js is a powerful Node.js and browser-compatible module that provides seamless interaction with:

Designed for usability, consistency, and performance, it covers nearly 100% of Jira APIs and stays updated with new features.

Getting Started
- Installation
- Quick Example
Documentation
Usage
Tree Shaking
Other Products
License

Getting Started

Installation

Requires Node.js 20.0.0 or newer.

# Using npm
npm install jira.js

# Using yarn
yarn add jira.js

# Using pnpm
pnpm add jira.js

Quick Example

Create your first Jira issue in under 5 minutes:

import { Version3Client } from 'jira.js';

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'your@email.com',
      apiToken: 'YOUR_API_TOKEN', // Create one: https://id.atlassian.com/manage-profile/security/api-tokens
    },
  },
});

async function createIssue() {
  const project = await client.projects.getProject({ projectIdOrKey: 'Your project id or key' });

  const newIssue = await client.issues.createIssue({
    fields: {
      summary: 'Hello Jira.js!',
      issuetype: { name: 'Task' },
      project: { key: project.key },
    },
  });

  console.log(`Issue created: ${newIssue.id}`);
}

createIssue();

Documentation

Full API reference and guides available at: https://mrrefactoring.github.io/jira.js/

Usage

Authentication

Email and API Token

Create an API token: https://id.atlassian.com/manage-profile/security/api-tokens
Configure the client:

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: { email: 'YOUR@EMAIL.ORG', apiToken: 'YOUR_API_TOKEN' },
  },
});

OAuth 2.0

Only authorization code grants are supported. Implement your own token acquisition flow using Atlassian's OAuth 2.0 documentation.

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    oauth2: { accessToken: 'YOUR_ACCESS_TOKEN' },
  },
});

Error Handling

Errors are categorized as:

HttpException: Server responded with an error (includes parsed error details)
AxiosError: Network/configuration issues (e.g., timeouts)

Example handling:

try {
  await client.issues.getIssue({ issueIdOrKey: 'INVALID-123' });
} catch (error) {
  if (error instanceof HttpException) {
    console.error('Server error:', error.message);
    console.debug('Response headers:', error.cause.response?.headers);
  } else if (error instanceof AxiosError) {
    console.error('Network error:', error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

API Structure

Access endpoints using the client.<group>.<method> pattern:

// Get all projects
const projects = await client.projects.searchProjects();

// Create a sprint
const sprint = await client.sprint.createSprint({ name: 'Q4 Sprint' });

Available API groups:

🔽 Agile Cloud API

🔽 Core REST API (v2/v3)

🔽 Service Desk API

See full group list in original documentation.

Tree Shaking

Optimize bundle size by importing only needed modules:

// custom-client.ts
import { BaseClient } from 'jira.js';
import { Issues } from 'jira.js/version3';
import { Board } from 'jira.js/agile';

export class CustomClient extends BaseClient {
  issues = new Issues(this);
  board = new Board(this);
}

// Usage
const client = new CustomClient({ /* config */ });
await client.issues.getIssue({ issueIdOrKey: 'KEY-1' });

Other Products

Explore our other Atlassian integration libraries:

Confluence.js - Interact with Confluence API
Trello.js - Trello API integration