vue-auth-href

Breaking changes: 2.0.0 and later are not compatible with the previous 1.8.0 Vue 2 release. If you still need Vue 2 support, use version 1.8.0.

Vue 3 directive and composable for downloading protected resources with authentication headers.

vue-auth-href intercepts an anchor click, performs an authenticated GET, converts the response to a blob, and triggers the browser download flow. In 2.0.0, the library is rewritten for Vue 3, TypeScript, Vite+, and Vitest.

Install

pnpm add vue-auth-href vue

Plugin Usage

Register the plugin once and keep the token resolver in plugin options.

import { createApp } from "vue";
import App from "./App.vue";
import VueAuthHref from "vue-auth-href";

const app = createApp(App);

app.use(VueAuthHref, {
  token: () => localStorage.getItem("access_token"),
  headers: {
    "x-client": "dashboard",
  },
  loading: {
    text: "Downloading",
  },
});

app.mount("#app");

Then use the directive on any anchor:

<template>
  <a v-auth-href href="/api/reports/monthly.csv">Download report</a>
</template>

Inline directive options still override the plugin defaults:

<template>
  <a
    v-auth-href="{
      loading: {
        text: 'Preparing file',
        animateDots: false,
      },
    }"
    href="/api/reports/monthly.csv"
  >
    Download report
  </a>
</template>

Composable Usage

Use the composable when you want full control over the trigger element or UI state.

<script setup lang="ts">
import { useAuthDownload } from "vue-auth-href";

const { download, error, isDownloading, status } = useAuthDownload({
  token: () => localStorage.getItem("access_token"),
});

async function downloadReport() {
  await download({
    url: "/api/reports/monthly.csv",
    fileName: "monthly.csv",
  });
}
</script>

<template>
  <button :disabled="isDownloading" type="button" @click="downloadReport">
    {{ isDownloading ? "Downloading..." : "Download report" }}
  </button>

  <p v-if="status === 'error' && error">Download failed: {{ error.message }}</p>
</template>

API

AuthDownloadOptions

Shared options used by the composable and directive:

Option	Type	Default	Description
token	string | Ref<string | null | undefined> | (() => string | null | undefined)	-	Required unless provided by plugin or composable defaults.
authHeader	string	"Authorization"	Header name used for the auth token.
authScheme	string	"Bearer"	Prepended to the token as <scheme> <token>. Use "" to send the raw token.
headers	Record<string, string>	{}	Extra request headers.
request	Omit<RequestInit, "headers" | "method">	undefined	Extra fetch options such as credentials.
fetcher	fetch-compatible function	globalThis.fetch	Override for testing or custom transports.
fileName	string | ((response, url) => string | undefined)	undefined	Preferred file name before falling back to response headers or the URL.
cleanupDelay	number	-1	Delay before removing the generated blob link.
onBeforeDownload	() => void | Promise<void>	undefined	Invoked before the request starts.
onSuccess	(result) => void	undefined	Invoked after a successful download.
onError	(error) => void	undefined	Invoked with an AuthDownloadError.
onSettled	(outcome) => void	undefined	Invoked after success or failure.

AuthHrefDirectiveOptions

Directive options extend AuthDownloadOptions with a loading object:

Option	Type	Default	Description
loading.mode	"text" | "html"	"text"	Controls whether loading content uses text or raw HTML.
loading.text	string	"Downloading"	Text shown while the request is in flight.
loading.html	string	""	HTML shown while the request is in flight.
loading.animateDots	boolean	true	Adds the dot animation when loading.mode is "text".
loading.replaceContent	boolean	true	Replaces the anchor content while downloading.

useAuthDownload()

The composable returns:

• status: idle | pending | success | error
• isDownloading: readonly boolean ref
• error: readonly AuthDownloadError | null ref
• download(request, overrides?)
• reset()

Exports

import VueAuthHref, {
  AuthDownloadError,
  createAuthHrefDirective,
  createAuthHrefPlugin,
  useAuthDownload,
  vAuthHref,
} from "vue-auth-href";

Development

pnpm install
pnpm run check
pnpm run test:run
pnpm run build

The project uses:

• Vite+ for build, format, and toolchain orchestration
• Vitest and @vue/test-utils for unit tests
• TypeScript for the library source and public types

Migration

2.0.0 is a breaking release. See MIGRATION.md for the upgrade notes from the Vue 2 line.

License

MIT