What causes "Do not include stylesheets manually." in oxc-project/oxc?

Import the stylesheet instead: `import './styles.css'` in `pages/_app.js` (pages router) or the consuming layout/component (app router).

oxc-project/oxc · warning · OxcDiagnostic

Do not include stylesheets manually.

Error message

Do not include stylesheets manually.

What it means

Warning from oxlint rule `nextjs/no-css-tags`. Manually adding `<link rel="stylesheet">` for a local CSS file bypasses the Next.js stylesheet pipeline (bundling, code-splitting, deduplication), which causes unstyled flashes and duplicated CSS. The rule flags link tags pointing at a project-local stylesheet rather than an external URL.

Source

Thrown at crates/oxc_linter/src/rules/nextjs/no_css_tags.rs:12

use oxc_ast::{
    AstKind,
    ast::{JSXAttributeItem, JSXAttributeName, JSXElementName},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{AstNode, context::LintContext, rule::Rule, utils::get_string_literal_prop_value};

fn no_css_tags_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Do not include stylesheets manually.")
        .with_help("See https://nextjs.org/docs/messages/no-css-tags")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct NoCssTags;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Prevents manual inclusion of stylesheets using `<link>` tags in Next.js applications.
    /// This rule checks for `<link>` tags with `rel="stylesheet"` that reference local CSS files.
    ///
    /// ### Why is this bad?
    ///
    /// Next.js handles CSS imports automatically through its built-in CSS support.
    /// Manual stylesheet inclusion bypasses Next.js's built-in CSS optimization,
    /// prevents proper code splitting and optimization of styles, and may cause

View on GitHub (pinned to e1e7af627c)

Solutions

Import the stylesheet instead: `import './styles.css'` in `pages/_app.js` (pages router) or the consuming layout/component (app router).
For third-party CSS keep `href` as a full `https://` URL; external links are not flagged.
For global styles, import the CSS once in the root layout.

Example fix

// before
<link rel="stylesheet" href="/styles/globals.css" />

// after (top of pages/_app.tsx)
import '../styles/globals.css';

Defensive patterns

Strategy: validation

Validate before calling

// find local stylesheet link tags:
// rg -n '<link[^>]*rel="stylesheet"[^>]*href="(?![a-z]+://)' --pcre2 -g '*.tsx' src

Prevention

Import CSS files in `_app.js` / root layout; never link them from markup.
Keep full `https://` URLs on genuinely external CDN stylesheets so tooling can distinguish them.
Gate merges on an oxlint run with the nextjs plugin enabled.

When it happens

Trigger: JSX `<link>` with `rel="stylesheet"` whose `href` is a string literal referencing a local CSS path (not an absolute http(s) URL), rendered in any page or component.

Common situations: Porting a static site's `<head>` links into components; adding a downloaded template's css link per page. Full `https://` CDN links are the common false-positive escape and are allowed.

Related errors

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/2bd84ffe1528f2a5. Report an issue: GitHub.