{"record":{"id":"cf66c81ad822f5da","repo":"oxc-project/oxc","slug":"next-script-s-beforeinteractive-strategy-should","errorCode":null,"errorMessage":"next/script's `beforeInteractive` strategy should not be used outside of `pages/_document.js`","messagePattern":"next/script's `beforeInteractive` strategy should not be used outside of `pages/_document\\.js`","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/nextjs/no_before_interactive_script_outside_document.rs","lineNumber":17,"sourceCode":"use oxc_ast::{\n    AstKind,\n    ast::{JSXAttributeItem, JSXAttributeName, JSXAttributeValue},\n};\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\n\nuse crate::{\n    AstNode,\n    context::LintContext,\n    rule::Rule,\n    utils::{get_next_script_import_local_name, is_document_page, is_in_app_dir},\n};\n\nfn no_before_interactive_script_outside_document_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"next/script's `beforeInteractive` strategy should not be used outside of `pages/_document.js`\")\n        .with_help(\"See https://nextjs.org/docs/messages/no-before-interactive-script-outside-document\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct NoBeforeInteractiveScriptOutsideDocument;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///\n    /// Prevents the usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.\n    /// This rule ensures that scripts with the `beforeInteractive` loading strategy are only used in the\n    /// document component where they are most effective.\n    ///\n    /// ### Why is this bad?\n    ///\n    /// The `beforeInteractive` strategy is specifically designed to load scripts before any page hydration\n    /// occurs, which is only guaranteed to work correctly when placed in `pages/_document.js`. Using it elsewhere:","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/nextjs/no_before_interactive_script_outside_document.rs#L1-L35","documentation":"Warning from oxlint rule `nextjs/no-before-interactive-script-outside-document`. `strategy=\"beforeInteractive\"` scripts must be injected into the initial HTML before hydration; in the pages router only `pages/_document.js` runs early enough to host them. Used anywhere else they break hydration or are silently degraded, so the rule reports the strategy outside `_document.js` (app-directory files are exempt).","triggerScenarios":"A `<Script>` element (local name from `next/script`) carrying `strategy=\"beforeInteractive\"` in any file other than `pages/_document.js`, while the file is not in the app directory.","commonSituations":"Moving a critical script (font loader, bot detection, A/B testing) into a page or `_app.js`; copying vendor setup code that requests earliest possible loading.","solutions":["Drop the `strategy` prop entirely: `afterInteractive` is the default and works everywhere.","If it truly must be `beforeInteractive`, move the `<Script>` into `pages/_document.js` inside `<Head>`.","In the app router, render `next/script` with the default strategy in `app/layout.tsx` instead."],"exampleFix":"// before (in pages/index.js)\n<Script src=\"/vendor.js\" strategy=\"beforeInteractive\" />\n\n// after\n<Script src=\"/vendor.js\" /> // afterInteractive is the default","handlingStrategy":"validation","validationCode":"// find beforeInteractive usages outside _document.js:\n// rg -n 'beforeInteractive' pages app components -g '!pages/_document.*'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to omitting `strategy` — `afterInteractive` covers almost every case.","Reserve `beforeInteractive` for `pages/_document.js` only; document this in the repo.","Run oxlint (nextjs plugin) in CI so a moved Script cannot keep the strategy silently."],"tags":["nextjs","next-script","pages-router","lint"],"backgroundTag":"lint-script-loading-strategy","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}