Registry / devops / vite-env-only

vite-env-only

JSON →
library3.0.3jsnpmunverified

vite-env-only is a suite of Vite plugins designed to facilitate the isolation of client-side and server-side code within a single codebase. It provides two primary functionalities: `denyImports` to prevent specific modules or files from being bundled into client or server builds, and `envOnlyMacros` (`serverOnly$`, `clientOnly$`) to conditionally include or exclude expressions based on the target environment. The current stable version is 3.0.3, with a release cadence that includes regular patch updates for improved dead code elimination and occasional minor/major releases for new features or architectural changes. A key differentiator from Vite's native `import.meta.env.SSR` is its ability to perform dead-code elimination in development builds, not just production, leading to more accurate environment simulation and smaller bundles during development.

npm install vite-env-only
INSTALL
IMPORT
SIG · VITE-ENV-ONLY
V
vite-env-only
devopsjavascriptv3.0.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

denyImports
import { denyImports } from 'vite-env-only'
import denyImports from 'vite-env-only'
Since v3.0.0, the default export was removed; `denyImports` is a named export.
envOnlyMacros
import { envOnlyMacros } from 'vite-env-only'
import envOnlyMacros from 'vite-env-only'
Since v3.0.0, the default export was removed; `envOnlyMacros` is a named export.
serverOnly$
import { serverOnly$ } from 'vite-env-only/macros'
import { serverOnly$ } from 'vite-env-only'
Since v3.0.0, macros like `serverOnly$` and `clientOnly$` are imported from the dedicated `vite-env-only/macros` entry point.
clientOnly$
import { clientOnly$ } from 'vite-env-only/macros'
const { clientOnly$ } = require('vite-env-only/macros')
This library is primarily designed for ESM environments, as is common with Vite. CommonJS `require` is not officially supported for macros and may lead to issues.

Demonstrates how to configure both `denyImports` and `envOnlyMacros` in `vite.config.ts`, along with basic usage of `serverOnly$` and `clientOnly$` macros in application code, highlighting type safety.

import { defineConfig } from 'vite'; import { denyImports, envOnlyMacros } from 'vite-env-only'; import { serverOnly$, clientOnly$ } from 'vite-env-only/macros'; export default defineConfig({ plugins: [ denyImports({ client: { specifiers: ['fs-extra', /^node:/, '@prisma/*'], files: ['**/.server/*', '**/*.server.*'], }, server: { specifiers: ['jquery'], }, }), envOnlyMacros() ], }); // Example usage in your application code (e.g., src/main.ts or a component) // This will be 'i only exist on the server' on the server, undefined on the client export const serverMessage = serverOnly$('i only exist on the server'); // This will be 'i only exist on the client' on the client, undefined on the server export const clientMessage = clientOnly$('i only exist on the client'); // Type-safe usage demonstrating potential undefined export const API_KEY = serverOnly$(process.env.VITE_SERVER_API_KEY ?? ''); // ^? string | undefined if (serverMessage !== undefined) { console.log('Server-side message:', serverMessage); } if (clientMessage !== undefined) { console.log('Client-side message:', clientMessage); } // To make sure environment variables are passed to the server-side code // you might need to set them in your .env file with or without VITE_ prefix // depending on how you intend to use them (client/server in Vite config). // For this example, VITE_SERVER_API_KEY would usually be processed by the build tool // to ensure it's available only where needed, or directly accessed via process.env // in Node.js contexts.
Debug
Known issues
breakingWith the release of v3.0.0, the package underwent a significant refactor. The default export was removed, and the primary plugins `envOnlyMacros` and `denyImports` are now named exports.
fix
Update your `vite.config.ts` imports from `import plugin from 'vite-env-only'` to `import { envOnlyMacros, denyImports } from 'vite-env-only'`.
affects: >=3.0.0
breakingAs part of the v3.0.0 refactor, the environment macros (`serverOnly$`, `clientOnly$`) were moved to a dedicated subpath import `vite-env-only/macros`.
fix
Change your application code imports for macros from `import { serverOnly$ } from 'vite-env-only'` to `import { serverOnly$ } from 'vite-env-only/macros'`.
affects: >=3.0.0
gotchaMacros like `serverOnly$` and `clientOnly$` replace expressions with `undefined` in the environments where they are eliminated. This means the return type of a macro call is `T | undefined` (where T is the type of the expression).
fix
Account for `undefined` in your TypeScript code using type narrowing (`if (value !== undefined)`) or non-null assertions (`value!`) if you are certain it will be present in the target environment.
affects: >=2.0.0
gotchaOlder versions of `vite-env-only` (prior to v2.4.0) did not support glob patterns for `denyImports` `specifiers` or `files` options. Only exact string or RegExp matches were supported.
fix
Upgrade to `vite-env-only@2.4.0` or newer to utilize glob pattern matching for import denial rules.
affects: <2.4.0
Errors
Common errors & fixes
TypeError: (0 , vite_env_only__WEBPACK_IMPORTED_MODULE_0__.default) is not a function
Attempting to use the default export of `vite-env-only` after version 3.0.0, where it was removed.
fix
Change your `vite.config.ts` import from `import plugin from 'vite-env-only'` to named imports like `import { envOnlyMacros } from 'vite-env-only'`.
ReferenceError: serverOnly$ is not defined
Incorrect import path for environment macros; they were moved to a subpath in v3.0.0.
fix
Ensure you are importing macros from the correct path: `import { serverOnly$ } from 'vite-env-only/macros'`.
Error: [vite-env-only] Import of 'fs' is denied in the client build.
A module or file that matches a `denyImports` rule for the current build environment (e.g., client or server) was detected in the bundle.
fix
Refactor your code to ensure that modules/files explicitly denied for a specific environment are not imported or referenced in that environment's code path. Use macros like `serverOnly$` or `clientOnly$` to conditionally exclude code.
Upgrade
Version history
3.0.3latest on npm
Audit
Dependencies
viterequiredPeer dependency as it's a Vite plugin. Requires Vite >= 2.3.0.
Agent activity
2 hits · last 30 days
node
2
Resources
vite-env-only — npm install vite-env-only · libregistry