@nextcloud/axios

@nextcloud/axios

Simple, typed wrapper of an Axios instance for Nextcloud that automatically sends authentication headers. Cancellation is supported as well.

Installation

npm install @nextcloud/axios --save

yarn add @nextcloud/axios

Usage

import axios from '@nextcloud/axios'

axios.get('nextcloud.com')

See https://github.com/axios/axios for details.

Defining baseURL

You are able to define baseURL to simplify the usage of axios across your app.

import axios from '@nextcloud/axios'
import { generateUrl } from '@nextcloud/router'

const baseURL = generateUrl('/apps/your_app_id/api')

axios.defaults.baseURL = baseURL

Retry handling

This package can optionally retry requests if they fail due to Nextcloud's maintenance mode. To activate this feature, pass retryIfMaintenanceMode: true into the request options. This mechanism will only catch relatively short server maintenance downtime in the range of seconds to a minute. Any longer downtime still has to be handled by the application, show feedback to the user, reload the page etc.

import axios from '@nextcloud/axios'

const pizzas = await axios.get('/apps/pizza/api/pizzas', {
    retryIfMaintenanceMode: true,
})
const myPizza = await axios.post('/apps/pizza/api/pizzas', { toppings: ['pineapple'] }, {
    retryIfMaintenanceMode: true,
})

Expired sessions handling

This package can optionally trigger a page reload whenever a request fails due to an expired user session. This interrupts application logic and should be the last resort. If possible, handle the expired session higher up in the application.

import axios from '@nextcloud/axios'

const response = await axios.get('/apps/foo/api/bar', {
    reloadExpiredSession: true,
})

References

• @nextcloud/router
• Nextcloud App Routing

Changelog

2.5.2 - 2025-09-20

Fixed

• fix: add missing config interface typing for reloadExpiredSession

Changed

• refactor: add SPDX headers
• refactor: migrate REUSE to TOML format
• refactor: resolve Typescript errors and stabilize tests
• chore: migrate to ESLint v9
• chore: allow wider engine version range
• chore: adjust package.json
  • make order consistent with other libraries
  • update maintainer information
  • fix wrong URLs
• ci: update reuse.yml workflow from organization
• ci: update npm-publish.yml workflow from template
• ci: update workflows from organization
• Bump @nextcloud/auth to 2.5.1
• Bump axios to 1.12.2