{"record":{"id":"6595961c83510db5","repo":"facebook/react","slug":"react-refresh-babel-transform-should-only-be-enabl","errorCode":null,"errorMessage":"React Refresh Babel transform should only be enabled in development environment. Instead, the environment is: \"${env}\". If you want to override this check, pass {skipEnvCheck: true} as plugin options.","messagePattern":"React Refresh Babel transform should only be enabled in development environment\\. Instead, the environment is: \"(.+?)\"\\. If you want to override this check, pass (.+?) as plugin options\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/react-refresh/src/ReactFreshBabelPlugin.js","lineNumber":15,"sourceCode":"/**\n * Copyright (c) Meta Platforms, Inc. and affiliates.\n *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\n\n'use strict';\n\nexport default function (babel, opts = {}) {\n  if (typeof babel.env === 'function') {\n    // Only available in Babel 7.\n    const env = babel.env();\n    if (env !== 'development' && !opts.skipEnvCheck) {\n      throw new Error(\n        'React Refresh Babel transform should only be enabled in development environment. ' +\n          'Instead, the environment is: \"' +\n          env +\n          '\". If you want to override this check, pass {skipEnvCheck: true} as plugin options.',\n      );\n    }\n  }\n\n  const {types: t} = babel;\n  const refreshReg = t.identifier(opts.refreshReg || '$RefreshReg$');\n  const refreshSig = t.identifier(opts.refreshSig || '$RefreshSig$');\n\n  const registrationsByProgramPath = new Map();\n  function createRegistration(programPath, persistentID) {\n    const handle = programPath.scope.generateUidIdentifier('c');\n    if (!registrationsByProgramPath.has(programPath)) {\n      registrationsByProgramPath.set(programPath, []);\n    }","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react-refresh/src/ReactFreshBabelPlugin.js#L1-L33","documentation":"The react-refresh Babel plugin (ReactFreshBabelPlugin) refuses to run outside a development environment: if babel.env() returns anything other than 'development' and the plugin options do not include skipEnvCheck: true, it throws at build start. The check exists because the transform emits $RefreshReg$/$RefreshSig$ registration calls — development-only instrumentation that must never reach a production or test bundle.","triggerScenarios":"Listing 'react-refresh/babel' unconditionally in babel.config.js/.babelrc while BABEL_ENV or NODE_ENV resolves to 'production' or 'test'; a Metro or webpack production build inheriting the dev babel config unchanged; CI pipelines that reuse the dev babel config with NODE_ENV=test.","commonSituations":"One shared babel config for dev and prod (ejected CRA, custom webpack setups); manually adding Fast Refresh instead of using @pmmmwh/react-refresh-webpack-plugin; test runners that set BABEL_ENV=test and pull the plugin in through a preset chain.","solutions":["Make the babel config a function and include 'react-refresh/babel' only when the env is development (api.env() === 'development' or process.env.NODE_ENV === 'development')","With webpack, use @pmmmwh/react-refresh-webpack-plugin, which injects the Babel plugin only for mode: 'development'","If you deliberately run the transform under a non-'development' env name (e.g. BABEL_ENV=test to compile a dev-mode playground), pass options: {skipEnvCheck: true}"],"exampleFix":"// before (.babelrc)\n{ \"plugins\": [\"react-refresh/babel\"] }\n\n// after (babel.config.js)\nmodule.exports = function (api) {\n  api.cache.using(() => process.env.NODE_ENV);\n  return {\n    plugins: [\n      ...(process.env.NODE_ENV === 'development' ? ['react-refresh/babel'] : []),\n    ],\n  };\n};","handlingStrategy":"validation","validationCode":"// babel.config.js\nmodule.exports = function (api) {\n  api.cache.using(() => process.env.NODE_ENV);\n  const isDev = process.env.NODE_ENV === 'development';\n  return {plugins: [...(isDev ? ['react-refresh/babel'] : [])]};\n};","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never list 'react-refresh/babel' unconditionally in a static config shared across environments","Let @pmmmwh/react-refresh-webpack-plugin inject the plugin so it follows webpack mode","Set NODE_ENV/BABEL_ENV explicitly in every build script so env checks are meaningful"],"tags":["babel","react-refresh","fast-refresh","build-config","environment"],"backgroundTag":"dev-only-plugin-in-production","analyzedSha":"eafeac097ba51e1eab809c07102126bd5f8e5425","analyzedAt":"2026-08-21T22:01:08.818Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}