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

About

Jira.js is a powerful, production-ready Node.js and browser-compatible TypeScript library that provides seamless interaction with Atlassian Jira Cloud APIs. This npm package offers comprehensive support for:

• Jira Cloud REST API v2/v3 - Complete platform API coverage
• Jira Agile Cloud API - Sprint, board, and backlog management
• Jira Service Desk Cloud API - Service desk operations

Key Features

• ✅ Type-Safe: Full TypeScript support with comprehensive type definitions and IntelliSense
• ✅ Tree-Shakable: Optimize bundle size by importing only what you need (perfect for browser apps)
• ✅ Universal: Works in Node.js (v20+) and modern browsers with full ESM/CJS support
• ✅ Complete Coverage: Nearly 100% of Jira Cloud REST API v2/v3, Agile, and Service Desk APIs
• ✅ Well Documented: Extensive JSDoc, API reference, and code examples
• ✅ Modern Stack: Built with TypeScript, supports ES Modules and CommonJS
• ✅ Actively Maintained: Regular updates with new Jira API features and bug fixes
• ✅ Production Ready: Used by thousands of developers in production environments

Perfect for building Jira integrations, automation tools, webhooks, CI/CD pipelines, custom Jira applications, and browser-based Jira management tools.

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

Install the Jira.js npm package using your preferred package manager. 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

TypeScript users: Type definitions are included - no additional @types package needed!

Quick Example

Get started with Jira.js in under 5 minutes. This example shows how to create a Jira issue using the TypeScript client:

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, guides, and examples available at: https://mrrefactoring.github.io/jira.js/

The documentation includes:

• Complete API reference for all endpoints
• TypeScript examples and code samples
• Authentication guides
• Error handling patterns
• Best practices and tips

Supported APIs

Jira.js provides comprehensive support for all major Jira Cloud APIs:

• Jira Platform REST API v2: Legacy API endpoints for projects, issues, users, and more
• Jira Platform REST API v3: Modern API with enhanced features and improved performance
• Jira Software (Agile) API: Sprint management, boards, backlogs, and agile workflows
• Jira Service Desk API: Service desk operations, customer management, and request handling

All APIs are fully typed with TypeScript definitions, making development faster and safer.

Usage

Authentication

Email and API Token

1. Create an API token: https://id.atlassian.com/manage-profile/security/api-tokens
2. 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

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

🔽 Core REST API (v2/v3)

• api
• announcementBanner
• appDataPolicy
• applicationRoles
• appMigration
• auditRecords
• avatars
• classificationLevels
• dashboards
• filters
• fieldSchemes
• filterSharing
• groupAndUserPicker
• groups
• instanceInformation
• issues
• issueAttachments
• issueBulkOperations
• issueComments
• issueCustomFieldAssociations
• issueCustomFieldConfigurationApps
• issueCommentProperties
• issueFields
• issueFieldConfigurations
• issueCustomFieldContexts
• issueCustomFieldOptions
• issueCustomFieldOptionsApps
• issueCustomFieldValuesApps
• issueLinks
• issueLinkTypes
• issueNavigatorSettings
• issueNotificationSchemes
• issuePriorities
• issueProperties
• issueRedaction
• issueRemoteLinks
• issueResolutions
• issueSearch
• issueSecurityLevel
• issueSecuritySchemes
• issueTypes
• issueTypeSchemes
• issueTypeScreenSchemes
• issueTypeProperties
• issueVotes
• issueWatchers
• issueWorklogs
• issueWorklogProperties
• jiraExpressions
• jiraSettings
• jql
• jqlFunctionsApps
• labels
• licenseMetrics
• migrationOfConnectModulesToForge
• 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 & Bundle Optimization

Jira.js supports tree shaking to minimize your bundle size. Import only the modules you need:

// 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' });

Benefits:

• Smaller bundle sizes for browser applications
• Faster load times
• Better performance in production

Use Cases

Jira.js is perfect for:

• 🔄 CI/CD Integration: Automate issue creation and updates in your deployment pipelines
• 🤖 Automation Scripts: Build custom automation for Jira workflows and processes
• 📊 Reporting & Analytics: Extract and analyze Jira data for custom dashboards
• 🔗 Webhook Handlers: Process Jira webhooks and integrate with external systems
• 🛠️ Custom Tools: Build admin tools, migration scripts, and custom Jira applications
• 📱 Browser Apps: Create browser-based Jira management interfaces
• 🔌 Third-Party Integrations: Connect Jira with other services and platforms

Common Questions

Q: Does this work with Jira Server/Data Center?
A: No, Jira.js is designed specifically for Jira Cloud. For on-premise Jira, consider using the REST API directly.

Q: Is TypeScript required?
A: No, but TypeScript is fully supported with comprehensive type definitions. You can use Jira.js with plain JavaScript too.

Q: Can I use this in the browser?
A: Yes! Jira.js works in both Node.js and modern browsers. Make sure to handle CORS if calling Jira APIs from a browser.

Q: How do I handle authentication?
A: Jira.js supports Basic Auth (email + API token) and OAuth 2.0. See the Authentication section above.

Other Products

Explore our other Atlassian integration libraries:

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

MIT License © MrRefactoring
See LICENSE for details.