DEV Community: Abhishek Singh

Setting Up Next.js 15 with Tailwind v4 and shadcn/ui — What Actually Changed

Abhishek Singh — Tue, 31 Mar 2026 18:14:30 +0000

I recently set up a new project with Next.js 15 (App Router), Tailwind CSS v4, and shadcn/ui. If you're coming from Tailwind v3, some things have changed and the official docs don't always make it obvious what breaks.

Here's what I ran into and how I got everything working.

Initial setup

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir
cd my-app

As of Next.js 15, create-next-app installs Tailwind v4 by default. This is where the differences start.

What changed in Tailwind v4

No more tailwind.config.js

This was the biggest surprise. Tailwind v4 uses CSS-based configuration instead of a JavaScript config file. Your customization now lives in your CSS file:

/* src/app/globals.css */
@import "tailwindcss";

@theme {
  --color-brand: #2563eb;
  --color-brand-dark: #1d4ed8;
  --color-surface: #0f0f0f;
  --color-surface-light: #1a1a1a;
  --color-border: #2a2a2a;

  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  --radius-lg: 12px;
  --radius-md: 8px;
  --radius-sm: 4px;
}

No more theme.extend.colors in a JS file. Everything is CSS custom properties now. Honestly, once I got used to it, this feels cleaner.

@import instead of @tailwind directives

Old way (v3):

@tailwind base;
@tailwind components;
@tailwind utilities;

New way (v4):

@import "tailwindcss";

That's it. One line.

Setting up shadcn/ui

This is where I ran into issues. Running the init command:

npx shadcn@latest init

It asks you a bunch of questions. Pick these:

Style: Default
Base color: Neutral (or whatever you prefer)
CSS variables: Yes

After init, it creates a components.json and updates your globals.css with CSS variables for the theme.

The CSS variables shadcn adds

shadcn/ui injects its color system using CSS variables. In v4, it looks like this in your globals.css:

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-ring: var(--ring);
  /* ...more variables */
}

Then the actual color values are defined per theme:

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* ...etc */
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  /* ...etc */
}

Notice they use oklch color space now instead of hsl. This gives more perceptually uniform colors.

Adding components

npx shadcn@latest add button card input dialog

Components go into src/components/ui/. Each one is a standalone file you can edit directly — that's the whole point of shadcn. It's not a package in node_modules, it's code you own.

Dark mode setup

With Next.js App Router and Tailwind v4, here's the minimal dark mode setup:

npm install next-themes

// src/components/theme-provider.tsx
"use client";

import { ThemeProvider as NextThemesProvider } from "next-themes";

export function ThemeProvider({
  children,
  ...props
}: React.ComponentProps<typeof NextThemesProvider>) {
  return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
}

// src/app/layout.tsx
import { ThemeProvider } from "@/components/theme-provider";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="dark"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

The suppressHydrationWarning on <html> is needed because next-themes adds the theme class on the client side, which creates a hydration mismatch. This is expected and the warning is safe to suppress.

Building a dashboard card

Here's a practical example combining everything — a stats card for a dashboard:

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { TrendingUp, TrendingDown } from "lucide-react";

interface StatCardProps {
  title: string;
  value: string;
  change: number;
  period: string;
}

export function StatCard({ title, value, change, period }: StatCardProps) {
  const isPositive = change >= 0;

  return (
    <Card>
      <CardHeader className="flex flex-row items-center justify-between pb-2">
        <CardTitle className="text-sm font-medium text-muted-foreground">
          {title}
        </CardTitle>
        {isPositive ? (
          <TrendingUp className="h-4 w-4 text-green-500" />
        ) : (
          <TrendingDown className="h-4 w-4 text-red-500" />
        )}
      </CardHeader>
      <CardContent>
        <div className="text-2xl font-bold">{value}</div>
        <p className="text-xs text-muted-foreground mt-1">
          <span className={isPositive ? "text-green-500" : "text-red-500"}>
            {isPositive ? "+" : ""}{change}%
          </span>
          {" "}from {period}
        </p>
      </CardContent>
    </Card>
  );
}

Usage:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
  <StatCard title="Total Orders" value="1,234" change={12.5} period="last month" />
  <StatCard title="Revenue" value="₹4,56,789" change={8.2} period="last month" />
  <StatCard title="Active Users" value="892" change={-3.1} period="last week" />
  <StatCard title="Conversion" value="3.2%" change={0.8} period="last month" />
</div>

Things that caught me off guard

1. cn() utility is essential

shadcn generates a lib/utils.ts with a cn() function that merges Tailwind classes properly. Always use it when combining conditional classes:

import { cn } from "@/lib/utils";

<div className={cn(
  "rounded-lg border p-4",
  isActive && "border-primary bg-primary/10",
  isDisabled && "opacity-50 cursor-not-allowed"
)} />

Without cn(), conflicting Tailwind classes don't resolve correctly. I had a bug where bg-red-500 wasn't overriding bg-blue-500 because of class order. cn() handles this using tailwind-merge under the hood.

2. withOpacity is deprecated

If you're upgrading from an older project, color.withOpacity(0.5) is deprecated in Flutter — wait, wrong framework. In Tailwind v4, the opacity modifier syntax changed slightly. Use bg-primary/10 for 10% opacity, which still works the same way.

3. Server Components and "use client"

shadcn/ui components that use useState, useEffect, or event handlers need the "use client" directive. The shadcn CLI adds this automatically, but if you create wrapper components, don't forget it. I spent 20 minutes debugging a dialog that wouldn't open because my wrapper was missing "use client".

4. Import paths

shadcn uses @/components/ui/button style imports. Make sure your tsconfig.json has the path alias:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

create-next-app sets this up automatically, but if you're adding shadcn to an existing project, check this first.

Is Tailwind v4 worth upgrading?

For new projects — yes, absolutely. The CSS-based config is cleaner, the build is faster, and oklch colors look better.

For existing v3 projects — wait until your dependencies (shadcn, other UI libraries) fully support v4. The migration isn't painful but there's no rush if everything works.

I'm Abhishek, a full-stack developer building SaaS products and mobile apps with Flutter, Next.js, and Node.js. I write about what I learn while building real projects.

How I Built Secure Firebase Cloud Functions with Admin Permissions and Rate Limiting

Abhishek Singh — Tue, 31 Mar 2026 18:06:50 +0000

If you're building an admin panel that talks to Firebase Cloud Functions, you need two things before anything else — permission checks and rate limiting. Without these, any authenticated user could call your admin endpoints, and a single bad actor could spam your functions into hitting billing limits.

Here's how I set this up in a real admin panel, not a tutorial demo.

The problem

I was building an admin panel for a mobile app. The admin needed to send push notifications, search users, and moderate content. All of these were Cloud Functions callable from the client.

The issue? Firebase callable functions don't have built-in admin role checks. Any authenticated user can call any callable function by default. That's terrifying.

Step 1: Store admin roles in Firestore

I keep a simple admins collection in Firestore:

// Firestore structure
// admins/{uid}
{
  email: "admin@example.com",
  role: "super_admin", // or "moderator", "viewer"
  permissions: ["send_notifications", "manage_users", "view_analytics"],
  createdAt: Timestamp
}

Step 2: The permission verification helper

Every admin Cloud Function calls this before doing anything:

import * as functions from "firebase-functions";
import * as admin from "firebase-admin";

interface AdminData {
  uid: string;
  role: string;
  permissions: string[];
}

async function verifyAdminPermission(
  context: functions.https.CallableContext,
  requiredPermission: string
): Promise<AdminData> {
  // Check if user is authenticated at all
  if (!context.auth) {
    throw new functions.https.HttpsError(
      "unauthenticated",
      "You must be logged in."
    );
  }

  const uid = context.auth.uid;

  // Check if user exists in admins collection
  const adminDoc = await admin
    .firestore()
    .collection("admins")
    .doc(uid)
    .get();

  if (!adminDoc.exists) {
    throw new functions.https.HttpsError(
      "permission-denied",
      "You are not an admin."
    );
  }

  const adminData = adminDoc.data() as AdminData;

  // Check specific permission
  if (
    adminData.role !== "super_admin" &&
    !adminData.permissions.includes(requiredPermission)
  ) {
    throw new functions.https.HttpsError(
      "permission-denied",
      `You don't have the "${requiredPermission}" permission.`
    );
  }

  return { uid, ...adminData };
}

The key design decision — super_admin bypasses all permission checks. Everyone else needs the specific permission listed in their Firestore document. This way I can have moderators who can only view reports but can't send notifications.

Step 3: Rate limiting with Firestore

I didn't want to add Redis or any external service just for rate limiting. Firestore works fine for admin-level traffic (not high-throughput APIs, but admin panels with a few users):

