feat(define): don't modify string literals

docs/config/shared-options.md

@@ -39,12 +39,14 @@ Define global constant replacements. Entries will be defined as globals during d
 
 - Starting from `2.0.0-beta.70`, string values will be used as raw expressions, so if defining a string constant, it needs to be explicitly quoted (e.g. with `JSON.stringify`).
 
+- Starting from `3.2.0`, defined constants within string literals and comments are ignored. For example, `process.env.NODE_ENV` is not replaced in `console.log('mode is process.env.NODE_ENV') /* process.env.NODE_ENV */`.
+
 - To be consistent with [esbuild behavior](https://esbuild.github.io/api/#define), expressions must either be a JSON object (null, boolean, number, string, array, or object) or a single identifier.
 
 - Replacements are performed only when the match isn't surrounded by other letters, numbers, `_` or `$`.
 
 ::: warning
-Because it's implemented as straightforward text replacements without any syntax analysis, we recommend using `define` for CONSTANTS only.
+Because it's implemented as straightforward text replacements without any syntax analysis (pre Vite 3.2.0), we recommend using `define` for CONSTANTS only.
 
 For example, `process.env.FOO` and `__APP_VERSION__` are good fits. But `process` or `global` should not be put into this option. Variables can be shimmed or polyfilled instead.
 :::

docs/guide/env-and-mode.md

@@ -18,9 +18,11 @@ Vite exposes env variables on the special **`import.meta.env`** object. Some bui
 
 During production, these env variables are **statically replaced**. It is therefore necessary to always reference them using the full static string. For example, dynamic key access like `import.meta.env[key]` will not work.
 
-It will also replace these strings appearing in JavaScript strings and Vue templates. This should be a rare case, but it can be unintended. You may see errors like `Missing Semicolon` or `Unexpected token` in this case, for example when `"process.env.`<wbr>`NODE_ENV"` is transformed to `""development": "`. There are ways to work around this behavior:
+Before version 3.2.0, Vite also replaces environment variables (and other [defined constants](/config/shared-options.html#define)) within string literals and comments. This could result in unintentional changes to your string literals that result in invalid JavaScript syntax, causing errors like `Missing ) after argument list`, `Missing semicolon`, or `Unexpected token`. For example, you'd see an error when `console.log("This is process.env.`<wbr>`NODE_ENV")` is transformed to `console.log("This is "development"")`.
 
-- For JavaScript strings, you can break the string up with a Unicode zero-width space, e.g. `'import.meta\u200b.env.MODE'`.
+There are ways to work around this string replacement behavior:
+
+- For JavaScript strings, you can break the string up with a Unicode zero-width space, e.g. `'import.meta\0.env.MODE'` or use string concatenation, e.g. `'import' + '.meta.env.MODE'`.
 
 - For Vue templates or other HTML that gets compiled into JavaScript strings, you can use the [`<wbr>` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr), e.g. `import.meta.<wbr>env.MODE`.
 

packages/vite/src/node/__tests__/plugins/clientInjections.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from 'vitest'
+import {
+  clientInjectionsPlugin,
+  normalizedClientEntry,
+  normalizedEnvEntry,
+  resolveInjections
+} from '../../plugins/clientInjections'
+import { resolveConfig } from '../../config'
+
+async function createClientInjectionPluginTransform({
+  build = true,
+  ssr = false,
+  id = 'foo.ts'
+} = {}) {
+  const config = await resolveConfig({}, build ? 'build' : 'serve')
+  const instance = clientInjectionsPlugin(config)
+  const transform = async (code: string) => {
+    const transform =
+      instance.transform && 'handler' in instance.transform
+        ? instance.transform.handler
+        : instance.transform
+    const result = await transform?.call({}, code, id, { ssr })
+    return result?.code || result
+  }
+  return {
+    transform,
+    injections: resolveInjections(config)
+  }
+}
+
+describe('clientInjectionsPlugin', () => {
+  test('replaces process.env.NODE_ENV for non-SSR', async () => {
+    const { transform } = await createClientInjectionPluginTransform()
+    expect(await transform('let x = process.env.NODE_ENV;')).toBe(
+      'let x = "test";'
+    )
+  })
+
+  test('replaces process.env.NODE_ENV inside template literal expressions for non-SSR', async () => {
+    const { transform } = await createClientInjectionPluginTransform()
+    expect(await transform('let x = `${process.env.NODE_ENV}`;')).toBe(
+      'let x = `${"test"}`;'
+    )
+  })
+
+  test('ignores process.env.NODE_ENV for SSR', async () => {
+    const { transform: ssrTransform } =
+      await createClientInjectionPluginTransform({
+        ssr: true
+      })
+    expect(await ssrTransform('let x = process.env.NODE_ENV;')).toBe(null)
+  })
+
+  test('ignores process.env.NODE_ENV inside string literal for non-SSR', async () => {
+    const { transform } = await createClientInjectionPluginTransform()
+    expect(await transform(`let x = 'process.env.NODE_ENV';`)).toBe(null)
+    expect(await transform('let x = "process.env.NODE_ENV";')).toBe(null)
+    expect(await transform('let x = `process.env.NODE_ENV`;')).toBe(null)
+  })
+
+  test('ignores process.env.NODE_ENV inside string literal for SSR', async () => {
+    const { transform: ssrTransform } =
+      await createClientInjectionPluginTransform({
+        ssr: true
+      })
+    expect(await ssrTransform(`let x = 'process.env.NODE_ENV';`)).toBe(null)
+    expect(await ssrTransform('let x = "process.env.NODE_ENV";')).toBe(null)
+    expect(await ssrTransform('let x = `process.env.NODE_ENV`;')).toBe(null)
+  })
+
+  test('replaces code injections for client entry', async () => {
+    const { injections, transform } =
+      await createClientInjectionPluginTransform({
+        id: normalizedClientEntry
+      })
+    test.each(Object.keys(injections))('replaces %s', async (key) => {
+      expect(await transform(key)).toBe(injections[key])
+    })
+  })
+
+  test('replaces code injections for env entry', async () => {
+    const { injections, transform } =
+      await createClientInjectionPluginTransform({
+        id: normalizedEnvEntry
+      })
+    test.each(Object.keys(injections))('replaces %s', async (key) => {
+      expect(await transform(key)).toBe(injections[key])
+    })
+  })
+
+  test('ignores code injections for non entry files', async () => {
+    const { injections, transform } =
+      await createClientInjectionPluginTransform()
+    test.each(Object.keys(injections))('replaces %s', async (key) => {
+      expect(await transform(key)).toBe(null)
+    })
+  })
+})

packages/vite/src/node/__tests__/plugins/define.spec.ts

@@ -10,7 +10,11 @@ async function createDefinePluginTransform(
   const config = await resolveConfig({ define }, build ? 'build' : 'serve')
   const instance = definePlugin(config)
   return async (code: string) => {
-    const result = await instance.transform.call({}, code, 'foo.ts', { ssr })
+    const transform =
+      instance.transform && 'handler' in instance.transform
+        ? instance.transform.handler
+        : instance.transform
+    const result = await transform?.call({}, code, 'foo.ts', { ssr })
     return result?.code || result
   }
 }
@@ -37,4 +41,114 @@ describe('definePlugin', () => {
       'const isSSR = false;'
     )
   })
+
+  // Specially defined constants found in packages/vite/src/node/plugins/define.ts
+  const specialDefines = {
+    'process.env.': '({}).',
+    'global.process.env.': '({}).',
+    'globalThis.process.env.': '({}).',
+    'process.env.NODE_ENV': '"test"',
+    'global.process.env.NODE_ENV': '"test"',
+    'globalThis.process.env.NODE_ENV': '"test"',
+    __vite_process_env_NODE_ENV: '"test"',
+    'import.meta.env.': '({}).',
+    'import.meta.env':
+      '{"BASE_URL":"/","MODE":"development","DEV":true,"PROD":false}',
+    'import.meta.hot': 'false'
+  }
+  const specialDefineKeys = Object.keys(specialDefines)
+
+  const specialDefinesSSR = {
+    ...specialDefines,
+    // process.env is not replaced in SSR
+    'process.env.': null,
+    'global.process.env.': null,
+    'globalThis.process.env.': null,
+    'process.env.NODE_ENV': null,
+    'global.process.env.NODE_ENV': null,
+    'globalThis.process.env.NODE_ENV': null,
+    // __vite_process_env_NODE_ENV is a special variable that resolves to process.env.NODE_ENV, which is not replaced in SSR
+    __vite_process_env_NODE_ENV: 'process.env.NODE_ENV'
+  }
+
+  describe('ignores defined constants in string literals', async () => {
+    const singleQuotedDefines = specialDefineKeys
+      .map((define) => `let x = '${define}'`)
+      .join(';\n')
+    const doubleQuotedDefines = specialDefineKeys
+      .map((define) => `let x = "${define}"`)
+      .join(';\n')
+    const backtickedDefines = specialDefineKeys
+      .map((define) => `let x = \`${define}\``)
+      .join(';\n')
+    const singleQuotedDefinesMultilineNested = specialDefineKeys
+      .map((define) => `let x = \`\n'${define}'\n\``)
+      .join(';\n')
+    const doubleQuotedDefinesMultilineNested = specialDefineKeys
+      .map((define) => `let x = \`\n"${define}"\n\``)
+      .join(';\n')
+
+    const inputs = [
+      ['double-quoted', doubleQuotedDefines],
+      ['single-quoted', singleQuotedDefines],
+      ['backticked', backtickedDefines],
+      ['multiline nested double-quoted', doubleQuotedDefinesMultilineNested],
+      ['multiline nested single-quoted', singleQuotedDefinesMultilineNested]
+    ]
+
+    describe('non-SSR', async () => {
+      const transform = await createDefinePluginTransform()
+      test.each(inputs)('%s', async (label, input) => {
+        // transform() returns null when no replacement is made
+        expect(await transform(input)).toBe(null)
+      })
+    })
+
+    describe('SSR', async () => {
+      const ssrTransform = await createDefinePluginTransform({}, true, true)
+      test.each(inputs)('%s', async (label, input) => {
+        // transform() returns null when no replacement is made
+        expect(await ssrTransform(input)).toBe(null)
+      })
+    })
+  })
+
+  describe('replaces defined constants in template literal expressions', async () => {
+    describe('non-SSR', async () => {
+      const transform = await createDefinePluginTransform()
+
+      test.each(specialDefineKeys)('%s', async (key) => {
+        const result = await transform('let x = `${' + key + '}`')
+        expect(result).toBe('let x = `${' + specialDefines[key] + '}`')
+      })
+
+      // multiline tests
+      test.each(specialDefineKeys)('%s', async (key) => {
+        const result = await transform('let x = `\n${' + key + '}\n`')
+        expect(result).toBe('let x = `\n${' + specialDefines[key] + '}\n`')
+      })
+    })
+    describe('SSR', async () => {
+      const ssrTransform = await createDefinePluginTransform({}, true, true)
+
+      test.each(specialDefineKeys)('%s', async (key) => {
+        const result = await ssrTransform('let x = `${' + key + '}`')
+        expect(result).toBe(
+          specialDefinesSSR[key]
+            ? 'let x = `${' + specialDefinesSSR[key] + '}`'
+            : null
+        )
+      })
+
+      // multiline tests
+      test.each(specialDefineKeys)('%s', async (key) => {
+        const result = await ssrTransform('let x = `\n${' + key + '}\n`')
+        expect(result).toBe(
+          specialDefinesSSR[key]
+            ? 'let x = `\n${' + specialDefinesSSR[key] + '}\n`'
+            : null
+        )
+      })
+    })
+  })
 })

