Vite HTTP Basic Auth Plugin

1.0.2 · active · verified Wed Apr 22

vite-plugin-http-basic-auth is a Vite plugin designed to add HTTP Basic Authentication support to the Vite development server and preview server. It is currently at version 1.0.2. As a plugin for Vite, its release cadence is generally tied to the Vite ecosystem, with updates provided as needed for compatibility or new features. This plugin is particularly useful for protecting development or staging environments that are exposed publicly, requiring credentials before allowing access. Key differentiators include its simple configuration within the Vite `defineConfig`, direct integration with environment variables for credentials, and optional enablement for both development and preview modes. It leverages standard HTTP Basic Auth, making it widely compatible with browsers and other clients.

Common errors

```
TypeError: httpAuth is not a function
```
cause Incorrect import statement for the plugin.

fix Ensure you are using the correct ESM import syntax: `import httpAuth from 'vite-plugin-http-basic-auth';`.
```
401 Unauthorized
```
cause Incorrect username/password credentials provided, or the environment variables supplying them are not loaded correctly.

fix Verify the username and password in your `.env` file match what is configured in `vite.config.ts`. Ensure `loadEnv` is correctly configured to load your `.env` file and prefixes.
```
HTTP Basic Auth is not prompting in browser
```
cause The plugin might not be active for the current server type (dev or preview) or the plugin array in Vite config is misconfigured.

fix Check `useInServer` and `useInPreview` options in the plugin configuration. Confirm the plugin is correctly added to the `plugins` array in `vite.config.ts`.

Warnings

gotcha Environment variables starting with `VITE_` are exposed to the client-side bundle in Vite by default. Ensure that sensitive credentials used for server-side basic auth are not inadvertently exposed or handle them with care.
Fix: Access environment variables that should only be server-side without the `VITE_` prefix, or ensure sensitive credentials are only used in the server configuration and not within the client-side code paths.
gotcha Basic Authentication sends credentials in plain text (Base64 encoded, not encrypted) over the network. Always use HTTPS for any environment where this plugin is deployed to prevent eavesdropping.
Fix: Ensure your development and preview servers are served over HTTPS. For Vite, you can configure HTTPS via `server.https: true` in `vite.config.ts` and provide certificate details.
gotcha The plugin's `useInServer` and `useInPreview` options are `true` by default. If you only want basic auth for specific environments (e.g., preview but not dev), you must explicitly set these options to `false` based on your `mode`.
Fix: Conditionally set `useInServer` or `useInPreview` based on `mode`: `useInServer: mode === 'development'`, etc., or omit them to use the default `true`.

Install

npm install vite-plugin-http-basic-auth npm
yarn add vite-plugin-http-basic-auth yarn
pnpm add vite-plugin-http-basic-auth pnpm

Imports

httpAuth
wrong:
```
const httpAuth = require('vite-plugin-http-basic-auth');
```
correct:
```
import httpAuth from 'vite-plugin-http-basic-auth';
```
The plugin is typically imported as a default export using ESM syntax within Vite configuration files. While Vite supports CJS for config, the plugin itself is likely ESM-first.
Configuring the plugin
```
plugins: [httpAuth([{ username: 'user', password: 'pass' }])]
```
The `httpAuth` function is called directly within the `plugins` array in `vite.config.ts`/`vite.config.js`.
Types
```
import type { UserCredentials, AuthOptions } from 'vite-plugin-http-basic-auth';
```
While explicit type imports might not always be needed due to inference, they are available for stricter type checking when configuring credentials or options.

Quickstart

This quickstart demonstrates how to configure HTTP Basic Authentication using environment variables for a Vite project, protecting both the development and preview servers.

import { defineConfig, loadEnv } from 'vite';
import httpAuth from 'vite-plugin-http-basic-auth';

// To run this example, create a .env file:
// VITE_AUTH_USERNAME_DEV=devuser
// VITE_AUTH_PASSWORD_DEV=devpass
// VITE_AUTH_REALM=SecureDevSite

export default defineConfig(({ command, mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    plugins: [
      httpAuth([{
        username: env.VITE_AUTH_USERNAME_DEV ?? '', // Use environment variables for credentials
        password: env.VITE_AUTH_PASSWORD_DEV ?? ''
      }], {
        realm: env.VITE_AUTH_REALM ?? 'Protected Area', // Optional: customize the realm
        useInServer: true,   // Default: true, enables auth for 'npm run dev'
        useInPreview: true   // Default: true, enables auth for 'npm run preview'
      })
    ]
  };
});

view raw JSON →