vite-plugin-tailscale

A Vite plugin that exposes your dev server through Tailscale. By default it uses Tailscale Serve (Tailnet only). Tailscale Funnel (public internet) is available but must be enabled explicitly.

The plugin only runs when the --tailscale argument is passed to the Vite dev command, so it stays out of the way during normal development.

Install

pnpm add -D vite-plugin-tailscale

Usage

Add the plugin to your Vite config:

import { defineConfig } from 'vite'
import tailscale from 'vite-plugin-tailscale'

export default defineConfig({
  plugins: [
    tailscale(),
  ],
})

Start the dev server with the --tailscale flag:

pnpm vite --tailscale

Your dev server is now reachable at https://<your-machine>.<tailnet>.ts.net from any device on your Tailnet.

Options

tailscale({
  /**
   * Exposure mode.
   * - `'serve'` (default): Tailnet only.
   * - `'funnel'`: public internet. Must be enabled explicitly.
   */
  mode: 'serve',

  /**
   * Tailscale hostname used in the printed URL.
   * When omitted, the plugin tries to auto-detect it from `tailscale status --json`.
   */
  hostname: undefined,

  /**
   * Auto-detect the Tailscale hostname.
   */
  autoDetectHostname: true,

  /**
   * Local port to expose. Defaults to the port Vite binds to.
   */
  port: undefined,

  /**
   * Tailscale HTTPS server port. Mirrors the `--https <PORT>` CLI flag so the
   * Tailnet URL becomes `https://<hostname>:<httpsPort>`.
   */
  httpsPort: undefined,

  /**
   * Disable the plugin entirely.
   */
  disabled: false,

  /**
   * CLI argument that enables Tailscale exposure.
   */
  enableArg: '--tailscale',

  /**
   * Environment variables to set once the Tailscale hostname is known.
   *
   * Each entry can be a string (env var name, defaults to the full URL)
   * or an object with `name` and `value`.
   *
   * - `value: 'url'`: full URL, e.g. `https://my-machine.tailnet-abc.ts.net:771`
   * - `value: 'host'`: hostname with optional port, e.g. `my-machine.tailnet-abc.ts.net:771`
   */
  env: undefined,

  /**
   * Run one or more hooks after Tailscale starts and its hostname is known.
   * Hooks may be async. Failures are logged without stopping the dev server.
   */
  hooks: undefined,
})

Hooks

Hooks receive the Tailscale hostname and a context containing the full URL, local port, HTTPS port, and exposure mode. For example, you can update a Convex environment variable with the exposed app URL:

import { execFileSync } from 'node:child_process'
import { defineConfig } from 'vite'
import tailscale from 'vite-plugin-tailscale'

export default defineConfig({
  plugins: [
    tailscale({
      hooks: (_hostname, { url }) => {
        execFileSync('pnpm', ['exec', 'convex', 'env', 'set', 'APP_URL', url], {
          stdio: 'inherit',
        })
      },
    }),
  ],
})

You can pass an array when multiple integrations need to run:

tailscale({
  hooks: [
    (hostname) => console.log(`Tailscale hostname: ${hostname}`),
    async (_hostname, { url }) => updateExternalService(url),
  ],
})

Funnel

To expose the dev server publicly via Tailscale Funnel:

import { defineConfig } from 'vite'
import tailscale from 'vite-plugin-tailscale'

export default defineConfig({
  plugins: [
    tailscale({ mode: 'funnel' }),
  ],
})

pnpm vite --tailscale

A warning is printed to remind you that the server is now public.

Requirements

• Tailscale must be installed, running, and logged in.
• Funnel mode requires Funnel to be enabled for your tailnet.

Publishing

Maintainer setup and tag-based release instructions are documented in PUBLISHING.md. npm publication only runs for a pushed version tag whose name exactly matches the version in package.json.

License

MIT