@vitejs/plugin-basic-ssl

@vitejs/plugin-basic-ssl is an official Vite plugin that adds HTTPS support to Vite’s dev and preview servers without requiring a trusted, manually-issued certificate. On first use it generates a self-signed RSA certificate and key pair using node-forge, caches the result on disk (inside the project’s Vite cache directory by default, or a custom certDir), and reuses it on subsequent runs until it expires.

The certificate covers localhost, 127.0.0.1, [::1], and fe80::1 by default, plus any additional domains passed via the domains option, so it works for typical local development flows including access from other devices on a LAN. Expiration is tracked via Node’s X509Certificate API (falling back to manual parsing of the nonstandard validTo string on older Node versions) and the certificate is regenerated automatically once it’s stale, controlled by the ttlDays option (30 days by default).

Because the certificate is self-signed and untrusted by browsers, visiting the dev server still shows a security warning that must be bypassed manually — this plugin trades that one-time friction for the ability to test HTTPS-only behavior (service workers, secure cookies, WebRTC, etc.) locally without configuring a real CA-issued cert. It plugs directly into Vite’s configResolved hook, setting server.https and preview.https only when they haven’t been explicitly disabled, so it composes cleanly with existing Vite HTTPS configuration.

What You Get

• Zero-config HTTPS - drop the plugin into vite.config.js and both the dev and preview servers immediately serve over HTTPS.
• Automatic certificate caching - the generated cert/key pair is written to disk (Vite’s cache dir by default) so it isn’t regenerated on every server start.
• Expiration-aware regeneration - certificates are checked against their validity window on each run and silently regenerated once expired.
• Custom domains and TTL - configurable domains, name, ttlDays, and certDir options for matching real-world hostnames or custom cache locations.
• Non-destructive integration - only sets server.https/preview.https when the user hasn’t already explicitly disabled HTTPS, so it won’t fight existing config.

Common Use Cases

• Testing HTTPS-only browser APIs locally - a developer needs to test service workers, secure cookies, or WebRTC features that require a secure context, without provisioning a real certificate.
• Cross-device LAN testing - a mobile developer wants to hit the dev server from a phone on the same network over HTTPS, adding the phone’s hostname via the domains option.
• Quick HTTPS smoke tests before deploying TLS-terminated infra - a team wants to sanity-check HTTPS-dependent redirects or headers before their production TLS termination is configured.
• Onboarding-friendly local setup - a project wants new contributors to get a working HTTPS dev environment with no manual certificate steps, just pnpm dev.

Under The Hood

Architecture The plugin is a small, single-purpose Vite plugin defined in src/index.ts: it hooks into Vite’s configResolved lifecycle to lazily generate or read a cached certificate and then assigns it to config.server.https and config.preview.https via Object.assign, preserving any existing HTTPS options the user set. Certificate generation is isolated in src/certificate.ts (a self-contained fork of the selfsigned library’s logic, using node-forge directly to keep the bundle smaller) and expiration checking is isolated in src/certificate-expiration.ts, which wraps Node’s X509Certificate with a fallback parser for the nonstandard validTo date format on older Node versions. The separation between plugin wiring, certificate creation, and expiration logic keeps each concern in its own file with a narrow, testable surface.

Tech Stack Written in TypeScript and built with unbuild, targeting Node 18/20/22+, with vite (6.x-8.x) as a peer dependency and node-forge as the sole runtime dependency for certificate generation. The package ships dual ESM/CJS builds (dist/index.mjs and dist/index.cjs) plus type declarations. Development tooling is a standard modern npm-ecosystem setup: pnpm workspaces, vitest for tests, prettier for formatting, and tsx for running release scripts.

Code Quality Test coverage is focused and pragmatic: test/test.spec.ts covers certificate creation, expiration detection under both the modern validToDate API and the legacy validTo string-parsing fallback (mocking X509Certificate getters with vitest’s vi.spyOn), and the nonstandard date parser directly. Error handling is minimal but deliberate — certificate cache reads fall back silently to regeneration on any read failure, and cache writes are fire-and-forget so a failed write never breaks the dev server. Naming and typing are consistent and the codebase is small enough that its scope stays easy to reason about.

What Makes It Unique Rather than depending on the full selfsigned npm package, the maintainers inlined and trimmed just the certificate-generation logic they needed directly from it (with attribution preserved in comments), avoiding an extra dependency and keeping the bundle lean. Combining that with automatic on-disk caching and expiration-aware regeneration means the certificate lifecycle is handled transparently — most consumers never think about it after adding the plugin once.