async function applyRateLimit(
  uid: string,
  action: string,
  maxRequests: number,
  windowMs: number
): Promise<void> {
  const now = Date.now();
  const windowStart = now - windowMs;

  const rateLimitRef = admin
    .firestore()
    .collection("rateLimits")
    .doc(`${uid}_${action}`);

  const doc = await rateLimitRef.get();

  if (doc.exists) {
    const data = doc.data()!;
    // Filter out old timestamps outside the window
    const recentRequests = (data.timestamps as number[]).filter(
      (t) => t > windowStart
    );

    if (recentRequests.length >= maxRequests) {
      throw new functions.https.HttpsError(
        "resource-exhausted",
        `Rate limit exceeded. Max ${maxRequests} requests per ${windowMs / 1000} seconds.`
      );
    }

    // Add current timestamp
    await rateLimitRef.update({
      timestamps: [...recentRequests, now],
    });
  } else {
    // First request
    await rateLimitRef.set({
      timestamps: [now],
    });
  }
}

Is this the most efficient rate limiter ever? No. But for an admin panel with 3-5 users, it works perfectly and costs basically nothing.

Step 4: Putting it together

Here's what a real admin Cloud Function looks like with both helpers:

export const sendAdminNotification = functions.https.onCall(
  async (data, context) => {
    // 1. Verify admin has notification permission
    const adminUser = await verifyAdminPermission(
      context,
      "send_notifications"
    );

    // 2. Rate limit: max 10 notifications per minute
    await applyRateLimit(adminUser.uid, "send_notification", 10, 60000);

    // 3. Validate input
    const { title, body, sendMode, filters } = data;

    if (!title || !body) {
      throw new functions.https.HttpsError(
        "invalid-argument",
        "Title and body are required."
      );
    }

    // 4. Build the query based on send mode
    let tokens: string[] = [];

    if (sendMode === "broadcast") {
      const usersSnapshot = await admin
        .firestore()
        .collection("users")
        .where("fcmToken", "!=", null)
        .get();
      tokens = usersSnapshot.docs.map((doc) => doc.data().fcmToken);
    } else if (sendMode === "filtered") {
      let query: admin.firestore.Query = admin
        .firestore()
        .collection("users");

      if (filters?.gender) {
        query = query.where("gender", "==", filters.gender);
      }
      if (filters?.city) {
        query = query.where("city", "==", filters.city);
      }
      if (filters?.tier) {
        query = query.where("tier", "==", filters.tier);
      }

      const snapshot = await query.get();
      tokens = snapshot.docs
        .map((doc) => doc.data().fcmToken)
        .filter(Boolean);
    }

    // 5. Send via FCM (batch if over 500)
    const batchSize = 500;
    let successCount = 0;
    let failureCount = 0;

    for (let i = 0; i < tokens.length; i += batchSize) {
      const batch = tokens.slice(i, i + batchSize);
      const response = await admin.messaging().sendEachForMulticast({
        tokens: batch,
        notification: { title, body },
      });
      successCount += response.successCount;
      failureCount += response.failureCount;
    }

    // 6. Log the notification for history
    await admin.firestore().collection("notificationHistory").add({
      title,
      body,
      sendMode,
      filters: filters || null,
      sentBy: adminUser.uid,
      totalTargeted: tokens.length,
      successCount,
      failureCount,
      sentAt: admin.firestore.FieldValue.serverTimestamp(),
    });

    return { successCount, failureCount, totalTargeted: tokens.length };
  }
);

Organizing Cloud Functions

When you have 10+ admin functions, a single index.ts file becomes unreadable. I split them into a folder structure:

functions/
  src/
    admin/
      notifications.ts    // sendAdminNotification, estimateAudience
      users.ts            // searchUsers, moderateUser
      analytics.ts        // getDashboardStats
      index.ts            // barrel file - re-exports everything
    index.ts              // main entry - exports from ./admin

The barrel file keeps imports clean:

// functions/src/admin/index.ts
export { sendAdminNotification, estimateAudience } from "./notifications";
export { searchUsers, moderateUser } from "./users";
export { getDashboardStats } from "./analytics";

// functions/src/index.ts
export * from "./admin";

Mistakes I made

1. Forgetting to handle expired FCM tokens

First time I sent a broadcast, 30% of tokens were stale. Firebase doesn't clean them for you. Now I delete tokens that return messaging/registration-token-not-registered errors after each send.

2. Not batching Firestore reads

I was doing individual getDoc() calls in a loop to check user profiles. Switched to a single where() query — went from 3 seconds to 200ms for 500 users.

3. Rate limit document growing forever

My first rate limiter appended timestamps but never cleaned old ones. After a month, each document had thousands of entries. The filter step in applyRateLimit above fixes this — it only keeps timestamps within the current window.

When to use this pattern

This setup works when:

You have a small number of admin users (under 50)
You want role-based permissions without adding a third-party auth service
Your rate limiting needs are basic (not thousands of requests per second)

If you need high-throughput rate limiting, use Redis. If you need complex RBAC, use a proper auth provider. But for most admin panels, Firestore-based checks are simple, free, and good enough.

