vite-plugin-conditional-import

0.1.7 verified Mon Apr 27 auth: no javascript

A Vite plugin for conditionally importing modules based on environment, using file naming conventions (e.g., foo.client.js, foo.server.js). Version 0.1.7 is the current release; development appears to be in early stages. It supports both static and dynamic imports, and is inspired by vite-plugin-iso-import. Unlike build-time environment variable substitution, this plugin allows tree-shaking and import splitting per environment. Requires manual setup of define and currentEnv. Limited ecosystem adoption; use with caution for production.

Common errors

error Error: The environment 'client' is not defined in the plugin options. ↓

cause Missing 'client' in `envs` array or typo in environment name.

fix

Ensure envs includes all environments used in filenames: envs: ['client', 'server'].

error [vite] Internal server error: Cannot find module './foo.client.js' ↓

cause File does not exist or path is incorrect relative to import statement.

fix

Verify the file exists at the correct path and the naming convention is strict (e.g., foo.client.js).

error TypeError: conditionalImportPlugin is not a function ↓

cause Using `require` instead of `import` (ESM-only package).

fix

Change to import conditionalImportPlugin from 'vite-plugin-conditional-import'.

Warnings

breaking Plugin may not work with SSR or Vite 5+ due to outdated internal API usage. ↓

fix Test thoroughly; consider alternatives like vite-plugin-conditional-compile.

gotcha File naming must match pattern `filename.env.js` exactly; environment names are case-sensitive. ↓

fix Ensure filename uses lowercase env strings (e.g., foo.client.js, not foo.Client.js).

gotcha The `define` block must declare the same environment variables used in source code; missing definitions cause runtime errors. ↓

fix Always pair plugin's currentEnv with corresponding define entries matching import.meta.env.* names.

deprecated No recent updates; package may be considered unmaintained. ↓

fix Monitor repository for activity; consider forking or using alternative plugins.

Install

npm install vite-plugin-conditional-import

yarn add vite-plugin-conditional-import

pnpm add vite-plugin-conditional-import

Imports

default export

wrong

const conditionalImportPlugin = require('vite-plugin-conditional-import')

correct

import conditionalImportPlugin from 'vite-plugin-conditional-import'

ESM-only; CJS require will fail. Plugin is default-exported.

conditionalImportPlugin (as type)

wrong

import { conditionalImportPlugin } from 'vite-plugin-conditional-import'

correct

import type conditionalImportPlugin from 'vite-plugin-conditional-import'

Type imports are available for TypeScript users, but the symbol is the default export, not named.

PluginOptions

wrong

import { PluginOptions } from 'vite-plugin-conditional-import'

correct

import type { PluginOptions } from 'vite-plugin-conditional-import'

Options type is named export; use type import for TypeScript.

Quickstart

Shows Vite config setup with environment variables and the plugin, enabling conditional imports based on client/server environment.

import { defineConfig } from 'vite';
import conditionalImportPlugin from 'vite-plugin-conditional-import';

const isClient = process.env.IS_CLIENT === 'true';

export default defineConfig({
  define: {
    'import.meta.env.IS_CLIENT': isClient ? 'true' : 'false',
    'import.meta.env.IS_SERVER': isClient ? 'false' : 'true',
  },
  plugins: [
    conditionalImportPlugin({
      currentEnv: isClient ? 'client' : 'server',
      envs: ['client', 'server'],
    }),
  ],
});