# @mongez/vite
**Curated bundle of Vite plugins for SPA workflows — typed env loading, `index.html` interpolation, tsconfig path mirroring, auto-open dev server, post-build `.zip`, `.htaccess` generation, prerender routing, and production base URL — all from one plugin call.**
[](https://www.npmjs.com/package/@mongez/vite)
[](LICENSE)
[](https://bundlephobia.com/package/@mongez/vite)
[](https://www.npmjs.com/package/@mongez/vite)
---
## Why @mongez/vite?
A typical Vite SPA wants the same handful of build-time conveniences on every project: load `.env.production` for `vite build` and `.env.development` for `vite dev`, inject env values into `index.html`, mirror `tsconfig.json` paths into `resolve.alias`, open the browser on dev start, set `config.base` from a CDN env variable during build, zip the build directory for shipping, write a SPA-friendly `.htaccess`, and route crawler traffic through a prerender service — and you end up reaching for `dotenv-flow-vite` + `vite-plugin-zip` + `vite-tsconfig-paths` + a hand-rolled `transformIndexHtml` + a hand-rolled `writeBundle` every time.
`@mongez/vite` is a curated bundle of those eight Vite plugins, exposed as one default export, each independently opt-in via the options bag. Defaults are on for SPA dev (`autoOpenBrowser`, `linkTsconfigPaths`, `compressBuild`); off for SPA prod-ops (`htaccess`, `preRender`). The whole package is build-time only — no runtime code ships to the browser.
```ts
import { defineConfig } from "vite";
import mongezVite from "@mongez/vite";
export default defineConfig({
plugins: [
mongezVite({
htaccess: true,
preRender: { url: "https://render.mentoor.io" },
}),
],
});
```
---
## Features
| Plugin | What it does |
|---|---|
| **Env loading** | Picks the right `.env.` file per Vite command via `@mongez/dotenv` — `.env.production` for `vite build`, `.env.development` for `vite dev`, with `.env.shared` layered underneath. |
| **Env-in-HTML interpolation** | Replaces `__KEY__`-style tokens in every emitted `index.html` with env values via a `transformIndexHtml` hook. Delimiters are customisable. |
| **tsconfig path aliases** | Reads `compilerOptions.paths` from `tsconfig.json` and mirrors them into `resolve.alias` so `tsc` and Vite agree on module resolution. |
| **Auto-open browser** | Sets `server.open = true` during `vite dev` while respecting any explicit user setting. |
| **Production base URL** | Reads an env variable (`PUBLIC_URL` by default) during `vite build` and writes it into `config.base` so assets reference the right CDN or subpath. |
| **Build zip** | Archives the entire output directory into a single `.zip` after build via `archiver`. Sync, async, and static filename forms all supported. |
| **.htaccess generation** | Writes a SPA-friendly Apache `.htaccess` into the output directory — SPA fallback rewrites, force-HTTPS, GZIP, cache headers. Opt-in. |
| **Pre-render service** | Emits a `prerender.php` and splices a crawler-routing rewrite into the `.htaccess` so bots get server-rendered HTML while real users get the SPA. Opt-in. |
---
## Installation
```sh
npm install -D @mongez/vite
```
```sh
yarn add -D @mongez/vite
```
```sh
pnpm add -D @mongez/vite
```
`vite >= 5.0.0` is a peer dependency.
---
## Quick start
Register the plugin in `vite.config.ts`:
```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import mongezVite from "@mongez/vite";
export default defineConfig({
plugins: [
mongezVite(),
react(),
],
});
```
That's the default profile — env loading, `index.html` interpolation, tsconfig aliases, auto-open, production base URL, and build zip all on; `htaccess` and `preRender` opt-in.
Drop two `.env` files at the project root:
```bash
# .env.development
APP_NAME="My App"
APP_PORT=3000
# .env.production
APP_NAME="My App"
PUBLIC_URL=https://cdn.example.com/
```
And reference env values in `index.html` with `__KEY__` tokens:
```html
__APP_NAME__
```
What happens at each command:
- **`vite dev`** — loads `.env.development`, replaces `__APP_NAME__` with `My App`, mirrors tsconfig paths into `resolve.alias`, opens the browser at `http://localhost:5173`.
- **`vite build`** — loads `.env.production`, sets `config.base = "https://cdn.example.com/"`, replaces `__APP_NAME__`, emits `dist/build.zip` ready to ship.
For an Apache deploy with crawler prerender, add `htaccess: true` + `preRender: { url: ... }` to the plugin call and `dist/` will also include `.htaccess` and `prerender.php`. See the [Recipes](#recipes) section.
---
## Env loading
`@mongez/vite` calls `@mongez/dotenv`'s `loadEnv` from inside its `config` hook so env values are populated before any other plugin reads them. The file picked depends on the Vite command:
| Command | File search order |
|---|---|
| `vite build` | `.env.production` → `.env.build` → `.env` |
| `vite dev` (`serve`) | `.env.development` → `.env.local` → `.env` |
Whichever exists first wins. If none exist, the helper is a no-op. `.env.shared` is loaded first underneath, so common defaults live there and environment-specific files override.
### Locking a specific file (multi-stage builds)
```ts
mongezVite({ productionEnvName: "staging" });
```
During `vite build`, the plugin loads ONLY `.env.staging`. There is no fallback — if `.env.staging` is missing the loader silently does nothing. During `vite dev` the option is ignored.
```sh
STAGE=staging vite build # loads .env.staging
vite dev # loads .env.development as usual
```
### Reading typed values back
`@mongez/dotenv` coerces `"3000"` to `3000`, `"true"` to `true`, `"null"` to `null`, and leaves quoted strings as strings. Read them through `env()`:
```ts
import { env } from "@mongez/dotenv";
env("APP_PORT"); // 3000 (number)
env("DEBUG"); // true (boolean)
env("MISSING", "x"); // "x" (fallback)
```
> The loader uses `override: true`, so `process.env.APP_PORT` also exists — but Node's `process.env` setter stringifies everything, so it reads back as `"3000"`. Use `env()` if you want the typed view.
### `.env.shared` layering
`@mongez/dotenv` loads `.env.shared` first (when `loadSharedEnv: true`, the default — and `@mongez/vite` always passes it). The environment-specific file then layers on top, so common values live once in shared and per-env overrides only restate what differs.
```bash
# .env.shared
APP_NAME="My App"
APP_URL=https://example.com
# .env.production
DB_HOST=prod-db.example.com
DEBUG=false
```
After load:
- `env("APP_NAME")` → `"My App"` (from shared)
- `env("DB_HOST")` → `"prod-db.example.com"` (from production)
- `env("DEBUG")` → `false` (typed boolean, from production)
If a key appears in both, the environment-specific file wins.
### `${VAR}` interpolation between keys
Values can reference earlier keys with `${VAR}`. Useful for composed URLs:
```bash
APP_HOST=localhost
APP_PORT=3000
APP_URL=http://${APP_HOST}:${APP_PORT}
```
```ts
env("APP_URL"); // "http://localhost:3000"
```
Interpolation reads from `@mongez/dotenv`'s internal store at parse time — the referenced key must appear earlier in the same file or in `.env.shared`.
---
## Env in HTML
The plugin registers a `transformIndexHtml` hook that iterates over every key in the env store and replaces `` tokens in every emitted HTML file.
```html
__APP_NAME__
```
```bash
# .env.production
APP_NAME="My App"
APP_DEFAULT_LOCALE=en
APP_DEFAULT_DIRECTION=ltr
APP_FAV_ICON=/favicon.svg
APP_PRIMARY_COLOR=#0066ff
APP_DESCRIPTION="A web app"
```
Customise the delimiters:
```ts
mongezVite({
htmlEnvPrefix: "{{",
htmlEnvSuffix: "}}",
});
```
```html
{{APP_NAME}}
```
> **Tokens for unknown keys are left intact.** If you see `__APP_NAME__` in your shipped HTML, the env variable wasn't loaded — there is no warning.
> **Avoid `%` or `$` in URL attributes.** Vite parses `` / `