Migration to native CSS

Overview

The :global() selector in next-yak is deprecated and will be removed in the next major version. This guide explains how to migrate to native CSS transpilation mode, which provides a simpler and more performant approach to handling global selectors.

Why are :global() selectors deprecated?

The :global() selector was originally needed because next-yak used CSS Modules under the hood, which scopes all selectors locally by default. To target global classes or elements, you had to wrap them in :global().

With native CSS transpilation mode, next-yak outputs standard CSS instead of CSS Modules, eliminating the need for :global() wrappers entirely.

Migration Steps

import { withYak } from "next-yak/withYak";

const nextConfig = {
  // your next.js config
};

export default withYak({
  experiments: {
    transpilationMode: 'Css'
  }
}, nextConfig);

import { styled } from 'next-yak';

const Container = styled.div`
  padding: 1rem;

  :global(.external-class) { // [!code --]
  .external-class { // [!code ++]
    color: red;
  }

  :global(body) { // [!code --]
  body { // [!code ++]
    margin: 0;
  }
`;

Using the ESLint Plugin

The eslint-plugin-yak package includes a rule to help identify :global() usage in your codebase:

import eslintPluginYak from "eslint-plugin-yak";

export default [
  eslintPluginYak.configs.recommended,
  // or enable just the deprecation rule:
  {
    plugins: { yak: eslintPluginYak },
    rules: {
      "yak/css-global-deprecated": "warn"
    }
  }
];

This will warn you about any :global() selectors that need to be migrated.

Suppressing Deprecation Warnings

If you need more time to migrate, you can temporarily suppress the deprecation warnings:

import { withYak } from "next-yak/withYak";

export default withYak({
  experiments: {
    suppressDeprecationWarnings: true
  }
}, nextConfig);

Before and After Examples

Targeting external library classes

const Wrapper = styled.div`
  :global(.react-select__control) {
    border-color: blue;
  }
`;

const Wrapper = styled.div`
  .react-select__control {
    border-color: blue;
  }
`;

Styling body or html elements

const GlobalStyles = styled.div`
  :global(html) {
    font-size: 16px;
  }

  :global(body) {
    margin: 0;
    padding: 0;
  }
`;

const GlobalStyles = styled.div`
  html {
    font-size: 16px;
  }

  body {
    margin: 0;
    padding: 0;
  }
`;

Nested global selectors

const Card = styled.div`
  :global(.dark-mode) & {
    background: #333;
    color: white;
  }
`;

const Card = styled.div`
  .dark-mode & {
    background: #333;
    color: white;
  }
`;

FAQ

Will my styles break if I switch to native CSS mode?

No, the styling behavior remains the same. The only difference is that you no longer need :global() wrappers since all selectors are treated as global by default in native CSS mode.

Can I use both modes during migration?

No, you must choose one transpilation mode for your entire project. We recommend migrating all :global() usage at once when switching to native CSS mode.

What if I'm using CSS Modules features like :local()?

Native CSS transpilation mode doesn't support CSS Modules-specific features like :local(). If you rely on these features, you may need to refactor your styles before migrating.