vite-env-only weekly downloads statistics

vite-env-only

Vite plugins for isolating server-only and client-only code

Install

Deny Imports

Prevents specific packages and files from being included in the client or server bundle by throwing an error at build-time when a matching import would have been included.

specifiers

Matching is performed against the raw import specifier in the source code. Match patterns can be:

• String literal for exact matches • Globs via [micromatch][micromatch] • RegExps

files

Matching is performed against the resolved and normalized root-relative file path. Match patterns can be:

• String literal for exact matches • Globs via [micromatch][micromatch] • RegExps

Macros

All macros can be imported within your app code from "vite-env-only/macros".

serverOnly$

Marks an expression as server-only and replaces it with undefined on the client. Keeps the expression as-is on the server.

For example:

On the client this produces:

On the server this produces:

clientOnly$

Marks an expression as client-only and replaces it with undefined on the server. Keeps the expression as-is on the client.

For example:

On the client this produces:

On the server this produces:

Dead-code elimination

This plugin eliminates any identifiers that become unreferenced as a result of macro replacement.

For example, given the following usage of serverOnly$:

On the client this produces:

On the server this produces:

Type safety

The macro types capture the fact that values can be undefined depending on the environment.

For example:

If you want to opt out of strict type safety, you can use a [non-null assertion][ts-non-null] (!):

Why?

Vite already provides [import.meta.env.SSR][vite-env-vars] which works in a similar way to these macros in production. However, in development Vite neither replaces import.meta.env.SSR nor performs dead-code elimination as Vite considers these steps to be optimizations.

In general, its a bad idea to rely on optimizations for correctness. In contrast, these macros treat code replacement and dead-code elimination as part of their feature set.

Additionally, these macros use function calls to mark expressions as server-only or client-only. That means they can _guarantee_ that code within the function call never ends up in the wrong environment while only transforming a single AST node type: function call expressions.

import.meta.env.SSR is instead a special identifier which can show up in many different AST node types: if statements, ternaries, switch statements, etc. This makes it far more challenging to guarantee that dead-code completely eliminated.

Prior art

Thanks to these project for exploring environment isolation and conventions for transpilation:

• [esm-env][esm-env] • [Qwik][qwik] • [TanStack bling][bling]

Description from the npm listing.