
## Introduction

Custom cursors are one of those small details that add "life" or personality to a website. Some time ago, I was browsing through some Awwwards websites and noticed the modified circular cursor that follows the mouse with a slight delay.

The effect is simple on the surface: a small circle follows the mouse with a slight delay, scales up when hovering over interactive elements, and disappears on mobile. But the implementation matters a lot. Do it wrong and you get jank. Do it right and the interaction feels effortless.

This guide covers how to build exactly that using Next.js (Pages Router), GSAP, and styled-components. No React state for mouse position, no `requestAnimationFrame` boilerplate. Just `gsap.quickTo()`, which handles the interpolation in a single line.

Here's what the finished effect looks like:

- Small circular cursor that replaces the default
- Smooth delayed movement (lerp-style lag)
- Ring scales on hover over links, buttons, or any custom element
- Hidden on mobile automatically

## Why GSAP and Not CSS Transitions

The naive approach is to set the cursor's `left` and `top` with `setState` and use a CSS `transition` to smooth it out. That works until it doesn't: React re-renders on every mousemove, the transition easing fights with the animation frame timing, and the result looks slightly off on fast movements.

`gsap.quickTo()` solves all of this. It creates a cached setter that GSAP drives directly on the DOM element, outside of React's render cycle. The motion is frame-perfect and the easing is applied correctly at any speed.

```ts
const xTo = gsap.quickTo(element, 'x', { duration: 0.45, ease: 'power3' });
// later:
xTo(e.clientX); // no re-render, no jank
```

## Building the Component

Install GSAP if you haven't already:

```bash
npm install gsap
```

Create `components/CustomCursor/index.tsx`:

```tsx
import { useEffect, useRef } from 'react';
import styled from 'styled-components';
import gsap from 'gsap';

const CursorRing = styled.div`
    position: fixed;
    top: 0;
    left: 0;
    width: 20px;
    height: 20px;
    border: 1px solid rgba(255, 255, 255, 0.35);
    border-radius: 50%;
    pointer-events: none;
    z-index: 9999;
    transform: translate(-50%, -50%);
    backdrop-filter: blur(2px);
    background: rgba(255, 255, 255, 0.04);
    mix-blend-mode: difference;
    will-change: transform;

    @media (max-width: 768px) {
        display: none;
    }
`;

const CursorDot = styled.div`
    position: fixed;
    top: 0;
    left: 0;
    width: 4px;
    height: 4px;
    background: rgba(255, 255, 255, 0.9);
    border-radius: 50%;
    pointer-events: none;
    z-index: 10000;
    transform: translate(-50%, -50%);
    will-change: transform;

    @media (max-width: 768px) {
        display: none;
    }
`;

export default function CustomCursor() {
    const ringRef = useRef<HTMLDivElement>(null);
    const dotRef  = useRef<HTMLDivElement>(null);

    useEffect(() => {
        const ring = ringRef.current;
        const dot  = dotRef.current;
        if (!ring || !dot) return;

        // Ring follows with a slight lag, dot snaps almost instantly
        const xRing = gsap.quickTo(ring, 'x', { duration: 0.45, ease: 'power3' });
        const yRing = gsap.quickTo(ring, 'y', { duration: 0.45, ease: 'power3' });
        const xDot  = gsap.quickTo(dot,  'x', { duration: 0.08, ease: 'power3' });
        const yDot  = gsap.quickTo(dot,  'y', { duration: 0.08, ease: 'power3' });

        const moveCursor = (e: MouseEvent) => {
            xRing(e.clientX); yRing(e.clientY);
            xDot(e.clientX);  yDot(e.clientY);
        };

        const hoverEls = document.querySelectorAll('a, button, [data-cursor-hover]');

        const onEnter = () =>
            gsap.to(ring, { scale: 2.5, duration: 0.3, ease: 'power3.out' });
        const onLeave = () =>
            gsap.to(ring, { scale: 1,   duration: 0.3, ease: 'power3.out' });

        window.addEventListener('mousemove', moveCursor);
        hoverEls.forEach((el) => {
            el.addEventListener('mouseenter', onEnter);
            el.addEventListener('mouseleave', onLeave);
        });

        return () => {
            window.removeEventListener('mousemove', moveCursor);
            hoverEls.forEach((el) => {
                el.removeEventListener('mouseenter', onEnter);
                el.removeEventListener('mouseleave', onLeave);
            });
        };
    }, []);

    return (
        <>
            <CursorRing ref={ringRef} />
            <CursorDot  ref={dotRef}  />
        </>
    );
}
```

## The Dual Cursor Pattern

The component renders two elements: a fast dot and a slow ring. The dot has `duration: 0.08`, which makes it feel almost physically attached to the pointer. The ring has `duration: 0.45`, which gives it that lagging elastic feel you see on Awwwards sites.

Running two separate `quickTo` instances at different speeds is the entire trick. No complex physics, no velocity tracking, just two different durations on the same coordinates. The visual gap between them creates the depth.

## Hiding the Native Cursor

You need to suppress the browser's default cursor inside the section where your custom cursor is active. The cleanest way to do this in a Pages Router project is to scope it to a container rather than applying `cursor: none` globally.

Pass a `scope` selector to the component, and it will hide the native cursor only inside that element:

```tsx
type Props = { scope?: string };

export default function CustomCursor({ scope }: Props) {
    useEffect(() => {
        const target = scope
            ? document.querySelector<HTMLElement>(scope)
            : document.body;

        if (target) target.style.cursor = 'none';

        // ... rest of setup

        return () => {
            if (target) target.style.cursor = '';
        };
    }, [scope]);
}
```

If you want the cursor site-wide, add it to `_app.tsx` without a scope. If you want it only on the hero, add an `id` to the section and pass it:

```tsx
// pages/_app.tsx
<CustomCursor />
```

Or scoped:

```tsx
// pages/index.tsx
<HeroSection id="hero">
    <CustomCursor scope="#hero" />
    ...
</HeroSection>
```

## Adding Hover Targets

By default, the ring scales on `a` and `button` elements. To trigger the effect on anything else, add the `data-cursor-hover` attribute:

```tsx
<div data-cursor-hover>
    Featured Project
</div>
```

That's all. No class names to remember, no additional wiring. The `useEffect` picks up everything matching `a, button, [data-cursor-hover]` at mount time.

```tsx
const hoverEls = document.querySelectorAll('a, button, [data-cursor-hover]');
```

> One limitation: hover listeners are attached at mount. If your page renders new interactive elements after mount (e.g., from a data fetch), you'll need to re-run the effect or attach listeners to those elements separately.

## Scoping to the Hero Only

If you want the cursor effect on the hero but not the rest of the page, the scope prop handles it cleanly. Give your hero section an ID and pass it as the selector:

```tsx
<section id="hero">
    <CustomCursor scope="#hero" />
    {/* hero content */}
</section>
```

The `scope` prop also tells the component where to query for hover targets, so the querySelectorAll is also scoped to that container.

## Optional: Cursor Text on Hover

You can extend the cursor into a pill shape that reveals text like `VIEW` or `OPEN` on hover over project cards. This works well on dark portfolios with large image cards.

Adjust the styled component:

```tsx
const CursorRing = styled.div`
    /* existing styles */
    display: flex;
    align-items: center;
    justify-content: center;
    font-size: 9px;
    font-weight: 600;
    letter-spacing: 0.1em;
    color: white;
    overflow: hidden;
`;
```

Then in the `mouseenter` handler:

```ts
const onEnter = (e: Event) => {
    const label = (e.currentTarget as HTMLElement).dataset.cursorLabel;
    if (ring.firstChild) ring.firstChild.textContent = label ?? '';
    gsap.to(ring, {
        scale: 3.5,
        borderRadius: '20px',
        duration: 0.3,
        ease: 'power3.out',
    });
};
```

Add the label via a data attribute:

```tsx
<div data-cursor-hover data-cursor-label="VIEW">
    Project Card
</div>
```

