Módulos CSS y estilos globales

Next.js soporta diferentes tipos de hojas de estilo, incluyendo:

Módulos CSS
Estilos globales
Hojas de estilo externas

Módulos CSS

Next.js tiene soporte integrado para Módulos CSS usando la extensión .module.css.

Los Módulos CSS limitan el alcance del CSS localmente al crear automáticamente un nombre de clase único. Esto te permite usar el mismo nombre de clase en diferentes archivos sin preocuparte por colisiones. Este comportamiento hace que los Módulos CSS sean la forma ideal de incluir CSS a nivel de componente.

Ejemplo

Los Módulos CSS se pueden importar en cualquier archivo dentro del directorio app:

import styles from './styles.module.css'

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return <section className={styles.dashboard}>{children}</section>
}

import styles from './styles.module.css'

export default function DashboardLayout({ children }) {
  return <section className={styles.dashboard}>{children}</section>
}

app/dashboard/styles.module.css

.dashboard {
  padding: 24px;
}

Los Módulos CSS están habilitados solo para archivos con las extensiones .module.css y .module.sass.

En producción, todos los archivos de Módulos CSS se concatenarán automáticamente en muchos archivos .css minimizados y divididos por código. Estos archivos .css representan rutas de ejecución críticas en tu aplicación, asegurando que se cargue la cantidad mínima de CSS necesaria para que tu aplicación se renderice.

Estilos globales

Los estilos globales se pueden importar en cualquier diseño, página o componente dentro del directorio app.

Nota importante: Esto es diferente al directorio pages, donde solo puedes importar estilos globales dentro del archivo _app.js.

Por ejemplo, considera una hoja de estilo llamada app/global.css:

body {
  padding: 20px 20px 60px;
  max-width: 680px;
  margin: 0 auto;
}

Dentro del diseño raíz (app/layout.js), importa la hoja de estilo global.css para aplicar los estilos a cada ruta en tu aplicación:

// Estos estilos aplican a cada ruta en la aplicación
import './global.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

// Estos estilos aplican a cada ruta en la aplicación
import './global.css'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

Hojas de estilo externas

Las hojas de estilo publicadas por paquetes externos se pueden importar en cualquier parte del directorio app, incluyendo componentes colocalizados:

import 'bootstrap/dist/css/bootstrap.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className="container">{children}</body>
    </html>
  )
}

import 'bootstrap/dist/css/bootstrap.css'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className="container">{children}</body>
    </html>
  )
}

Nota importante: Las hojas de estilo externas deben importarse directamente desde un paquete npm o descargarse y colocarse junto con tu código base. No puedes usar <link rel="stylesheet" />.

Orden y fusión

Next.js optimiza el CSS durante las compilaciones de producción al agrupar (fusionar) automáticamente las hojas de estilo. El orden del CSS está determinado por el orden en que importas las hojas de estilo en el código de tu aplicación.

Por ejemplo, base-button.module.css se ordenará antes que page.module.css ya que <BaseButton> se importa primero en <Page>:

import styles from './base-button.module.css'

export function BaseButton() {
  return <button className={styles.primary} />
}

import styles from './base-button.module.css'

export function BaseButton() {
  return <button className={styles.primary} />
}

import { BaseButton } from './base-button'
import styles from './page.module.css'

export function Page() {
  return <BaseButton className={styles.primary} />
}

import { BaseButton } from './base-button'
import styles from './page.module.css'

export function Page() {
  return <BaseButton className={styles.primary} />
}

Para mantener un orden predecible, recomendamos lo siguiente:

Importa un archivo CSS solo en un único archivo JS/TS.
- Si usas nombres de clase globales, importa los estilos globales en el mismo archivo en el orden que deseas que se apliquen.
Prefiere Módulos CSS sobre estilos globales.
- Usa una convención de nombres consistente para tus Módulos CSS. Por ejemplo, usa <name>.module.css en lugar de <name>.tsx.
Extrae estilos compartidos en un componente separado.
Si usas Tailwind, importa la hoja de estilo al principio del archivo, preferiblemente en el Diseño Raíz.

Nota importante: El orden del CSS se comporta diferente en modo desarrollo, siempre verifica las implementaciones de vista previa para confirmar el orden final del CSS en tu compilación de producción.

Características adicionales

Next.js incluye características adicionales para mejorar la experiencia de agregar estilos:

Cuando ejecutas localmente con next dev, las hojas de estilo locales (ya sean globales o Módulos CSS) aprovecharán Fast Refresh para reflejar cambios instantáneamente mientras guardas ediciones.
Al compilar para producción con next build, los archivos CSS se agruparán en menos archivos .css minimizados para reducir el número de solicitudes de red necesarias para recuperar estilos.
Si desactivas JavaScript, los estilos aún se cargarán en la compilación de producción (next start). Sin embargo, JavaScript sigue siendo necesario para next dev para habilitar Fast Refresh.