I'm Abhishek, a full-stack developer building SaaS products and mobile apps with Flutter, Next.js, and Node.js. I write about practical patterns from real projects.

How I Manage Complex State in Flutter with Riverpod StateNotifier

Abhishek Singh — Tue, 31 Mar 2026 17:59:48 +0000

I've been building a Flutter admin panel that handles push notifications, user filtering, audience estimation, and real-time Firestore data. At first I tried setState and Provider, but things got messy fast — especially when multiple screens needed to share and update the same state.

Switching to Riverpod with StateNotifier cleaned up everything. Here's how I structure it in production, not just todo app examples.

Why StateNotifier over other options?

I tried a few approaches before landing on StateNotifier:

setState — works for simple screens but becomes a nightmare when you have filters on one screen affecting data on another
Provider (vanilla) — better, but ChangeNotifier gets messy with multiple fields. You end up calling notifyListeners() everywhere and losing track of what changed
Bloc — honestly felt like overkill for my use case. Too much boilerplate for what I needed
Riverpod + StateNotifier — immutable state updates, no BuildContext dependency, easy to test. This clicked for me

Setting up a real example

Let me show you how I built a notification composer that has debounced audience estimation. When an admin selects filters (gender, city, tier, etc.), the app waits 500ms after they stop selecting, then calls a Cloud Function to estimate how many users match.

The state class

import 'package:freezed_annotation/freezed_annotation.dart';

part 'notification_state.freezed.dart';

@freezed
class NotificationState with _$NotificationState {
  const factory NotificationState({
    @Default('broadcast') String sendMode,
    @Default('') String title,
    @Default('') String body,
    @Default(null) String? selectedGender,
    @Default(null) String? selectedCity,
    @Default(null) String? selectedTier,
    @Default(false) bool excludeFakeUsers,
    @Default(null) int? lastActiveDays,
    @Default(false) bool isEstimating,
    @Default(null) int? estimatedAudience,
    @Default(false) bool isSending,
    @Default(null) String? errorMessage,
  }) = _NotificationState;
}
I use Freezed here because writing copyWith manually for 12+ fields is painful. One time I forgot to copy a field and spent 30 minutes debugging why my filter kept resetting. Never again.

The StateNotifier

import 'dart:async';
import 'package:flutter_riverpod/flutter_riverpod.dart';

class NotificationNotifier extends StateNotifier<NotificationState> {
  NotificationNotifier(this._ref) : super(const NotificationState());

  final Ref _ref;
  Timer? _debounceTimer;

  void setSendMode(String mode) {
    state = state.copyWith(
      sendMode: mode,
      selectedGender: null,
      selectedCity: null,
      selectedTier: null,
      estimatedAudience: null,
    );
  }

  void updateTitle(String title) {
    state = state.copyWith(title: title);
  }

  void updateBody(String body) {
    state = state.copyWith(body: body);
  }

  void setGenderFilter(String? gender) {
    state = state.copyWith(selectedGender: gender);
    _debouncedEstimate();
  }

  void setCityFilter(String? city) {
    state = state.copyWith(selectedCity: city);
    _debouncedEstimate();
  }

  void setTierFilter(String? tier) {
    state = state.copyWith(selectedTier: tier);
    _debouncedEstimate();
  }

  void setExcludeFakeUsers(bool exclude) {
    state = state.copyWith(excludeFakeUsers: exclude);
    _debouncedEstimate();
  }

  void _debouncedEstimate() {
    _debounceTimer?.cancel();
    _debounceTimer = Timer(const Duration(milliseconds: 500), () {
      _estimateAudience();
    });
  }

  Future<void> _estimateAudience() async {
    if (state.sendMode == 'broadcast') return;

    state = state.copyWith(isEstimating: true, errorMessage: null);

    try {
      final filters = {
        if (state.selectedGender != null) 'gender': state.selectedGender,
        if (state.selectedCity != null) 'city': state.selectedCity,
        if (state.selectedTier != null) 'tier': state.selectedTier,
        'excludeFakeUsers': state.excludeFakeUsers,
        if (state.lastActiveDays != null) 'lastActiveDays': state.lastActiveDays,
      };

      final result = await _ref.read(cloudFunctionsProvider).call(
        'estimateAudience',
        parameters: filters,
      );

      if (mounted) {
        state = state.copyWith(
          isEstimating: false,
          estimatedAudience: result.data['count'] as int,
        );
      }
    } catch (e) {
      if (mounted) {
        state = state.copyWith(
          isEstimating: false,
          errorMessage: 'Failed to estimate audience',
        );
      }
    }
  }