## Performance Tips

The most common mistake is driving cursor position with `useState`. This triggers a React re-render on every `mousemove` event, which is 60+ times a second. On a complex page that causes noticeable frame drops.

The right approach:

- Store the cursor element in a `ref`, not state
- Use `gsap.quickTo()` to animate it directly on the DOM node
- Never call `setState` in a `mousemove` handler

```ts
// Don't do this
const [pos, setPos] = useState({ x: 0, y: 0 });
window.addEventListener('mousemove', (e) => setPos({ x: e.clientX, y: e.clientY }));

// Do this
const xTo = gsap.quickTo(ref.current, 'x', { duration: 0.4 });
window.addEventListener('mousemove', (e) => xTo(e.clientX));
```

The GSAP approach never touches React's reconciler. The animation runs entirely in GSAP's internal loop, and the DOM update happens once per frame via `requestAnimationFrame` internally.

## Recommended Style for a Minimal Portfolio

If your site has a dark background and clean typography, keep the cursor subtle:

- Thin `1px` outlined ring, no fill
- `backdrop-filter: blur(2px)` for a frosted glass feel
- `mix-blend-mode: difference` so it inverts the color under it automatically
- Scale to `2.5x` on hover, not larger
- No particles, trails, or color changes

The goal is to add personality without distraction. The cursor should feel like part of the interface, not a feature competing for attention.

## Conclusion

A custom cursor done well is invisible until you notice it, and then you can't imagine the site without it. The whole thing comes down to two ideas: use `gsap.quickTo()` instead of React state, and separate the ring from the dot at different speeds. Everything else is styling.

The full component is less than 80 lines and has zero dependencies beyond GSAP, which you likely already have if you're doing any animation work in Next.js.

## Resources

