Ratter Vite Plugin

@ratter/vite is the Vite integration for the Ratter stack. It registers the current dev server with the Ratter engine so the local domain, port, and reverse-proxy route stay in sync while you develop.

This package depends on the Ratter engine, which is the backend service that exposes the domain management API at http://localhost:4321 by default.

What It Does

When your Vite dev server starts, the plugin:

• detects the bound development port
• resolves a domain name for the project
• creates or updates a domain in the Ratter engine
• optionally removes or disables the domain when the server shuts down
• prints a friendly local URL in the terminal

How It Works

The plugin talks to the engine over HTTP and uses the /api/domains endpoint to synchronize state.

Vite dev server
  -> @ratter/vite plugin
  -> Ratter engine API
  -> Technitium DNS + Caddy
  -> browser-friendly local domain

By default it uses:

• API URL: http://localhost:4321
• TLD: localhost
• target IP: 127.0.0.1

Installation

Install the package in a Vite project:

npm install -D @ratter/vite

You also need a running Ratter engine before the plugin can register anything.

Basic Usage

Add the plugin to your Vite config:

import { defineConfig } from 'vite';
import { ratter } from '@ratter/vite';

export default defineConfig({
  plugins: [
    ratter({
      domain: 'my-app',
      tld: 'com',
    }),
  ],
});

If domain is omitted, the plugin derives a name from the current package name.

Options

| Option | Type | Default | Purpose | | --- | --- | --- | --- | | domain | string | derived from package name | Domain label or full domain to register | | tld | string | localhost | Suffix added when domain is only a label | | type | subdomain | custom | wildcard | subdomain | Domain type sent to the engine | | targetIp | string | 127.0.0.1 | Target IP stored in the engine | | port | number | auto-detected | Port to register for the dev server | | apiUrl | string | http://localhost:4321 | Ratter engine base URL | | deleteOnExit | boolean | false | Delete the domain when Vite shuts down | | verbose | boolean | false | Print extra warnings on failures |

Example Scenarios

Register the current package name

plugins: [ratter()]

Use a custom local domain

plugins: [
  ratter({
    domain: 'dashboard.local',
    apiUrl: 'http://localhost:4321',
  }),
]

Clean up the domain when the dev server closes

plugins: [
  ratter({
    domain: 'admin.local',
    deleteOnExit: true,
  }),
]

Runtime Behavior

The plugin is intentionally lightweight and only applies during development.

• It uses apply: 'serve', so production builds are not affected.
• It only runs once the Vite HTTP server is listening.
• It queries the engine before creating a new domain, so repeated runs update the existing record instead of duplicating it.
• It deactivates or deletes the domain on shutdown depending on deleteOnExit.

Requirements

• Vite 4 or newer
• A running Ratter engine