packages/vite/src/node/__tests__/plugins/importGlob/__snapshots__/fixture.test.ts.snap

@@ -13,7 +13,7 @@ export const excludeSelf = /* #__PURE__ */ Object.assign({\\"./sibling.ts\\": ()
 export const customQueryString = /* #__PURE__ */ Object.assign({\\"./sibling.ts\\": () => import(\\"./sibling.ts?custom\\")});
 export const customQueryObject = /* #__PURE__ */ Object.assign({\\"./sibling.ts\\": () => import(\\"./sibling.ts?foo=bar&raw=true\\")});
 export const parent = /* #__PURE__ */ Object.assign({});
-export const rootMixedRelative = /* #__PURE__ */ Object.assign({\\"/css.spec.ts\\": () => import(\\"../../css.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/define.spec.ts\\": () => import(\\"../../define.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/esbuild.spec.ts\\": () => import(\\"../../esbuild.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/import.spec.ts\\": () => import(\\"../../import.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/a.ts\\": () => import(\\"../fixture-b/a.ts?url\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/b.ts\\": () => import(\\"../fixture-b/b.ts?url\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/index.ts\\": () => import(\\"../fixture-b/index.ts?url\\").then(m => m[\\"default\\"])});
+export const rootMixedRelative = /* #__PURE__ */ Object.assign({\\"/clientInjections.spec.ts\\": () => import(\\"../../clientInjections.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/css.spec.ts\\": () => import(\\"../../css.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/define.spec.ts\\": () => import(\\"../../define.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/esbuild.spec.ts\\": () => import(\\"../../esbuild.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/import.spec.ts\\": () => import(\\"../../import.spec.ts?url\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/a.ts\\": () => import(\\"../fixture-b/a.ts?url\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/b.ts\\": () => import(\\"../fixture-b/b.ts?url\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/index.ts\\": () => import(\\"../fixture-b/index.ts?url\\").then(m => m[\\"default\\"])});
 export const cleverCwd1 = /* #__PURE__ */ Object.assign({\\"./node_modules/framework/pages/hello.page.js\\": () => import(\\"./node_modules/framework/pages/hello.page.js\\")});
 export const cleverCwd2 = /* #__PURE__ */ Object.assign({\\"./modules/a.ts\\": () => import(\\"./modules/a.ts\\"),\\"./modules/b.ts\\": () => import(\\"./modules/b.ts\\"),\\"../fixture-b/a.ts\\": () => import(\\"../fixture-b/a.ts\\"),\\"../fixture-b/b.ts\\": () => import(\\"../fixture-b/b.ts\\")});
 "
@@ -32,7 +32,7 @@ export const excludeSelf = /* #__PURE__ */ Object.assign({\\"./sibling.ts\\": ()
 export const customQueryString = /* #__PURE__ */ Object.assign({\\"./sibling.ts\\": () => import(\\"./sibling.ts?custom&lang.ts\\")});
 export const customQueryObject = /* #__PURE__ */ Object.assign({\\"./sibling.ts\\": () => import(\\"./sibling.ts?foo=bar&raw=true&lang.ts\\")});
 export const parent = /* #__PURE__ */ Object.assign({});
-export const rootMixedRelative = /* #__PURE__ */ Object.assign({\\"/css.spec.ts\\": () => import(\\"../../css.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/define.spec.ts\\": () => import(\\"../../define.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/esbuild.spec.ts\\": () => import(\\"../../esbuild.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/import.spec.ts\\": () => import(\\"../../import.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/a.ts\\": () => import(\\"../fixture-b/a.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/b.ts\\": () => import(\\"../fixture-b/b.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/index.ts\\": () => import(\\"../fixture-b/index.ts?url&lang.ts\\").then(m => m[\\"default\\"])});
+export const rootMixedRelative = /* #__PURE__ */ Object.assign({\\"/clientInjections.spec.ts\\": () => import(\\"../../clientInjections.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/css.spec.ts\\": () => import(\\"../../css.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/define.spec.ts\\": () => import(\\"../../define.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/esbuild.spec.ts\\": () => import(\\"../../esbuild.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/import.spec.ts\\": () => import(\\"../../import.spec.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/a.ts\\": () => import(\\"../fixture-b/a.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/b.ts\\": () => import(\\"../fixture-b/b.ts?url&lang.ts\\").then(m => m[\\"default\\"]),\\"/importGlob/fixture-b/index.ts\\": () => import(\\"../fixture-b/index.ts?url&lang.ts\\").then(m => m[\\"default\\"])});
 export const cleverCwd1 = /* #__PURE__ */ Object.assign({\\"./node_modules/framework/pages/hello.page.js\\": () => import(\\"./node_modules/framework/pages/hello.page.js\\")});
 export const cleverCwd2 = /* #__PURE__ */ Object.assign({\\"./modules/a.ts\\": () => import(\\"./modules/a.ts\\"),\\"./modules/b.ts\\": () => import(\\"./modules/b.ts\\"),\\"../fixture-b/a.ts\\": () => import(\\"../fixture-b/a.ts\\"),\\"../fixture-b/b.ts\\": () => import(\\"../fixture-b/b.ts\\")});
 "

packages/vite/src/node/__tests__/utils.spec.ts

@@ -7,6 +7,7 @@ import {
   injectQuery,
   isWindows,
   posToNumber,
+  replaceInCode,
   resolveHostname
 } from '../utils'
 
@@ -236,3 +237,36 @@ describe('asyncFlatten', () => {
     expect(arr).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9])
   })
 })
+
+describe('replaceInCode', () => {
+  test('replaces pattern with string', () => {
+    expect(replaceInCode('let a1 = 1;', /\d/g, 'b')?.toString()).toBe(
+      'let ab = b;'
+    )
+  })
+
+  test('replaces pattern with replacement object', () => {
+    expect(
+      replaceInCode('let a1 = 2;', /\d/g, {
+        '1': 'b',
+        '2': 'c'
+      })?.toString()
+    ).toBe('let ab = c;')
+  })
+
+  test('returns null if no replacement', () => {
+    expect(replaceInCode('let a = b;', /\d/g, {})).toBe(null)
+  })
+
+  test('ignores string literals', () => {
+    expect(replaceInCode('let a1 = "1";', /\d/g, 'b')?.toString()).toBe(
+      'let ab = "1";'
+    )
+  })
+
+  test('ignores comments', () => {
+    expect(
+      replaceInCode('let a /* 1 */ = 1; // 1', /\d/g, 'b')?.toString()
+    ).toBe('let a /* 1 */ = b; // 1')
+  })
+})