Movatterモバイル変換

MrRefactoring/jira.jsPublic

NotificationsYou must be signed in to change notification settings
Fork61
Star476

A JavaScript/TypeScript wrapper for the JIRA Cloud, Service Desk and Agile REST API

mrrefactoring.github.io/jira.js/

License

MIT license

476 stars 61 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 249 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.ts		eslint.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
rollup.config.ts		rollup.config.ts
tsconfig.json		tsconfig.json
vitest.config.mts		vitest.config.mts

Repository files navigation

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

About

Jira.js is a powerfulNode.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

Requires Node.js 20.0.0 or newer.

# Using npmnpm install jira.js# Using yarnyarn add jira.js# Using pnpmpnpm add jira.js

Quick Example

Create your first Jira issue in under 5 minutes:

import{Version3Client}from'jira.js';constclient=newVersion3Client({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},},});asyncfunctioncreateIssue(){constproject=awaitclient.projects.getProject({projectIdOrKey:'Your project id or key'});constnewIssue=awaitclient.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:

constclient=newVersion3Client({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'sOAuth 2.0 documentation.

constclient=newVersion3Client({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)
Error: Network/configuration issues (e.g., timeouts)

Example handling:

try{awaitclient.issues.getIssue({issueIdOrKey:'INVALID-123'});}catch(error){if(errorinstanceofHttpException){console.error('Server error:',error.message);console.debug('Response headers:',error.cause.response?.headers);}elseif(errorinstanceofError){console.error('Network error:',error.code);}else{console.error('Unexpected error:',error);}}

API Structure

Access endpoints using theclient.<group>.<method> pattern:

// Get all projectsconstprojects=awaitclient.projects.searchProjects();// Create a sprintconstsprint=awaitclient.sprint.createSprint({name:'Q4 Sprint'});

Available API groups:

🔽 Agile Cloud API

🔽 Core REST API (v2/v3)

🔽 Service Desk API

See full group list inoriginal documentation.

Tree Shaking

Optimize bundle size by importing only needed modules:

// custom-client.tsimport{BaseClient}from'jira.js';import{Issues}from'jira.js/version3';import{Board}from'jira.js/agile';exportclassCustomClientextendsBaseClient{issues=newIssues(this);board=newBoard(this);}// Usageconstclient=newCustomClient({/* config */});awaitclient.issues.getIssue({issueIdOrKey:'KEY-1'});