jira.js

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:

• Jira Cloud API
• Jira Agile Cloud API
• Jira ServiceDesk Cloud API

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

Table of Contents

• Getting Started
  • Installation
  • Quick Example
• Documentation
• Usage
  • Authentication
    • Email and API Token
    • OAuth 2.0
  • Error Handling
  • API Structure
• 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: '[e-mail]',
      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: '[e-mail]', 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

• backlog
• board
• builds
• deployments
• developmentInformation
• devopsComponents
• epic
• featureFlags
• issue
• operations
• remoteLinks
• securityInformation
• sprint

🔽 Core REST API (v2/v3)

• announcementBanner
• appDataPolicy
• applicationRoles
• appMigration
• auditRecords
• avatars
• classificationLevels
• dashboards
• filters
• filterSharing
• groupAndUserPicker
• groups
• instanceInformation
• issues
• issueAttachments
• issueBulkOperations
• issueComments
• issueCustomFieldAssociations
• issueCustomFieldConfigurationApps
• issueCommentProperties
• issueFields
• issueFieldConfigurations
• issueCustomFieldContexts
• issueCustomFieldOptions
• issueCustomFieldOptionsApps
• issueCustomFieldValuesApps
• issueLinks
• issueLinkTypes
• issueNavigatorSettings
• issueNotificationSchemes
• issuePriorities
• issueProperties
• issueRemoteLinks
• issueResolutions
• issueSearch
• issueSecurityLevel
• issueSecuritySchemes
• issueTypes
• issueTypeSchemes
• issueTypeScreenSchemes
• issueTypeProperties
• issueVotes
• issueWatchers
• issueWorklogs
• issueWorklogProperties
• jiraExpressions
• jiraSettings
• jql
• jqlFunctionsApps
• labels
• licenseMetrics
• myself
• permissions
• permissionSchemes
• plans
• prioritySchemes
• projects
• projectTemplates
• projectAvatars
• projectCategories
• projectClassificationLevels
• projectComponents
• projectEmail
• projectFeatures
• projectKeyAndNameValidation
• projectPermissionSchemes
• projectProperties
• projectRoles
• projectRoleActors
• projectTypes
• projectVersions
• screens
• screenTabs
• screenTabFields
• screenSchemes
• serverInfo
• serviceRegistry
• status
• tasks
• teamsInPlan
• timeTracking
• uiModificationsApps
• users
• userNavProperties
• userProperties
• userSearch
• webhooks
• workflows
• workflowTransitionRules
• workflowSchemes
• workflowSchemeProjectAssociations
• workflowSchemeDrafts
• workflowStatuses
• workflowStatusCategories
• workflowTransitionProperties
• appProperties
• dynamicModules

🔽 Service Desk API

• customer
• info
• insight
• knowledgeBase
• organizations
• request
• requestType
• serviceDesk

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

License

MIT License © MrRefactoring See LICENSE for details.

Changelog

5.2.1

Bug Fixes

• Removed ~ alias due to compatibility issues with some build systems. Thanks @ThomasTrepanier, for reporting.