Loading repository data…
Loading repository data…
MrRefactoring / repository
Modern Jira REST API client for JavaScript & TypeScript — Jira Cloud API v2/v3, Agile & Service Desk. Type-safe, tree-shakable, works in Node.js and browsers (ESM/CJS).
🌐 English · Русский
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:
Perfect for building Jira integrations, automation tools, webhooks, CI/CD pipelines, custom Jira applications, and browser-based Jira management tools.
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!
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();
📚 Full API reference, guides, and examples available at: https://mrrefactoring.github.io/jira.js/
The documentation includes:
Jira.js provides comprehensive support for all major Jira Cloud APIs:
All APIs are fully typed with TypeScript definitions, making development faster and safer.
const client = new Version3Client({
host: 'https://your-domain.atlassian.net',
authentication: {
basic: { email: 'YOUR@EMAIL.ORG', apiToken: 'YOUR_API_TOKEN' },
},
});
jira.js supports the full Atlassian OAuth 2.0 (3LO) flow. The simplest setup uses a static access token:
const client = new Version3Client({
host: 'https://your-domain.atlassian.net',
authentication: {
oauth2: { accessToken: 'YOUR_ACCESS_TOKEN' },
},
});
Full flow with automatic refresh and cloudId resolution. Provide refresh credentials and the client refreshes the access token on expiry (and on 401), persists the rotated refresh token via onTokenRefresh, and routes requests through the API gateway (https://api.atlassian.com/ex/jira/{cloudId}) — so no host is needed. clientSecret and refresh are server-side only.
const client = new Version3Client({
// no `host` — the cloudId is resolved automatically (pass `siteUrl` or `cloudId` to pin it)
authentication: {
oauth2: {
accessToken: 'CURRENT_ACCESS_TOKEN',
refreshToken: 'CURRENT_REFRESH_TOKEN',
clientId: 'YOUR_CLIENT_ID',
clientSecret: 'YOUR_CLIENT_SECRET',
expiresAt: Date.now() + 3600 * 1000, // optional; epoch milliseconds
onTokenRefresh: async ({ accessToken, refreshToken, expiresAt }) => {
await saveTokens({ accessToken, refreshToken, expiresAt }); // persist the rotated tokens
},
},
},
});
jira.js also exports stateless helpers for the authorization-code flow — generateAuthorizationUrl, exchangeAuthorizationCode, refreshOAuth2Token, getAccessibleResources. See the step-by-step OAuth 2.0 guide.
For Atlassian Connect apps, authenticate with a per-request JWT signed using your app's shared secret. This is a server-side flow — the shared secret must never be shipped to a browser.
Note: Atlassian Connect is reaching end of support (Q4 2026), and new private apps can no longer be installed via a descriptor URL. JWT auth here is intended for existing Connect app installations.
issuer: your app key — the key field in your atlassian-connect.json descriptor.secret: the sharedSecret your app receives in the body of the installed lifecycle webhook during the installation handshake. Store it per-tenant.expiryTimeSeconds (optional): token lifetime in seconds (defaults to 180, i.e. 3 minutes).const client = new Version3Client({
host: 'https://your-domain.atlassian.net',
authentication: {
jwt: {
issuer: 'YOUR_APP_KEY',
secret: 'YOUR_SHARED_SECRET',
expiryTimeSeconds: 180, // optional
},
},
});
A fresh JWT is generated for every request, with a query-string hash (qsh) bound to that request's method and URL. See the step-by-step setup guide for how to create a Connect app and obtain the issuer and secret.
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);
}
}
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: