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

$3

- ✅ 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

$3

Install the Jira.js npm package using your preferred package manager. Requires Node.js 20.0.0 or newer.

``bash


Using npm

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

$3

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

`typescript
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

$3

#### Email and API Token

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

`typescript
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.

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

$3

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

Example handling:

`typescript
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);
}
}
`

$3

Access endpoints using the client.. pattern:

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

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

Available API groups:


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:

`typescript
// 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.