{"id":14235,"library":"vite-env-only","title":"Vite Environment Code Isolation","description":"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.","status":"active","version":"3.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/pcattori/vite-env-only","tags":["javascript","vite-plugin","env","only","client","server","macro","deny","imports"],"install":[{"cmd":"npm install vite-env-only","lang":"bash","label":"npm"},{"cmd":"yarn add vite-env-only","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-env-only","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as it's a Vite plugin. Requires Vite >= 2.3.0.","package":"vite","optional":false}],"imports":[{"note":"Since v3.0.0, the default export was removed; `denyImports` is a named export.","wrong":"import denyImports from 'vite-env-only'","symbol":"denyImports","correct":"import { denyImports } from 'vite-env-only'"},{"note":"Since v3.0.0, the default export was removed; `envOnlyMacros` is a named export.","wrong":"import envOnlyMacros from 'vite-env-only'","symbol":"envOnlyMacros","correct":"import { envOnlyMacros } from 'vite-env-only'"},{"note":"Since v3.0.0, macros like `serverOnly$` and `clientOnly$` are imported from the dedicated `vite-env-only/macros` entry point.","wrong":"import { serverOnly$ } from 'vite-env-only'","symbol":"serverOnly$","correct":"import { serverOnly$ } from 'vite-env-only/macros'"},{"note":"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.","wrong":"const { clientOnly$ } = require('vite-env-only/macros')","symbol":"clientOnly$","correct":"import { clientOnly$ } from 'vite-env-only/macros'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport { denyImports, envOnlyMacros } from 'vite-env-only';\nimport { serverOnly$, clientOnly$ } from 'vite-env-only/macros';\n\nexport default defineConfig({\n  plugins: [\n    denyImports({\n      client: {\n        specifiers: ['fs-extra', /^node:/, '@prisma/*'],\n        files: ['**/.server/*', '**/*.server.*'],\n      },\n      server: {\n        specifiers: ['jquery'],\n      },\n    }),\n    envOnlyMacros()\n  ],\n});\n\n// Example usage in your application code (e.g., src/main.ts or a component)\n\n// This will be 'i only exist on the server' on the server, undefined on the client\nexport const serverMessage = serverOnly$('i only exist on the server');\n\n// This will be 'i only exist on the client' on the client, undefined on the server\nexport const clientMessage = clientOnly$('i only exist on the client');\n\n// Type-safe usage demonstrating potential undefined\nexport const API_KEY = serverOnly$(process.env.VITE_SERVER_API_KEY ?? '');\n//    ^? string | undefined\n\nif (serverMessage !== undefined) {\n  console.log('Server-side message:', serverMessage);\n}\n\nif (clientMessage !== undefined) {\n  console.log('Client-side message:', clientMessage);\n}\n\n// To make sure environment variables are passed to the server-side code\n// you might need to set them in your .env file with or without VITE_ prefix\n// depending on how you intend to use them (client/server in Vite config).\n// For this example, VITE_SERVER_API_KEY would usually be processed by the build tool\n// to ensure it's available only where needed, or directly accessed via process.env\n// in Node.js contexts.","lang":"typescript","description":"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."},"warnings":[{"fix":"Update your `vite.config.ts` imports from `import plugin from 'vite-env-only'` to `import { envOnlyMacros, denyImports } from 'vite-env-only'`.","message":"With 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Change your application code imports for macros from `import { serverOnly$ } from 'vite-env-only'` to `import { serverOnly$ } from 'vite-env-only/macros'`.","message":"As part of the v3.0.0 refactor, the environment macros (`serverOnly$`, `clientOnly$`) were moved to a dedicated subpath import `vite-env-only/macros`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Macros 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).","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to `vite-env-only@2.4.0` or newer to utilize glob pattern matching for import denial rules.","message":"Older 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.","severity":"gotcha","affected_versions":"<2.4.0"}],"env_vars":null,"search_vec":"'3.0.3':73 'abil':108 'accur':124 'architectur':96 'base':63 'build':52,117 'bundl':47,129 'cadenc':77 'chang':97 'client':22,49,138 'client-sid':21 'clienton':56 'code':3,28,86,113 'codebas':32 'condit':58 'current':69 'dead':85,112 'dead-cod':111 'deni':141 'denyimport':38 'design':15 'develop':116,131 'differenti':100 'elimin':87,114 'env':7,136 'environ':2,67,125 'envonlymacro':54 'exclud':61 'express':62 'facilit':17 'featur':94 'file':44 'function':37 'import':142 'import.meta.env.ssr':105 'improv':84 'includ':59,79 'isol':4,19 'javascript':132 'key':99 'lead':121 'macro':140 'minor/major':90 'modul':42 'nativ':104 'new':93 'occasion':89 'patch':81 'perform':110 'plugin':14,135 'prevent':40 'primari':36 'product':120 'provid':34 'regular':80 'releas':76,91 'server':26,51,139 'server-sid':25 'serveron':55 'side':23,27 'simul':126 'singl':31 'smaller':128 'specif':41 'stabl':70 'suit':11 'target':66 'two':35 'updat':82 'version':71 'vite':1,6,13,102,134 'vite-env-on':5 'vite-plugin':133 'within':29","created_at":"2026-04-20T01:58:38.677772+00:00","updated_at":"2026-04-20T01:58:38.677772+00:00","problems":[{"fix":"Change your `vite.config.ts` import from `import plugin from 'vite-env-only'` to named imports like `import { envOnlyMacros } from 'vite-env-only'`.","cause":"Attempting to use the default export of `vite-env-only` after version 3.0.0, where it was removed.","error":"TypeError: (0 , vite_env_only__WEBPACK_IMPORTED_MODULE_0__.default) is not a function"},{"fix":"Ensure you are importing macros from the correct path: `import { serverOnly$ } from 'vite-env-only/macros'`.","cause":"Incorrect import path for environment macros; they were moved to a subpath in v3.0.0.","error":"ReferenceError: serverOnly$ is not defined"},{"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.","cause":"A module or file that matches a `denyImports` rule for the current build environment (e.g., client or server) was detected in the bundle.","error":"Error: [vite-env-only] Import of 'fs' is denied in the client build."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/pcattori/vite-env-only","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vite-env-only","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}