Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A global from a script tag in index.html is 'not defined' in React

Error'Widget' is not defined no-undef

Short answer

A script in index.html creates a global at runtime, but your tools do not know it exists. ESLint reports it with no-undef until you declare it as a global. If it fails at run time, the script has not run yet: check async and defer, which change when the script executes.

  • Applies to React 19, ESLint 9, Vite 7
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the check in the browser console on the loaded page. If the name exists there, only the linter is complaining. If it does not, the script has not run or failed to load.

    typeof Widget
  2. 2Match what you see, then jump to its fix

    1. 1The build or editor shows no-undef but the page works in the browserESLint does not know the script's globalFix
    2. 2typeof Widget is undefined at the moment the component runs, and defined laterThe script runs after your code, or not in the order you expectFix

What does the error look like?

  • 'Widget' is not defined no-undef

Cause 1 of 2

ESLint does not know the script's global

1Check

The no-undef rule reports any use of an undeclared variable. A script loaded in index.html is invisible to it.

npx eslint src/App.jsx

2Fix

Declare the name as a global in the file with a comment, or add it to the globals key in your ESLint configuration.

/* global Widget */
export default function App() {
  return <button onClick={() => Widget.open()}>Open</button>;
}

3Verify

Run ESLint again; the no-undef line is gone.

npx eslint src/App.jsx

Confirmed by eslint.org

Did this fix it?

Cause 2 of 2

The script runs after your code, or not in the order you expect

1Check

A script with async runs as soon as it is downloaded and its order is not guaranteed. A script with defer runs after the document is parsed, in document order. A script with neither blocks parsing and runs first.

grep -n "<script" index.html public/index.html

2Fix

Load the third-party script without async, or with defer placed before your app's own script, and read the global only inside functions that run later (such as an event handler or an effect).

<script src="https://example.com/widget.js"></script>
<script type="module" src="/src/main.jsx"></script>

3Verify

Reload the page and check typeof Widget in the console, before any click.

typeof Widget

Confirmed by developer.mozilla.org

Did this fix it?

How do I stop it coming back?

  • Declare every browser global your code uses in the ESLint config, once, instead of per file.
  • Read script globals inside event handlers or effects, never at module top level.
  • Prefer an npm package for a library when one exists, so imports replace globals.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.