nuxt-define

library1.0.0jsnpmunverified

nuxt-define is a utility package designed for Nuxt module authors to uniformly define compiler constants across all supported Nuxt builders, including Vite, Webpack, and Rspack. It abstracts away the builder-specific mechanisms for constant definition, providing a single `addDefinePlugin` function. This allows module developers to avoid adding builder-specific dev dependencies, reducing dependency noise and ensuring consistent behavior regardless of the underlying bundler chosen by the Nuxt project. The current stable version is 1.0.0, suggesting a mature initial release. As a utility, its release cadence is likely tied to Nuxt ecosystem updates or bug fixes, rather than a strict schedule. Its key differentiator is simplifying cross-builder constant definition and enabling effective dead code elimination for feature flags during the build process, leading to optimized bundles.

web-framework devops

npm install nuxt-define

package ↗

INSTALL

IMPORT

SIG · NUXT-DEFINE

nuxt-define

web-frameworkjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

addDefinePlugin

✓ import { addDefinePlugin } from 'nuxt-define'

✗ const { addDefinePlugin } = require('nuxt-define')

Primarily used within the `setup()` hook of a Nuxt module to define global compiler constants.

__MY_CONSTANT__

✓ console.log(__MY_CONSTANT__)

✗ console.log(global.__MY_CONSTANT__)

Compiler constants are globally available during build-time compilation and should be accessed directly, not via `global` or `window`.

Demonstrates how to import and use `addDefinePlugin` within a Nuxt module's setup function to define global compiler constants.

import { defineNuxtModule } from '@nuxt/kit'; import { addDefinePlugin } from 'nuxt-define'; export default defineNuxtModule({ meta: { name: 'my-feature-module', configKey: 'myFeature' }, setup(_options, _nuxt) { // Define compiler constants that will be available globally in your runtime code addDefinePlugin({ '__MY_MODULE_VERSION__': JSON.stringify('1.2.3'), '__ENABLE_ANALYTICS__': JSON.stringify(true), '__API_ENDPOINT__': JSON.stringify(process.env.API_ENDPOINT ?? 'https://api.example.com/default') }); // Example of how these constants might be used in a runtime file (e.g., src/runtime/analytics.ts) // if (__ENABLE_ANALYTICS__) { // console.log(`Analytics enabled. Module version: ${__MY_MODULE_VERSION__}`); // // initAnalytics(__API_ENDPOINT__); // } console.log('Nuxt module setup completed, constants defined.'); } });

Debug

Known issues

gotchaValues passed to `addDefinePlugin` must be stringified using `JSON.stringify()` if they are not already strings. Forgetting this can lead to syntax errors in the bundled output, as the values are directly substituted into the code.

fix

Ensure all non-string values (booleans, numbers, objects) are wrapped with `JSON.stringify()`: `JSON.stringify(true)`, `JSON.stringify('my-string')`.

affects: >=1.0.0

gotchaCompiler constants are replaced at build time, meaning they are not dynamic runtime variables. Changes to constants require a re-build. They are also subject to dead code elimination if used in conditional statements with a falsy value (e.g., `if (__FEATURE_FLAG__)`).

fix

Understand that these are compile-time transformations. Do not expect to modify them at runtime. Use `process.env` for runtime environment variables.

affects: >=1.0.0

gotchaCompiler constants are not typed by default. If using TypeScript, you may need to declare them globally to avoid 'Cannot find name '__MY_CONSTANT__'' errors in your runtime code.

fix

Add a declaration file (e.g., `src/types/globals.d.ts`) with `declare const __MY_CONSTANT__: string;` for each constant.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: __SOME_FEATURE_FLAG__ is not defined

Attempting to access a compiler constant in runtime code without it being properly defined via `addDefinePlugin` in a Nuxt module, or trying to access it in a context where the build-time replacement has not occurred.

fix

Ensure `addDefinePlugin` is called within your Nuxt module's `setup()` function and that the constant name exactly matches. Confirm the constant is used in code processed by the Nuxt build (e.g., `src/runtime/` files).

SyntaxError: Invalid or unexpected token (e.g., if (true,) { ... })

A non-string value (like a boolean or number) was passed to `addDefinePlugin` without being wrapped in `JSON.stringify()`, leading to raw value substitution that breaks JavaScript syntax.

fix

Always use `JSON.stringify()` for the constant values, even for booleans, numbers, or strings (e.g., `'__MY_FLAG__': JSON.stringify(true)`).

TS2304: Cannot find name '__MY_CONSTANT__'.

TypeScript compiler cannot resolve the globally injected compiler constant during type checking, even if it works at runtime.

fix

Create a `globals.d.ts` file in your project (e.g., `src/types/globals.d.ts`) and declare the constants: `declare const __MY_CONSTANT__: string;`.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/nuxt-define ↗