1. [GSAP quickTo docs](https://gsap.com/docs/v3/GSAP/gsap.quickTo())
2. [GSAP with React](https://gsap.com/resources/React/)
3. [styled-components docs](https://styled-components.com/docs)
4. [mix-blend-mode on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/mix-blend-mode)


How to Build a Custom Cursor Effect in Next.js with GSAP

Recommended Style for a Minimal Portfolio


  
## Introduction

When the first version of Next.js was released in 2016, it came with a filesystem-based routing system called the **Pages Router**. It uses a specific `pages` directory for defining routes. In Next.js 13, the **App Router** was introduced as a more modern alternative that uses a `app` directory for route organization, and providing support for newer React features like **Server Components**, **Server Functions**, and **Suspense**. Both are fully supported today, and choosing between them is one of the first decisions you'll make when starting a new Next.js project.
  
On the surface, the two routers achieve the same goal: they map files in your project to URL routes. But under the hood, they have fundamentally different architectures, data-fetching patterns, and mental models. Understanding these differences will help you make better architectural decisions, avoid common pitfalls, and write more efficient Next.js applications.

In this article, you'll learn the key differences between the App Router and the Pages Router, when to use each, and how to think about migrating if you're working on an existing project.

## How routing works

The most visible difference between the two routers is how files map to routes. 

### Pages router

In the Pages Router, any React file (`.js`, `.ts`, `.jsx`, or `.tsx`) you create inside the `pages/` directory automatically becomes a route. You can also use folders to group pages, but the file name is the route.

```bash
pages/
├── index.tsx → example.com/
├── about.tsx → example.com/about
├── blog/
│ ├── index.tsx → example.com/blog
│ └── [slug].tsx → example.com/blog/:slug
```

Dynamic routes use bracket notation `[slug].tsx`, and catch-all routes use spread notation `[...slug].tsx`. 


### App router

  The App Router, on the other hand, lives inside the `app/` directory. The key difference is that folder names define routes, and a special file called `page.tsx` inside that folder defines the UI for that route.


```bash

app/
├── page.tsx → /
├── about/
│ └── page.tsx → /about
├── blog/
│ ├── page.tsx → /blog
│ └── [slug]
│ └── page.tsx → /blog/:slug

```

This might seem like more boilerplate at first glance, but the folder-based approach unlocks a more powerful feature: **co-location**. You can place components, tests, and utilities directly alongside the route files that use them, without accidentally exposing them as routes.

## Layouts

  Layouts are one of the biggest practical differences between the two routers.

### Pages router

One major limitation of the Pages Router is its lack of built-in nested layouts like the App Router. You have to manually implement nested layouts through a global layout defined in `_app.tsx` (which is not what you want in most cases) or the `getLayout` pattern.

Suppose you have the following dashboard structure:

```bash
pages/
├── dashboard/
│ ├── index.tsx 
│ ├── settings.tsx 
```

Ideally, both pages would share a common `DashboardLayout` containing elements such as a sidebar and navbar. To achieve that with the Pages Router, you have to manually import the layout and attach the `getLayout` in every single page. 

Without a shared layout pattern, navigating between `dashboard/index.tsx` and `dashboard/settings.tsx` causes the current page component to unmount and the next page component to mount. Any local React state stored within the page or its layout components is therefore lost between navigations.

### App router

The App Router makes nested layouts a first-class feature. Any `layout.tsx` file in a folder automatically wraps the routes inside that folder, and layouts persist across navigations, meaning they don't remount when a user navigates between child routes.


```bash
app/
├── layout.tsx ← root layout (wraps everything)
├── page.tsx
└── dashboard/
├── layout.tsx ← dashboard layout (persists within /dashboard/*)
├── page.tsx
└── settings/
└── page.tsx
```

Some developers find the file naming conventions used by the App Router less convenient when navigating large codebases:

```bash
page.tsx
layout.tsx
loading.tsx
error.tsx
route.ts
```

I agree that having multiple identical file names in a codebase can cause visual clutter and make debugging harder in code editors. 

However, I also think that this issue can be mitigated by using specific editor features like tab naming configurations. For example, VS Code allows you to change `workbench.editor.labelFormat` to `medium` or `short` to display parent folder names on tabs.


## Data fetching

Data fetching is one of the most commonly debated issues in Next.js, and it's also where the two router methodss diverge the most.

### Pages router

The Pages Router provides three special data fetching functions that you export from page files:

- **Static Site Generation (SSG)** – `getStaticProps`: Fetches data at build time and generates a static HTML page.
- **Server-Side Rendering (SSR)** – `getServerSideProps`: Fetches data on each request and renders the page on the server.
- **Dynamic Routes with SSG** – `getStaticPaths`: Works with `getStaticProps` to specify which dynamic pages should be pre-rendered at build time.

Additionally, the Pages Router supports dynamic data fetching if you don't need SEO optimization and your data refreshes dynamically inside the browser view:

- **Client-Side Rendering (CSR)** – Uses `fetch`, `useEffect`, or libraries like SWR to fetch data in the browser after the page loads.

```tsx
// pages/blog/[slug].tsx

import { useEffect, useState } from 'react';

// SSG: Fetch data at build time
export async function getStaticProps({ params }) {
  const post = await fetchPost(params.slug);

  return {
    props: { post },
  };
}

// SSG: Define dynamic routes to pre-render
export async function getStaticPaths() {
  const slugs = await fetchAllSlugs();

  return {
    paths: slugs.map((slug) => ({
      params: { slug },
    })),
    fallback: false,
  };
}

export default function BlogPost({ post }) {
  const [comments, setComments] = useState([]);

  // CSR: Fetch comments in the browser after hydration
  useEffect(() => {
    async function loadComments() {
      const res = await fetch(`/api/comments?slug=${post.slug}`);
      const data = await res.json();
      setComments(data);
    }

    loadComments();
  }, [post.slug]);

  return (
    <>
      <article>{post.content}</article>

      <section>
        <h2>Comments</h2>
        {comments.map((comment) => (
          <p key={comment.id}>{comment.body}</p>
        ))}
      </section>
    </>
  );
}
```

In this example, the blog post is statically generated using `getStaticProps`, dynamic routes are defined with `getStaticPaths`, and comments are fetched on the client after hydration using `fetch` and `useEffect`.

### App router

The App Router replaces the three data fetching functions with **async Server Components**. Because Server Components run exclusively on the server, you can fetch data directly inside the component as no special function is needed.

```tsx
// app/blog/[slug]/page.tsx

export default async function BlogPost({ params }) {
const post = await fetchPost(params.slug);

return <article>{post.content}</article>;
}
```

For static generation with dynamic routes, you export a `generateStaticParams` function (the equivalent of `getStaticPaths`):


```tsx
export async function generateStaticParams() {
const slugs = await fetchAllSlugs();
return slugs.map((slug) => ({ slug }));
}
```

For cache control, which the Pages Router handled via `revalidate` in `getStaticProps`, the App Router uses the native `fetch` API with a `next` option:

```tsx
const data = await fetch('https://api.example.com/posts', {
next: { revalidate: 3600 }, // revalidate every hour
});
```

> The `revalidate` option works the same way as `revalidate` in `getStaticProps` from the Pages Router. It tells Next.js how long to cache the response before re-fetching it in the background.

## React server components

React Server Components (RSCs), introduced in React 19, are a new type fo Component that allows you to render UI components exclusively on the server, sending zero client-side JavaScript for those components to the browser. This rendering happens ahead of time, before bundling, in an environment separate from your client app or SSR server.

RSCs is the most architecturally significant difference between the Pages and App Router, and it stems directly from how the App Router works.

### What are Server Components?

React Server Components (RSC) are components that render exclusively on the server. They have direct access to databases, file systems, and secrets, without exposing any of it to the client. They produce zero JavaScript in the client bundle, which improves performance.

In the App Router, _all components are Server Components by default_. To opt a component into client-side rendering (event handlers, state, browser APIs), you _must_ add the `'use client'` directive at the top of the file:

```tsx

'use client';

import { useState } from 'react';

export default function Counter() {
const [count, setCount] = useState(0);

return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
```

### Pages router

The Pages Router does not have Server Components. All components are client components by default. Data fetching is separated out into special functions like`getStaticProps` or `getServerSideProps`, and components themselves always run on the client.

This distinction matters because in the App Router, you need to be intentional about what runs where. A common mistake is trying to use hooks (`useState`, `useEffect`) in a Server Component, the compiler will throw an error until you add `'use client'`.

> A useful mental model: if a component needs to be interactive or access browser APIs, it's a Client Component. If it just renders data, it can be a Server Component.


## API routes

Both routers support API routes: server-side endpoints that handle HTTP requests.

### Pages router

API routes live in `pages/api/` and export a handler function:

```tsx

// pages/api/hello.ts
import type { NextApiRequest, NextApiResponse } from 'next'; 

export default function handler(req: NextApiRequest, res: NextApiResponse) {
res.status(200).json({ message: 'Hello' });

}
```

### App router

The App Router uses **Route Handlers**, which live in `route.ts` files inside the `app/` directory. They use the Web standard `Request` and `Response` objects:

  
```tsx

// app/api/hello/route.ts
export async function GET(request: Request) {
return Response.json({ message: 'Hello' });
}

```

Route Handlers support named exports for each HTTP method (`GET`, `POST`, `PUT`, `DELETE`, etc.), which is cleaner than the `req.method` switch statement pattern common in Pages Router API routes.


```tsx

export async function GET() { /* ... */ }
export async function POST(request: Request) { /* ... */ }
export async function DELETE(request: Request) { /* ... */ }
```

## Middleware

Middleware works the same way in both routers: you create a `middleware.ts` file at the root of your project and export a `middleware` function. The API is identical regardless of which router you're using.

```tsx
// middleware.ts

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {

if (!request.cookies.get('token')) {
return NextResponse.redirect(new URL('/login', request.url));
}

return NextResponse.next();
}

export const config = {
matcher: '/dashboard/:path*',
};
```


## Special files

Each router has its own set of special files that handle specific behaviours.

| Purpose | Pages Router | App Router |
|---|---|---|
| Root HTML shell | `_document.tsx` | `layout.tsx` |
| Global wrapper | `_app.tsx` | `layout.tsx` |
| 404 page | `404.tsx` | `not-found.tsx` |
| Error boundary | `_error.tsx` | `error.tsx` |
| Loading state | — | `loading.tsx` |
| Route component | `[name].tsx` | `page.tsx` |

The App Router's `loading.tsx` is particularly useful. It automatically renders a loading UI using React Suspense while a page or layout is fetching data, without any manual Suspense boundary setup.


## When to use each

As of today, the Next.js team recommends using the App Router for new Next.js projects. They made it clear that App Router is the future of the framework, and most new features are being built exclusively for it.

**Use the Pages Router when:**

- You're maintaining an existing Pages Router project; there's no obligation to migrate
- Your team is more comfortable with the traditional model
- You're using third-party libraries or patterns that haven't fully adopted Server Components yet
- Your project is a straightforward marketing site or blog with simple data fetching

  
**Use the App Router when:**

- You're starting a new project today.
- You need fine-grained control over which parts of the UI render on the server vs. client.
- You're building a complex application with nested layouts, streaming, or incremental rendering.
- You want to take advantage of Server Components to reduce client bundle size.


## How to migrate from Pages to App router

Next.js officially supports running both routers in the same project during migration. The `pages/` and `app/` directories can coexist, so you can migrate incrementally, route by route, without a single rewrite.

The general migration steps are:

1. Create the `app/` directory at the root of your project.
2. Create a root `app/layout.tsx` that includes the `<html>` and `<body>` tags (this replaces `_document.tsx`).
3. Move global styles and providers from `_app.tsx` into the root layout (`app/layout.tsx`).
4. Migrate `next/head` usage to the App Router Metadata API.  
	- In the Pages Router, `next/head` is used to manage `<head>` elements like titles and meta tags.  
	- In the App Router, it is replaced by the built-in Metadata API (`export const metadata`) for static metadata or `generateMetadata` for dynamic cases.
5. Migrate pages one at a time, starting with the simplest ones.
6. Convert `getStaticProps` / `getServerSideProps` calls to async component fetches or `generateStaticParams`.
7. Audit components for `useState` / `useEffect` usage and add `'use client'` where needed.

The most common migration pain points are:

- **Context providers**: They need to be in a Client Component, so wrap them in a `'use client'` component and import that into the Server Component layout.
- **Third-party libraries**: Some older libraries don't yet support Server Components. Check the library's documentation before migrating.
- **Cookies and headers**: `cookies()` and `headers()` from `next/headers` replace `req.cookies` and `req.headers` from `getServerSideProps`.

## Conclusion

The Pages Router and the App Router are both mature, production-ready options. The Pages Router is simpler, battle-tested, and well-documented with years of community resources behind it. The App Router is more powerful, more flexible, and where the framework is heading. But it comes with a steeper learning curve, particularly around the Server/Client Component boundary.

If you're building a new Next.js application today, start with the App Router. If you're maintaining an existing project, migrate when the complexity of your application genuinely calls for it, not because a new version was released.


Understanding the Differences Between Next.js App Router and Pages Router



## Introduction
Following the release of version 20.6.0, the Node.js team [announced](https://nodejs.org/en/blog/release/v20.6.0) that there will be built-in support for .env configuration files going forward. This update is long overdue and represents a significant win for all Node.js developers. Environment variables are a common aspect of Node.js app development that every developer must deal with in most of their applications.

Before this release, the Node.js community relies on an npm package called `dotenv` to manage and simplify loading environment variables in Node.js applications.

In this short article, I'll show you how you can start using the built-in feature in your applications.

First of all, if you haven't updated your Node.js installation to v20.6.0 or above, you can download the installer for your platform on the official website [here](https://nodejs.org/en/download/).

After the installation is complete, run `node -v` to confirm you have a version not older than v20.6.0.

## How to use the built-in .env file support

I assume you already have a project you'd like to test this feature in. Note that for this to work, the `.env`` configuration file you want to load the environment variable from must follow the INI file format.

Here's an example:

```bash
ADMIN_PASSWORD=XT56yf45te
DATABASE_URL=https:127.0.0.1
```

One way to load the environment variables into your application is to use the following CLI command: 
```bash
node --env-file=config.env index.js
```

In the above example, `config.env` is the name of the file containing the environment variables. However, you're free to name it whatever you like - you may be familiar with the more  common `.env` file name.

Another way is to use the command in `package.json`. So if you have a `.env` file in your project directory, you can do something like so:

```json
//...
"scripts": {
  "start": "node --env-file=.env index.js" // Assuming index.js is the entry point of your application.
}
```
Now, when you run `npm start`, Node.js will load the environment variables and you can them access them like `process.env.ADMIN_PASSWORD`, etc.

If you'd like to read more about other features in the release, feel free to check it out [here](https://nodejs.org/en/blog/release/v20.6.0).


You Don't Need Dotenv in Node.js 20.6.0

How to use the built-in .env file support

 



## Introduction
 [`zip()`](https://docs.python.org/3/library/functions.html#zip) is a built-in function in Python used for unpacking values from one or more iterables into a tuple, with one value from each of the iterables in the tuple. Another way of thinking about the `zip` function is transposing a square matrix.


## Syntax
The `zip()` function has the following syntax: 

```python
zip(*iterable, strict=False)
```

- `iterable`: An object that can be looped or iterated over. Examples include strings, lists, dictionaries, tuples, sets, etc.
- `strict`:  A boolean value that allows you to set whether the length of the iterables should be the same or not.
- **Return value**: The return value is an iterator of tuples, where the _i_-th tuple contains the _i_-th element from each of the argument iterables. Note that until the zip function is iterated upon, for example, using a **for** loop, or wrapping in a `list()` constructor, the iterables won't be processed or accessible. 

## Understanding the `zip` function through examples

1. Here we're using a **for** loop with the `zip` function to unpack iterables like, a range function, a list, a tuple and a string:

```python
for item in zip(range(4),  ['fee', 'fi', 'fo', 'fum'], ('bam', 'baz', 'bat', 'ban'), 'abot'):  
    print(item)
```

Running the code above prints the following tuples : 
```python
(0, 'fee', 'bam', 'a')
(1, 'fi', 'baz', 'b')
(2, 'fo', 'bat', 'o')
(3, 'fum', 'ban', 't')
```

2. In the following example, we're using the `list()` constructor together with the `zip` function: 

```python
list(zip(range(4),['fee', 'fi', 'fo', 'fum'], ['bam', 'baz', 'bat', 'ban']))
```

The code above outputs:

```python
[(0, 'fee', 'bam'), (1, 'fi', 'baz'), (2, 'fo', 'bat'), (3, 'fum', 'ban')]
```


3. When using the `zip` function, if the `strict` argument is not set to True and the iterables provided are of different lengths, `zip` will only consider the values up to the length of the shortest iterable, ignoring any extra values in the longer iterables. In the example below, the third iterable which is a tuple has a length shorter than other iterables in the function:
 
```python
for item in zip(range(4),  ['fee', 'fi', 'fo', 'fum'], ('bam', 'baz', 'bat'), 'abot'):  
    print(item)
```

And as you can see below, the last item of each of the longer iterables is discarded:

```python
(0, 'fee', 'bam', 'a')
(1, 'fi', 'baz', 'b')
(2, 'fo', 'bat', 'o')
```

4. If you set the value of `strict` to True, and of the iterables passed to the `zip` function has a unequal length, a `ValueError` will be raised.  Here's the code from the last example, but with  `strict=True`:
```python
for item in zip(range(4),  ['fee', 'fi', 'fo', 'fum'], ('bam', 'baz', 'bat'), 'abot', strict=True):  
    print(item)
```

A `ValueError` is thrown as shown below:

```python
(0, 'fee', 'bam', 'a')
(1, 'fi', 'baz', 'b')
(2, 'fo', 'bat', 'o')

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[13], line 1
----> 1 for item in zip(range(4),  ['fee', 'fi', 'fo', 'fum'], ('bam', 'baz', 'bat'), 'abot', strict=True):  
      2 print(item)

ValueError: zip() argument 3 is shorter than arguments 1-2
```


## Tips and tricks for using the `zip` function

### Create a dictionary from two lists
One common use case of the zip function is for creating a dictionary from two lists: 
```python
keys = [0, 1, 2, 3, 4, 5]
values = ["John", "Jane", "Max", "Dave", "Ella"]

create_dict = dict(zip(keys, values))
print(create_dict) # {0: 'John', 1: 'Jane', 2: 'Max', 3: 'Dave', 4: 'Ella'}
```

### Parallel iteration of two or more lists
Here's how you can use the `zip` function to loop through two or more sequences simultaneously.

```python
users = ['Max', 'Jane', 'Jack']
ages = [25, 30, 25]
for name, age in zip(users, ages):
    print(f'{name} is {age} years old.')

# prints:
# Max is 25 years old.
# Jane is 30 years old.
# Jack is 25 years old.
```

### Using `itertools.zip_longest()` to fill missing values
If one or more of the iterables passed to the `zip` function has a shorter length than others, you can use `itertools.zip_longest()` to fill in the missing values. The example below fills the missing values with 0:

```python
from itertools import zip_longest
list1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
list2 = ['a', 'b', 'c', 'd', 'e']
zipped = list(zip_longest(list1, list2, fillvalue=0))
print(zipped) 

# prints:
# [(1, 'a'), (2, 'b'), (3, 'c'), (4, 'd'), (5, 'e'), (6, 0), (7, 0), (8, 0), (9, 0), (10, 0)]
```

### Unzip a sequence using the * operator 
Perhaps you have been wondering if there's an `unzip` function that does the the opposite of `zip`, well, there's none. You can actually use the `zip` function to zip and unzip a sequence of iterables. 

The example below shows how you can use the `*` operator with `zip` to unzip a list of tuples into separate tuples:

```python
zipped = [('a', 1), ('b', 2), ('c', 3), ('d', 4)]
letters, numbers = zip(*zipped)
print(letters)
print(numbers)

# prints:
# ('a', 'b', 'c', 'd')
# (1, 2, 3, 4)
```

## Conclusion
`zip` is a very handy function every Python developer should have in their arsenal. Its versatility can help make your code look more readable and professional. 

Hopefully, this article has shed light on the potentials of `zip` and equipped you with valuable tips to leverage its capabilities in your next projects.

Until next time, happy coding!

Understanding the zip function in Python

Understanding the zip function through examples

Tips and tricks for using the zip function

Using itertools.zip_longest() to fill missing values


## Introduction
SSH (Secure Shell) is a fundamental tool in computer networking that allows two or more computers to communicate securely over a network. It was originally developed by Finnish researcher Tatu Ylönen, in response to a password-sniffing attack on his university's network in the summer of 1995.

Today, SSH serves as the foundation for many file transfer and remote connection protocols. Understanding how SSH works is an essential skill every developer must have.

In this article, you'll learn all there is about SSH, how it works, and the problems it solves. To solidify your knowledge, you'll also learn how to SSH into a Linux virtual machine (VM) created with Google Compute Engine, transfer files from your local computer to the VM instance using `scp` (Secure Copy Protocol), and spin off an Apache web server on the VM. 

## What is SSH and How Does it Work?

SSH is an internet protocol based on the TCP/IP protocol that establishes a secure connection between a client and a server over an unsecured network. It was developed as a replacement for unsecured network protocols like Telnet and remote shell (rsh), which use plaintext passwords for authentication. SSH has numerous applications, including logging into a remote computer's shell or command-line interface, transferring files using SCP or SFTP, tunneling, port forwarding, and more.

To use SSH to establish a connection between your local computer and a remote virtual machine or host, you need to install an SSH client on the computer you're connecting from, and an SSH server on the computer you're connecting to. By default, SSH uses port 22 to listen to connections between a client and server. However, since everyone knows SSH runs on port 22, this makes it a common target for brute-force attacks, so some administrators change the default port to a less predictable number to enhance security.

![How SSH works](/assets/posts/ssh/openssh-server-client.png)

SSH enables secure connection and transfer of data between two computers by using cryptography to authenticate and encrypt connections, ensuring that data transmitted between the client and server remains private and protected from eavesdropping. SSH allows several authentication methods for securely verifying a client's identity when connecting to a server. These include:

- Password authentication: Uses a username and password.
- Key-based authentication: Uses a public key stored on the server and a private key stored on the client computer.
- Two-factor authentication or certificate authentication: Provides additional security by requiring a second factor or a digital certificate.


Here's the command structure to instantiate a SSH connection between a computer and a remote server:

```bash
ssh <username>@<server name or IP address>
```

For example:

```bash
ssh michael@192.168.57.23
```


## What is OpenSSH?
OpenSSH is a popular and open-source implementation of the original SSH program developed by Tatu Ylönen. It consists of a suite of programs that provide several capabilities, including:

- Remote operations and file transfer using tools like `opensh-client`, `openssh-server`, `sftp`, `scp`, etc.
- Key generation and management using `ssh-keygen`, `ssh-add`, etc.
- A service side toolkit consisting of tools like `sshd` (OpenSSH daemon - a background service that listens for incoming SSH connections and handles authentication, session management, and encryption).

If you're using a Linux distro such as Ubuntu, Debian, Fedora, etc., OpenSSH client is usually installed by default, meaning you can use the `ssh` command to connect to remote servers without needing to install anything separately. 

You can verify if SSH is installed on your computer by running the following command:

```bash
ssh -V
```

If OpenSSH is installed, you should see an output similar to the following:

```bash
OpenSSH_9.6p1 Ubuntu-3ubuntu13.8, OpenSSL 3.0.13 30 Jan 2024
```

Now that you understand what SSH is and how it works, let's explore a real-world example of how to use it in practice.

## Create a Google VM Instance 
Google Compute Engine (GCE) is a component of Google Cloud Platform (GCP) that allows users to create and manage virtual machines (VMs) using Google's infrastructure. It's similar to Amazon EC2 and Microsoft Azure VMs.

Google offers a [free tier](https://cloud.google.com/free/docs/free-cloud-features?authuser=0#free-tier) that provides access to several Google Cloud products, including Compute Engine, BigQuery, Cloud Run, and more, at no cost. The free tier for Compute Engine includes the following resources, which is more than enough for our use case:

- One non-preemptible `e2-micro` VM instance per month in one of the following U.S. regions:
    - Oregon: `us-west1`
    - Iowa: `us-central1`
    - South Carolina: `us-east1`
- 30 GB-months of standard persistent disk storage
- 1 GB of outbound data transfer per month from North America to all regional destinations (excluding China and Australia)


To create and launch a VM using GCE, follow these steps:

1. In the [Google Cloud console](https://console.cloud.google.com/), go to the [VM instances](https://console.cloud.google.com/compute/instances) page.
2. When the **VM instances** page is ready, click **Create instance**.
3. In the **Name** field, enter a name for your VM.  I named mine `linux-server`.
4. In the **Region** list, select **us-central1**.
 ![VM instance configuration](/assets/posts/ssh/vm-configuration.png)
5. In the **Zone** list, select **us-central1-a**.
6.  In the Machine type list, select **E2**.
7. In the left navigation menu, click **OS and storage**.
8. Click **Change**.
9. In the **Boot disk** pane, on the **Public images** tab (default), select the following options:
    1. In the **Operating system** list, select **Ubuntu**.
    2. In the **Version** list, select **Ubuntu 24.04 LTS**.
    3. In the **Boot disk type** list, select **Balanced persistent disk**.
    4. In the **Size** box, choose **10**.
    5. Click **Select**.
    ![VM instance OS settings](/assets/posts/ssh/os-settings.png)
10. In the navigation menu, click **Networking**.
11. In the **Firewall** section, select **Allow HTTP traffic**.
![VM instance firewall settings](/assets/posts/ssh/firewall.png)
12. Click **Create**.

Now your new VM is listed on the **VM instances** page. When a green checkmark appears as shown in the image below, you're ready to connect to the VM and use it.

![Google cloud console VM instances](/assets/posts/ssh/vm-page.png)


When you create a Linux VM with Compute Engine, `openssh-server` is installed and enabled by default - you can confirm this by running the following command after connecting to the VM via SSH:

```bash
dpkg -l | grep openssh-server
```

You should see an output similar to this:

![terminal output](/assets/posts/ssh/openssh-server.png)


## SSH into the VM Instance
In this section, we'll explore two different ways you can connect to your VM instance using SSH.

### 1.  Connect using Google Cloud CLI

Google Cloud CLI (gcloud CLI) is a command-line tool that allows us to create, manage, and interact with Google Cloud resources, including VMs, from the command line or through scripts, automating many common GCP tasks. To install gcloud CLI for your OS, follow the instructions on [this page](https://cloud.google.com/sdk/docs/install). 

After the installation, initialize gcloud CLI by running the following command:

```bash
gcloud init
```


### 2. Connect using OpenSSH
In this step, we'll use key-based authentication to establish a connection between our computer and the VM. 

To use key-based authentication, there are three basic steps we need to follow:

1. Create public and private keys
2. Upload public key to VM
3. SSH into the VM using the private key

#### Step 1 - Create public and private Keys
To set up key-based authentication, we'll use the `ssh-keygen` tool from the OpenSSH suite to generate an SSH key pair. Since `ssh-keygen` is included with OpenSSH, there's no need for a separate installation. You can verify its presence by running `ssh-keygen -V` in the terminal.

Several cryptographic algorithms can be used to generate an SSH key pair, including RSA, ED25519_SK, ED25519, and more. However, the book [Practical Cryptography With Go](https://leanpub.com/gocrypto/read#leanpub-auto-chapter-5-digital-signatures) recommends [ED25519](https://ed25519.cr.yp.to/) as a more secure and efficient alternative to the others, so we'll use ED25519 to generate the key pair. 

> Before generating a new SSH key pair, it's possible that one already exists in  `~/.ssh` on your local computer.  If your existing keys are secure, strong, and already in use, you can stick with them. Otherwise, generate a new one.

Run the following command to use the ED25519 algorithm to generate a new key pair:

```bash
ssh-keygen -t ed25519
```

When prompted with:

```
Enter file in which to save the key (/home/user/.ssh/id_ed25519):
```

simply press **Enter** to use the default location. Next, you can either set a **passphrase** for added security or press **Enter** to skip it.

Once the key pair is generated, navigate to the `~/.ssh` directory:

```bash
cd ~/.ssh
```

Here, you'll find two separate files:

- `id_ed25519.pub`: Contains the public key, which can be shared.
- `id_ed25519`: Contains the private key, which must be kept secure.


#### Step 2 - Upload public key to VM
Since our VM is hosted on GCP, we'll need to upload the public key to Compute Engine on our Google Cloud console. Copy the content of the `id_ed25519` file from `Step 1` and go to the [metadata settings](https://console.cloud.google.com/compute/metadata) page for Compute Engine on Google Cloud console. 

On the page, you may notice an SSH key already exists. Yes, this is the key that was generated when you connected to the VM via gcloud CLI. To add a new SSH public, click on **Edit** > **Add item** as shown below:

![Metadata settings on google cloud console](/assets/posts/ssh/metadata-settings.png)

Once the public key has been added successfully, we can now go back to our local terminal to connect to the VM. 

> After adding the key, note your username. You'll need it when connecting via SSH. 

#### Step 3 - SSH into the VM using private key
Finally, to connect to the VM, run the following command:

```bash
ssh -i ~/.ssh/id_ed25519 your-user-name@VM_EXTERNAL_IP
```

- Replace `your-user-name` with your username from `Step 2`
- Replace `VM_EXTERNAL_IP` with your VM external IP address

> If you set a passphrase when generating the key pair, you'll be prompted to enter it to unlock the private key before proceeding.

Voila! You should now be logged into your virtual machine. You can see the changes in the terminal prompt as highlighted in the image below:

![terminal showing the linux VM server](/assets/posts/ssh/local-ssh.png)

## Transfer files to the Linux VM using `scp`

The VM we created uses the boot disk as storage, meaning whenever the VM is stopped or deleted, all files or data created in it will be lost. However, if we need to persist data, we can [attach a persistent disk to the VM instance](https://cloud.google.com/compute/docs/disks/add-persistent-disk#create_disk). 

For simplicity's sake, we'll go with the boot disk storage since we don't need to store any important data in the VM.  gcloud CLI includes a command, `gcloud compute scp`, that allows us to [transfer files](https://cloud.google.com/compute/docs/instances/transfer-files#transfergcloud) from a remote VM instance and vice versa.

The command structure looks like the following:

```bash
gcloud compute scp LOCAL_FILE_PATH VM_NAME:REMOTE_DIR --project PROJECT_ID
```

Where:

- `LOCAL_FILE_PATH`: the path to the file on your machine
- `VM_NAME`: the name of your VM
- `REMOTE_DIR`: a directory on the remote machine
- `PROJECT_ID`: the Project ID (you can run `gcloud projects list` to get the Project ID).

First, log in to your VM, then create a folder named `pictures` in the root folder:

```bash
mkdir pictures
```

Now, here's an example command (ensure you're running this command in a new local terminal prompt, not inside your VM instance) to transfer an image file from my computer to the VM: 

```bash
gcloud compute scp /home/michael-hungbo/Pictures/cld-sample.jpg linux-server:/home/michael-hungbo/pictures --project my-project-id
```

Now, if you go back to your VM instance terminal, you can confirm the file has been transferred by running `ls` in the `pictures` folder:

![terminal](/assets/posts/ssh/transferred-image.png)

## Serve a web page using Apache 

One of the cool things people do with VMs is creating web servers to deploy websites and apps to the cloud. Apache is an open-source HTTP web server that listens for requests from clients (like web browsers) and then responds by sending back the requested web pages or other files.

In this section, we'll set up an Apache web server on our VM and customize the default web page using CSS.

SSH into your VM using a local terminal and run the following command to update the package list:

```bash
sudo apt-get update
```

Next, install Apache2 HTTP web server:

```bash
sudo apt-get install apache2
```

By default, Apache serves a generic web page. We'll replace it with our own HTML file. 

Run the following command to overwrite the default Apache index file with a simple HTML page:

```bash
echo '<!doctype html><html><body><h1>Hello World!</h1></body></html>' | sudo tee /var/www/html/index.html
```

To enhance the look of our web page, let's create a CSS file and link it to the HTML file.

1. Open the HTML file in a text editor:

```bash
sudo nano /var/www/html/index.html
```

2. Modify the content to include a reference to an external CSS file:

```html
<!DOCTYPE html>
<html>
<head>
    <title>Setting up Apache on a Linux VM</title>
    <link rel="stylesheet" type="text/css" href="style.css">
</head>
<body>
    <h1>Welcome to My Web Page!</h1>
    <p>This page is styled using CSS.</p>
</body>
</html>
```

3. Press `CTRL + X`, then `Y`, and `Enter` to save and exit the editor.

4. Now, let's create the `style.css` file inside the web directory.

```bash
sudo nano /var/www/html/style.css
```

5. Then add the following code to the CSS file:

```css
body {
    background-color: #f4f4f4;
    font-family: Arial, sans-serif;
    text-align: center;
    padding: 50px;
}

h1 {
    color: #333;
}

p {
    font-size: 18px;
    color: #666;
}
```

6. Press `CTRL + X`, then `Y`, and `Enter` to save and exit the editor.

7. To apply the changes, restart the Apache server:

```bash
sudo systemctl restart apache2
```

8. Finally, run the following command (outside the VM terminal) to retrieve the VM's IP address.

```bash
gcloud compute instances list --format="table(name, networkInterfaces[0].accessConfigs[0].natIP)" --project PROJECT_ID
```

Paste the IP address in a browser and you should see the page rendered as follows:

![Rendered web page using Apache2](/assets/posts/ssh/webpage.png)



> To avoid incurring unnecessary charges to your account, it's recommended to delete a VM instance if you no longer need it.

To delete a VM instance on your Google Cloud console, do the following:

1. Navigate to the [VM instances page](https://console.cloud.google.com/compute/instances).
2. Click on the VM instance.
3. In the menu that pops up, click **Delete**.

## Conclusion

SSH is a powerful tool with numerous applications in computer programming. Whether you're managing a server, deploying applications, or troubleshooting issues, SSH is an essential skill for working with remote systems securely and efficiently.

In this article, you've learned what SSH is, how it works, and how to use it effectively. I hope this guide serves as a solid foundation as you continue exploring the world of computer networking.

As an exercise, consider setting up an SSL certificate for an Apache web server or deploying your own custom website to a virtual machine.


Introduction to SSH and How to Login Into A Remote Linux Virtual Machine

Step 3 - SSH into the VM using private key

## Introduction

Tailwind CSS is a utility-first CSS framework that lets you build custom designs directly in your markup, without writing a single line of custom CSS. Instead of predefined component classes like Bootstrap's `btn` or `card`, Tailwind gives you low-level utility classes, like `flex`, `pt-4`, `text-center`, that you compose to build any design you want.

The result is a faster development workflow, smaller production CSS bundles, and no context-switching between your HTML and a stylesheet.

In this guide, you'll learn how to set up Tailwind CSS v4 in a Next.js 15 project, understand how its core concepts work, common patterns, and best practices to follow.

> This guide covers Tailwind CSS v4, released in early 2025. If you're on an older project using v3, the setup steps are different. Check the [Tailwind v3 docs](https://v3.tailwindcss.com) for that.

## Setting up Tailwind CSS in Next.js

There are two ways to get Tailwind running in a Next.js project: letting `create-next-app` handle it automatically, or adding it manually to an existing project.

### Option 1 - New project with `create-next-app`

The easiest way to start is with the official Next.js scaffolding tool. Run the following command and answer `Yes` when it asks about Tailwind CSS:

```bash
npx create-next-app@latest my-app
```
In the setup prompts, answer `Yes` when asked if you want to use Tailwind CSS:

```bash
Would you like to use Tailwind CSS? › Yes
```

Then the CLI automatically installs Tailwind and configures everything for you.

### Option 2 - Adding Tailwind to an existing project

If you're adding Tailwind to an existing Next.js project, install it along with the PostCSS plugin:

```bash
npm install tailwindcss @tailwindcss/postcss postcss
```

Next, create a `postcss.config.js` file in the root of your project:

```js
// postcss.config.js
const config = {
    plugins: {
        '@tailwindcss/postcss': {},
    },
};

export default config;
```

Finally, open your global stylesheet (`app/globals.css` or `styles/globals.css`) and replace its contents with a single import:

```css
@import "tailwindcss";
```

> That single line replaces the three directives (`@tailwind base`, `@tailwind components`, `@tailwind utilities`) used in Tailwind v3. Tailwind v4 automatically detects your project files, so there's no `content` array to configure.

Restart your dev server and Tailwind is ready to use.

## How Tailwind works

Tailwind scans your project files for utility class names, generates only the CSS those classes need, and injects it into your stylesheet. In production, this means your CSS bundle contains only the styles you actually use, often just a few kilobytes.

Here's a quick example of Tailwind in action. In `app/page.tsx`, replace the contents with:

```tsx
export default function Home() {
    return (
        <main className="min-h-screen bg-gray-950 flex items-center justify-center">
            <div className="bg-emerald-700 text-white rounded-xl shadow-lg p-8 w-64 text-center">
                <h1 className="text-2xl font-bold mb-2">Hello, Tailwind!</h1>
                <p className="text-emerald-100 text-sm">Styled without a single line of CSS.</p>
            </div>
        </main>
    );
}
```

Run `npm run dev` and visit `http://localhost:3000`. You'll see a centered card with a dark background, built entirely with utility classes.

## Directives

Tailwind provides a set of custom at-rules called directives that give you control over how styles are generated and applied.

### `@import`

The `@import "tailwindcss"` directive is the entry point for Tailwind v4. It injects Tailwind's base reset, component layer, and utility classes into your stylesheet.

```css
@import "tailwindcss";
```

### `@apply`

`@apply` lets you use Tailwind utility classes inside custom CSS rules. This is useful when you want to keep your markup clean but still use Tailwind under the hood:

```css
.btn-primary {
    @apply px-4 py-2 bg-emerald-600 text-white rounded-lg font-medium;
    @apply hover:bg-emerald-700 transition-colors duration-200;
}
```

Use `@apply` sparingly. If you find yourself reaching for it often, it might be a sign to extract a reusable component instead.

### `@layer`

`@layer` tells Tailwind which layer your custom styles belong to: `base`, `components`, or `utilities`. This controls when your styles are applied relative to Tailwind's own styles.

```css
@layer base {
    h1 {
        @apply text-3xl font-bold tracking-tight;
    }

    a {
        @apply text-emerald-500 hover:underline;
    }
}

@layer components {
    .card {
        @apply bg-white rounded-xl shadow-md p-6;
    }
}
```

### `@utility`

`@utility` is new in Tailwind v4. It's the recommended way to define custom utility classes that work just like Tailwind's built-in ones, including support for variants like `hover:`, `md:`, and `dark:`:

```css
@utility flex-center {
    display: flex;
    justify-content: center;
    align-items: center;
}

@utility text-balance {
    text-wrap: balance;
}
```

Once defined, you can use these utilities exactly like any other Tailwind class:

```tsx
<div className="flex-center min-h-screen">
    <h1 className="text-balance text-4xl font-bold">Hello World</h1>
</div>
```

## Theme customization

In Tailwind v4, theme customization happens in your CSS file using the `@theme` directive, not in a JavaScript config file. This is one of the biggest changes from v3.

### What are theme variables?

Theme variables are CSS custom properties defined inside an `@theme` block. They serve two purposes at once: they generate Tailwind utility classes, and they're available as regular CSS variables anywhere in your stylesheet.

```css
@import "tailwindcss";

@theme {
    --color-primary: #a6dbc8;
    --font-sans: 'Inter', system-ui, sans-serif;
    --breakpoint-md: 768px;
}
```

After defining `--color-primary`, Tailwind generates the full set of color utilities: `bg-primary`, `text-primary`, `border-primary`, `ring-primary`, `fill-primary`, `stroke-primary`, and so on. The same variable is also available as `var(--color-primary)` in your own CSS.

### Why `@theme` and not `:root`?

You might wonder why Tailwind uses a special directive instead of just `:root`. The reason is that `:root` declarations are passive, they're just CSS variables with no special behavior. `@theme` tells Tailwind to actively process the variables and generate corresponding utility classes.

When Tailwind compiles your CSS, it reads the `@theme` block, understands the namespace of each variable (color, font, spacing, etc.), and generates the right utilities for each one. Variables in `:root` are invisible to this process.

### Theme variable namespaces

The variable namespace determines which utility classes get generated. Here's a reference for the most common ones:

| Namespace | Example variable | Generated utilities |
|-----------|-----------------|---------------------|
| `--color-*` | `--color-mint` | `bg-mint`, `text-mint`, `border-mint` |
| `--font-*` | `--font-sans` | `font-sans` |
| `--text-*` | `--text-lg` | `text-lg` |
| `--font-weight-*` | `--font-weight-bold` | `font-bold` |
| `--tracking-*` | `--tracking-wide` | `tracking-wide` |
| `--leading-*` | `--leading-relaxed` | `leading-relaxed` |
| `--breakpoint-*` | `--breakpoint-tablet` | `tablet:` prefix |
| `--spacing-*` | `--spacing-18` | `p-18`, `m-18`, `w-18`, `gap-18` |
| `--radius-*` | `--radius-card` | `rounded-card` |
| `--shadow-*` | `--shadow-card` | `shadow-card` |
| `--animate-*` | `--animate-spin` | `animate-spin` |
| `--ease-*` | `--ease-in` | `ease-in` |
| `--width-*` | `--width-sidebar` | `w-sidebar` |

### Extending the default theme

By default, your `@theme` block adds to Tailwind's built-in theme. You don't need to redefine anything that already exists:

```css
@import "tailwindcss";

@theme {
    /* Add a new brand color alongside Tailwind's existing colors */
    --color-mint: #a6dbc8;
    --color-mint-dark: #6fbfa8;

    /* Add a custom font */
    --font-sans: 'Inter', system-ui, sans-serif;
    --font-mono: 'JetBrains Mono', monospace;

    /* Add a custom breakpoint */
    --breakpoint-xs: 480px;

    /* Add a custom border radius */
    --radius-card: 0.75rem;
}
```

You can now use `bg-mint`, `xs:text-sm`, `rounded-card`, and `font-mono` alongside Tailwind's existing classes like `bg-blue-500` or `text-lg`.

### Overriding default values

To override a specific default value, define a variable with the same name:

```css
@theme {
    /* Override Tailwind's default sans font */
    --font-sans: 'Inter', system-ui, sans-serif;

    /* Override the default xl breakpoint */
    --breakpoint-xl: 1400px;
}
```

### Replacing the entire theme

To replace Tailwind's defaults completely and start from scratch, set `--*: initial` before your declarations:

```css
@theme {
    --*: initial;

    --color-white: #fff;
    --color-black: #000;
    --color-brand: #a6dbc8;

    --font-sans: 'Inter', system-ui, sans-serif;

    --breakpoint-sm: 640px;
    --breakpoint-md: 768px;
    --breakpoint-lg: 1024px;
}
```

This removes all of Tailwind's built-in colors, fonts, spacing, and breakpoints. Use this when you want full control over the design system with no defaults leaking in.

To disable only one namespace, target it specifically:

```css
@theme {
    /* Remove all default colors, keep everything else */
    --color-*: initial;

    --color-brand: #a6dbc8;
    --color-danger: #f87171;
}
```

### Custom animations

You can define custom keyframe animations directly inside `@theme`. Tailwind will generate the `animate-*` utility and inject the keyframes into your stylesheet:

```css
@theme {
    --animate-fade-in: fade-in 0.3s ease-out;

    @keyframes fade-in {
        from { opacity: 0; transform: translateY(8px); }
        to   { opacity: 1; transform: translateY(0); }
    }
}
```

Then use it like any other animation:

```tsx
<div className="animate-fade-in">Hello</div>
```

### `@theme inline`

Sometimes you want a CSS variable that references another CSS variable, rather than a static value. This is common when building dark mode or theming systems. Use `@theme inline` for this:

```css
@import "tailwindcss";

@theme {
    --color-primary: #a6dbc8;
    --color-secondary: #6fbfa8;
}

@theme inline {
    --color-surface: var(--color-primary);
}
```

Without `inline`, Tailwind would try to resolve `var(--color-primary)` at build time and fail. With `inline`, the variable stays as a live reference in the output, updating dynamically at runtime.

This is the right tool for semantic color tokens that change between light and dark mode:

```css
@theme inline {
    --color-text: var(--color-gray-900);
    --color-bg: var(--color-white);
}

@media (prefers-color-scheme: dark) {
    :root {
        --color-gray-900: #f5f5f5;
        --color-white: #0f0f0f;
    }
}
```

### Sharing theme variables across projects

If you work with multiple packages or apps that share a design system, you can extract your theme into a standalone CSS file and import it:

```css
/* packages/design-tokens/theme.css */
@theme {
    --color-brand: #a6dbc8;
    --color-brand-dark: #6fbfa8;
    --font-sans: 'Inter', system-ui, sans-serif;
    --radius-card: 0.75rem;
}
```

```css
/* apps/web/app/globals.css */
@import "tailwindcss";
@import "@your-org/design-tokens/theme.css";
```

Both apps get the same theme variables and the same generated utility classes.

### Using theme variables in custom CSS

Because `@theme` variables are real CSS custom properties, you can use them anywhere:

```css
@layer components {
    .card {
        background: var(--color-surface);
        border-radius: var(--radius-card);
        padding: var(--spacing-6);
        box-shadow: var(--shadow-md);
    }
}
```

You can also reference them in arbitrary values inside your JSX:

```tsx
<div className="bg-[var(--color-brand)] rounded-[var(--radius-card)]">
    Custom token, Tailwind syntax
</div>
```

### Using theme variables in JavaScript

To read theme values in JavaScript (for charting libraries, canvas, or animation), use `getComputedStyle`:

```ts
const styles = getComputedStyle(document.documentElement);
const brandColor = styles.getPropertyValue('--color-brand').trim();
const sans = styles.getPropertyValue('--font-sans').trim();
```

This always reflects the current computed value, including any runtime overrides from dark mode toggles or media queries.

If you need a JavaScript config file for tooling or IDE support, you can still create a `tailwind.config.ts` file:

```ts
import type { Config } from 'tailwindcss';

const config: Config = {
    theme: {
        extend: {
            colors: {
                primary: '#a6dbc8',
            },
        },
    },
};

export default config;
```

## Responsive design

Tailwind uses a mobile-first approach to responsive design. You add breakpoint prefixes to any utility class to apply it at a specific screen width and above.

The default breakpoints are:

| Prefix | Minimum width |
|--------|--------------|
| `sm` | 640px |
| `md` | 768px |
| `lg` | 1024px |
| `xl` | 1280px |
| `2xl` | 1536px |

```tsx
<div className="flex flex-col md:flex-row gap-4">
    <aside className="w-full md:w-64 bg-gray-800 p-4 rounded-lg">
        Sidebar
    </aside>
    <main className="flex-1 bg-gray-900 p-6 rounded-lg">
        Main content
    </main>
</div>
```

In this example, the layout stacks vertically on mobile and switches to a side-by-side row on medium screens and above.

To add custom breakpoints in v4, define them in your `@theme` block:

```css
@theme {
    --breakpoint-tablet: 900px;
}
```

Then use `tablet:` as a prefix in your markup:

```tsx
<h1 className="text-2xl tablet:text-5xl font-bold">Hello</h1>
```

## Dark mode

Tailwind supports dark mode with the `dark:` variant. By default, it follows the user's system preference via the `prefers-color-scheme` media query.

```tsx
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100 p-6 rounded-xl">
    <h2 className="text-xl font-semibold">This card adapts to dark mode</h2>
    <p className="text-gray-600 dark:text-gray-400 mt-2">
        The colors change automatically based on the user's system theme.
    </p>
</div>
```

If you want to control dark mode manually (for example, with a toggle button), configure it in your CSS:

```css
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));
```

Then toggle the `dark` class on your `<html>` element using JavaScript:

```ts
document.documentElement.classList.toggle('dark');
```

## Arbitrary values

Sometimes you need a specific value that doesn't exist in Tailwind's default scale. Rather than reaching for custom CSS, you can use arbitrary values with square bracket notation:

```tsx
<div className="w-[340px] h-[200px] bg-[#1a1a2e] rounded-[10px]">
    <p className="text-[15px] leading-[1.8] text-[#e0e0ff]">
        Custom sizing without leaving your markup.
    </p>
</div>
```

Arbitrary values work with any utility in Tailwind, including spacing, colors, font sizes, grid columns, and more:

```tsx
<div className="grid grid-cols-[1fr_320px] gap-[48px]">
    <main>Content</main>
    <aside>Sidebar</aside>
</div>
```

## Composing components

One of the strongest arguments for Tailwind is how it handles component extraction. Instead of writing CSS, you extract reusable logic into a component.

Here's the pattern: start with inline classes, and when you find yourself copying them, pull them into a component:

```tsx
// Before: repeated markup
<button className="px-4 py-2 bg-emerald-600 text-white rounded-lg font-medium hover:bg-emerald-700 transition-colors">
    Save
</button>
<button className="px-4 py-2 bg-emerald-600 text-white rounded-lg font-medium hover:bg-emerald-700 transition-colors">
    Submit
</button>

// After: extracted component
const Button = ({ children }: { children: React.ReactNode }) => (
    <button className="px-4 py-2 bg-emerald-600 text-white rounded-lg font-medium hover:bg-emerald-700 transition-colors">
        {children}
    </button>
);
```

This keeps Tailwind classes co-located with the component they style, which is easier to maintain than a separate CSS file.

For more complex components with conditional styles, use the `clsx` or `cva` libraries:

```bash
npm install clsx class-variance-authority
```

```tsx
import { cva } from 'class-variance-authority';

const button = cva(
    'px-4 py-2 rounded-lg font-medium transition-colors',
    {
        variants: {
            intent: {
                primary: 'bg-emerald-600 text-white hover:bg-emerald-700',
                secondary: 'bg-gray-800 text-gray-100 hover:bg-gray-700',
                danger: 'bg-red-600 text-white hover:bg-red-700',
            },
            size: {
                sm: 'text-sm px-3 py-1.5',
                md: 'text-base px-4 py-2',
                lg: 'text-lg px-6 py-3',
            },
        },
        defaultVariants: {
            intent: 'primary',
            size: 'md',
        },
    }
);

<button className={button({ intent: 'secondary', size: 'lg' })}>
    Click me
</button>
```

## Class sorting with Prettier

One practical problem with utility-first CSS is that class lists can get long and inconsistent. Different developers order classes differently, which makes diffs noisy and code harder to scan.

Tailwind maintains an official [Prettier plugin](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) that automatically sorts your classes following Tailwind's [recommended class order](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier#how-classes-are-sorted). It runs on save, works with custom Tailwind configurations, and since it's just a Prettier plugin, it works in every editor that supports Prettier.

Install it alongside Prettier:

```bash
npm install -D prettier prettier-plugin-tailwindcss
```

Then add it to your `prettier.config.js`:

```js
// prettier.config.js
export default {
    plugins: ['prettier-plugin-tailwindcss'],
};
```

Here's what the sorting looks like in practice:

```html

<button class="text-white px-4 sm:px-8 py-2 sm:py-3 bg-sky-700 hover:bg-sky-800">
    Submit
</button>


<button class="bg-sky-700 px-4 py-2 text-white hover:bg-sky-800 sm:px-8 sm:py-3">
    Submit
</button>
```

The plugin groups classes by category (layout, spacing, typography, background, interactivity) and puts responsive variants at the end. Once you have it running, you stop thinking about class order entirely.

## Conclusion

Tailwind CSS v4 is the most productive way to style a Next.js application today. The setup is minimal, the utility classes are predictable, and the CSS output is lean. Once you're past the initial learning curve of memorizing class names, which happens faster than you'd expect, you'll find it hard to go back to writing plain CSS or using component libraries.

The concepts covered here are enough to build real production UIs. As you grow more comfortable, explore the [Tailwind CSS documentation](https://tailwindcss.com/docs) for advanced features like container queries, 3D transforms, and the full list of available utilities.

## Resources

1. [Tailwind CSS Docs](https://tailwindcss.com/docs)
2. [Tailwind CSS v4 Migration Guide](https://tailwindcss.com/docs/upgrade-guide)
3. [class-variance-authority](https://cva.style/docs)
4. [clsx](https://github.com/lukeed/clsx)
5. [Tailwind CSS IntelliSense for VS Code](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
6. [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)

Getting Started with Tailwind CSS in Next.js

Option 1 - New project with create-next-app

Option 2 - Adding Tailwind to an existing project