Apply CSS in Next.js with StayedCSS

Styling Issues in Next.js App Router

Since the launch of the Next.js App Router, developers have embraced a paradigm that separates server and client components. While efficient, it introduces new challenges.

Challenge 1: Supporting server-side and client-side environments

Next.js often uses React styling libraries, as it’s based on React. However, many of these libraries are optimized for CSR (Client-Side Rendering), while the App Router defaults to SSR (Server-Side Rendering). This mismatch can lead to inconsistent styles between SSR and CSR.

Challenge 2: Flash of Unstyled Content (FOUC)

Dark mode is a common feature for better UX, but SSR typically renders HTML in light mode. The client applies dark mode later, causing screen flickering that disrupts the user experience.

I’ve faced these challenges myself during development. Despite the strengths of Next.js, styling problems kept getting in the way. Here's how I addressed them.

StayedCSS: The CSS Library for Next.js App Router

vectordxy / stayedcss

✨ A lightweight CSS library for Next.js App Router, supporting server and client components.

StayedCSS: The CSS library for Next.js App Router

Introduction

StayedCSS - beta version

StayedCSS is a static CSS library designed for Next.js App Router, offering full support for both server and client components. With a simple syntax similar to basic CSS, it enables efficient styling and aims to be the next-generation CSS library for the Next.js App Router.

Currently in its beta version, StayedCSS is rapidly improving in optimization and stability. It will continue to evolve to deliver a better styling experience for your projects.

Main Features

• Server and Client Component Support: Apply styles seamlessly to server and client components in the Next.js App Router environment.
• Various Styling Options: Supports various CSS styles such as :hover, ::after, and ~ p.
• Media Queries: Simplify responsive design implementation.
• Dark Mode: Offers flicker-free dark mode transitions.

Getting Started

Installation

npm install stayedcss
# or
yarn

…

View on GitHub

To address these issues, I created StayedCSS. This library supports both server and client environments, offering flicker-free dark mode and seamless compatibility with the Next.js App Router.

I hope StayedCSS helps other developers solve these challenges, and I’m excited to share it with the community!

1. Applying Styles to Server Components

import { st } from "stayedcss";

const styles = st({
  componentId: "components/example",
  container: {
    backgroundColor: "white",
    padding: "20px",
  },
});

export default function Example() {
  return (
    <div className={styles.container}>
      <h1>Hello, StayedCSS!</h1>
    </div>
  );
}

Define styles using the st function, which generates static CSS files and unique class names. Each style object is linked to a componentId, ensuring easy differentiation. Server components can now leverage CSS-in-JS-like syntax while benefiting from static CSS optimized for SSR.

2. Applying Styles to Client Components

'use client'

import { stClient } from "stayedcss/client";

export default function ExampleClient() {
  return (
    <div className={style.container}>
      <div className={style.title}>title</div>
    </div>
  );
}

const style = stClient({
  componentId: "components/example-client",
  container: {
    marginBottom: 60,
  },
  title:{
    fontSize: 27,
  },
});

For client components, use the stClient function to define styles. Similar to server components, it generates static CSS files and unique class names based on a componentId. Both server and client components share the same simple styling approach.

3. Dark Mode without Flickering

import { st, stDark } from "stayedcss";

export default function DarkModeExample() {
  return (
    <div className={style.container}>
      <h1>Hello world!</h1>
    </div>
  );
}

const style = st({
  componentId: "component/darkmode-example",
  container: {
    backgroundColor: "white",
  },
});

stDark({
  componentId: "component/darkmode-example",
  container: {
    backgroundColor: "black",
  },
});

StayedCSS resolves FOUC issues in SSR by using cookies to apply dark mode without delays or flickering. Define light and dark mode styles with matching componentId for smooth transitions.

4. Responsive Pages with Simple method

const style = st({
  componentId: "components/docs/media-query",
  container: {
    display: "flex",
    justifyContent: "center",
    padding: "20px",
    backgroundColor: "lightgray",
  },
  "@mobile": {
    container: {
      backgroundColor: "pink", 
      padding: "10px",
    },
  },
  "@tablet": {
    container: {
      backgroundColor: "lightblue", 
      padding: "15px",
    },
  },
  "@desktop": {
    container: {
      backgroundColor: "lightgreen",
      width: "50%",
    },
  },
});

StayedCSS makes media queries easy with keywords like mobile, tablet, and desktop. Declare responsive styles directly in the style object for clean and adaptive designs across screen sizes.

5. Taking It Further with Advanced CSS

const style = st({
  componentId: "components/docs/pseudo-classes",
  container: {
    backgroundColor: "black",
    ":hover": {
      backgroundColor: "green",
    },
  },
});

Supported features include pseudo-classes :hover, pseudo-elements ::before, and combinators ~. Write familiar CSS syntax, and StayedCSS optimizes it into static files, enabling high-performance styling across server and client components.

For detailed examples, visit the Docs page.

---

StayedCSS is here to simplify styling in the Next.js App Router environment. From server-client compatibility to advanced CSS features, it’s designed for a better styling experience. Try it today and share your thoughts — I’d love to hear your feedback! 🚀