  Future<void> sendNotification() async {
    if (state.title.isEmpty || state.body.isEmpty) {
      state = state.copyWith(errorMessage: 'Title and body are required');
      return;
    }

    state = state.copyWith(isSending: true, errorMessage: null);

    try {
      await _ref.read(cloudFunctionsProvider).call(
        'sendAdminNotification',
        parameters: {
          'title': state.title,
          'body': state.body,
          'sendMode': state.sendMode,
          if (state.selectedGender != null) 'gender': state.selectedGender,
          if (state.selectedCity != null) 'city': state.selectedCity,
          if (state.selectedTier != null) 'tier': state.selectedTier,
          'excludeFakeUsers': state.excludeFakeUsers,
        },
      );

      state = const NotificationState();
    } catch (e) {
      state = state.copyWith(
        isSending: false,
        errorMessage: 'Failed to send notification: $e',
      );
    }
  }

  @override
  void dispose() {
    _debounceTimer?.cancel();
    super.dispose();
  }
}

final notificationProvider =
    StateNotifierProvider<NotificationNotifier, NotificationState>((ref) {
  return NotificationNotifier(ref);
});
Using it in the UI
The nice thing about Riverpod is you can watch specific fields. Your widget only rebuilds when the field it cares about changes:


class AudienceEstimateWidget extends ConsumerWidget {
  const AudienceEstimateWidget({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final isEstimating = ref.watch(
      notificationProvider.select((s) => s.isEstimating),
    );
    final count = ref.watch(
      notificationProvider.select((s) => s.estimatedAudience),
    );

    if (isEstimating) {
      return const CircularProgressIndicator();
    }

    if (count != null) {
      return Text(
        'Estimated audience: $count users',
        style: const TextStyle(
          fontWeight: FontWeight.w600,
          fontSize: 16,
        ),
      );
    }

    return const Text('Select filters to see audience estimate');
  }
}
The .select() is important — without it, this widget would rebuild every time ANY field in the state changes (like when the user types in the title field). With .select(), it only rebuilds when isEstimating or estimatedAudience changes.

Filter dropdowns

class GenderFilterDropdown extends ConsumerWidget {
  const GenderFilterDropdown({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final selected = ref.watch(
      notificationProvider.select((s) => s.selectedGender),
    );

    return DropdownButtonFormField<String>(
      value: selected,
      decoration: const InputDecoration(labelText: 'Gender'),
      items: const [
        DropdownMenuItem(value: null, child: Text('All')),
        DropdownMenuItem(value: 'male', child: Text('Male')),
        DropdownMenuItem(value: 'female', child: Text('Female')),
        DropdownMenuItem(value: 'other', child: Text('Other')),
      ],
      onChanged: (value) {
        ref.read(notificationProvider.notifier).setGenderFilter(value);
      },
    );
  }
}

Things that tripped me up

Checking mounted before updating state

If your Cloud Function takes 2-3 seconds and the user navigates away, calling state = state.copyWith(...) on a disposed notifier crashes the app. Always check mounted before updating state after async operations.

Debounce timer not getting cancelled

Forgetting to cancel the timer in dispose() causes weird bugs — like the estimation running after you've already left the screen. Took me a while to figure out why I was getting random errors in the console.

DropdownButtonFormField value vs initialValue

This is a Flutter thing, not Riverpod, but it got me. If you use value property, Flutter manages the display. If you switch to initialValue, it only sets it once on build. When your state updates the selected filter, you want value so the dropdown reflects the current state. I kept using initialValue and wondering why my dropdowns weren't updating.

Don't put heavy logic in build()

I initially had the debounce logic inside the widget. Every rebuild created a new Timer. Moving it into the StateNotifier fixed it. Keep your widgets dumb — they should only read state and call notifier methods.

When NOT to use StateNotifier
For simple screens with 1-2 fields that don't share state with anything else — just use useState hook (with hooks_riverpod) or even plain setState. Not everything needs this pattern. I use StateNotifier when:

The state has 5+ fields

Multiple widgets need to read/write the same state
There's async logic (API calls, debouncing)
I want to test the logic without a widget
For a simple toggle or text input that lives in one widget? setState is fine. Don't over-engineer it.

Wrapping up
Riverpod + StateNotifier gives you a clean separation between your UI and business logic. The state is immutable (no accidental mutations), the logic is testable (no widget dependency), and the rebuilds are efficient (with .select()).

If you're building anything more complex than a single-screen app in Flutter, give this pattern a try. It might feel like extra boilerplate at first, but the moment you need to debug a state issue across multiple screens, you'll be glad everything is in one predictable place.