### Install Dependencies Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/CONTRIBUTING.md Install all the necessary project dependencies using npm. ```bash npm install ``` -------------------------------- ### Root Layout Example with PreferencesStoreProvider Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/03-preferences-system.md Example of how to use the `PreferencesStoreProvider` in the root layout of a Next.js application to set initial preferences. ```typescript // In root layout export default function RootLayout({ children, params, }: { children: React.ReactNode; params: Promise<{themeMode: ThemeMode}>; }) { return ( {children} ); } ``` -------------------------------- ### Font Management Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Illustrates how to get the current font setting, set a new font, and apply it globally. This example assumes `setFont` and `applyFont` functions are correctly implemented and accessible. ```typescript const font = usePreferencesStore(s => s.font); setFont("inter"); applyFont("inter"); ``` -------------------------------- ### Run Development Server Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/CONTRIBUTING.md Start the local development server to view the application. The app will be accessible at http://localhost:3000. ```bash npm run dev ``` -------------------------------- ### Add New Navigation Item Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/07-navigation.md Examples demonstrating how to define new navigation items, including a standard item, a 'coming soon' item, and an item with sub-navigation. ```typescript // Example: Adding a new dashboard { title: "Reports", url: "/dashboard/reports", icon: BarChart3, isNew: true, } // Example: Adding coming soon item { title: "Settings", url: "/dashboard/coming-soon", icon: Settings, comingSoon: true, } // Example: Item with sub-navigation { title: "Tools", url: "/tools", icon: Wrench, subItems: [ { title: "Tool 1", url: "/tools/1" }, { title: "Tool 2", url: "/tools/2" }, ], } ``` -------------------------------- ### Accessing Simple Icons Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/06-components.md Provides an example of how to import and access various icons from the Simple Icons library. ```typescript import * as SimpleIcons from "simple-icons"; // Example icons: // siGithub, siTwitter, siLinkedin, siInstagram, siYoutube, etc. const icon = SimpleIcons[`si${providerName}`]; ``` -------------------------------- ### Create Preferences Store Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/03-preferences-system.md Shows how to create a Zustand store instance for managing preferences state. It allows for initial state overrides. ```typescript import { createPreferencesStore } from "@/stores/preferences/preferences-store"; const store = createPreferencesStore({ themeMode: "dark", themePreset: "brutalist", font: "inter", }); // Get state const state = store.getState(); // Subscribe to changes const unsubscribe = store.subscribe( (state) => console.log("Theme changed:", state.themeMode) ); ``` -------------------------------- ### Sidebar Navigation Structure Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/07-navigation.md An example illustrating the structure of the `sidebarItems` constant, which is an array of `NavGroup` objects. This defines the complete navigation hierarchy for the sidebar. ```typescript export const sidebarItems: NavGroup[] [ { id: 1, label: "Dashboards", items: [ { title: "Default", url: "/dashboard/default", icon: LayoutDashboard, }, // ... more dashboard items ], }, { id: 2, label: "Pages", items: [ // ... page navigation items ], }, // ... more groups ] ``` -------------------------------- ### SimpleIcon Usage Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/06-components.md Demonstrates rendering GitHub and Twitter icons using the SimpleIcon component with custom size and hover effects. ```typescript import { SimpleIcon } from "@/components/simple-icon"; import { siGithub, siTwitter } from "simple-icons"; export function SocialLinks() { return (
); } ``` -------------------------------- ### Theme Mode and Persistence Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Demonstrates how to access and set the theme mode using the preferences store and persist the change. Ensure the `persistPreference` function is available in your scope. ```typescript const themeMode = usePreferencesStore(s => s.themeMode); setThemeMode("dark"); await persistPreference("theme_mode", "dark"); ``` -------------------------------- ### Usage Example: getPreference Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Demonstrates using getPreference to safely retrieve 'theme_mode' and 'sidebar_variant' preferences, providing fallback values and type safety. ```typescript import { getPreference } from "@/server/server-actions"; import { THEME_MODE_VALUES } from "@/lib/preferences/theme"; import { SIDEBAR_VARIANT_VALUES } from "@/lib/preferences/layout"; // In a server component or server action const themeMode = await getPreference( "theme_mode", THEME_MODE_VALUES, // ["light", "dark", "system"] "light" // fallback ); // Type: "light" | "dark" | "system" const sidebarVariant = await getPreference( "sidebar_variant", SIDEBAR_VARIANT_VALUES, // ["sidebar", "inset", "floating"] "inset" ); // Type: "sidebar" | "inset" | "floating" ``` -------------------------------- ### Responsive Design Hooks Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Demonstrates the usage of custom hooks `useIsMobile` and `useIsLg` to determine the current screen size. These hooks are essential for implementing responsive behavior in your components. ```typescript const isMobile = useIsMobile(); const isLg = useIsLg(); ``` -------------------------------- ### Sidebar Navigation Items Iteration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Shows how to import and iterate through the `sidebarItems` configuration. This example logs the label and items for each navigation group, useful for dynamic menu rendering. ```typescript import { sidebarItems } from "@/navigation/sidebar/sidebar-items"; sidebarItems.forEach(group => { console.log(group.label, group.items); }); ``` -------------------------------- ### DateRangePicker Usage Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/06-components.md Demonstrates how to use the DateRangePicker component in a React application to manage a date range state. ```typescript import { DateRangePicker } from "@/components/date-range-picker"; import { useState } from "react"; import type { DateRange } from "react-day-picker"; export function Analytics() { const [dateRange, setDateRange] = useState(); return ( ); } ``` -------------------------------- ### Get Current Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md Retrieve current theme mode, font, and sidebar state from the preferences store. ```typescript const theme = usePreferencesStore(s => s.themeMode); const font = usePreferencesStore(s => s.font); const sidebarOpen = usePreferencesStore(s => s.sidebarCollapsible); ``` -------------------------------- ### Build Settings Panel with Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Demonstrates how to use preferences in a client component to build a settings panel. It utilizes the `usePreferencesStore` hook to get and set preferences and `persistPreference` to save them on the server. ```typescript export function SettingsPanel() { const { themeMode, setThemeMode } = usePreferencesStore(s => ({ themeMode: s.themeMode, setThemeMode: s.setThemeMode, })); const handleChange = async (value) => { setThemeMode(value); await persistPreference("theme_mode", value); }; return ( ); } ``` -------------------------------- ### Create a New Feature Branch Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/CONTRIBUTING.md Before starting any work, create a new branch for your changes. Replace 'my-update' with a descriptive name for your feature. ```bash git checkout -b feature/my-update ``` -------------------------------- ### Usage Examples: setValueToCookie Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Shows how to use setValueToCookie to set cookies with default options, a specific max age for one hour, and a custom path. ```typescript import { setValueToCookie } from "@/server/server-actions"; // Set a 7-day cookie await setValueToCookie("theme_mode", "dark"); // Set a 1-hour cookie await setValueToCookie("session_token", "abc123", { maxAge: 3600 }); // Set a path-specific cookie await setValueToCookie("dashboard_state", "expanded", { path: "/dashboard" }); ``` -------------------------------- ### User Data Usage Examples Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/08-configuration.md Illustrates common operations on the mock user data, such as filtering users by ID or role, and mapping user data to create options for a selector component. ```typescript import { users, rootUser } from "@/data/users"; // Get user by ID function getUserById(id: string) { return users.find((u) => u.id === id); } // Get user by email function getUserByEmail(email: string) { return users.find((u) => u.email === email); } // Filter by role const administrators = users.filter((u) => u.role === "administrator"); // Build user selector options const userOptions = users.map((u) => ({ value: u.id, label: u.name, })); ``` -------------------------------- ### CSS Customization Examples Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/06-components.md Demonstrates how to customize the size, color, and interactivity of a component using Tailwind CSS utility classes. Useful for applying consistent styling across different component instances. ```typescript // Size variants {/* 12px */} {/* 16px */} {/* 20px (default) */} {/* 24px */} // Color variants // Interactive ``` -------------------------------- ### Persist Preference Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/03-preferences-system.md Demonstrates how to save a preference value using the `persistPreference` function. This function routes the save operation to the appropriate storage based on the `PREFERENCE_PERSISTENCE` configuration. ```typescript import { persistPreference } from "@/lib/preferences/preferences-storage"; // Save theme preference to cookie await persistPreference("theme_mode", "dark"); // Save layout preference to localStorage await persistPreference("content_layout", "full-width"); ``` -------------------------------- ### Common Next.js Environment Variables Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/08-configuration.md Provides examples of standard Next.js environment variables for deployment URL and external API keys. The preferences system does not require custom env vars. ```env # For deployment NEXT_PUBLIC_APP_URL=https://yourdomain.com # For external APIs (if added) NEXT_PUBLIC_API_KEY=... DATABASE_URL=... ``` -------------------------------- ### Preferences Store API Reference Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Provides a quick reference for interacting with the preferences store on the client-side. Includes examples for reading values, updating local state, and persisting changes to the server. ```typescript // Read const value = usePreferencesStore(s => s.themeMode); // Update const setThemeMode = usePreferencesStore(s => s.setThemeMode); setThemeMode("dark"); // Save await persistPreference("theme_mode", "dark"); ``` -------------------------------- ### Preferences Store Methods Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/03-preferences-system.md Common methods for interacting with the preferences store, such as getting state, updating state, subscribing to changes, and directly setting theme or font. ```typescript store.getState() // Get full state store.setState(updater) // Update state store.subscribe(listener) // Listen to changes store.getState().setThemeMode(mode) // Update theme store.getState().setFont(fontKey) // Update font ``` -------------------------------- ### Setting Cookie Expiration for Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Provides examples of setting different cookie expirations, from long-lived preferences to short-lived tokens and session cookies. ```typescript // ✅ Long-lived preferences (7 days is default) await setValueToCookie("theme_mode", "dark"); // ✅ Short-lived tokens (1 hour) await setValueToCookie("csrf_token", token, { maxAge: 3600 }); // ✅ Session cookies (until browser closes) await setValueToCookie("session_id", sessionId, { maxAge: undefined }); ``` -------------------------------- ### Usage Example: getValueFromCookie Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Demonstrates how to import and use the getValueFromCookie function in a server component or server action to retrieve a user ID. ```typescript import { getValueFromCookie } from "@/server/server-actions"; // In a server component or server action const userId = await getValueFromCookie("user_id"); console.log(userId); // "123" or undefined ``` -------------------------------- ### Error Handling for Server Actions Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Demonstrates implicit error handling behaviors of server actions, such as returning `undefined` for missing cookies or fallback values for invalid inputs. Includes a `try-catch` example for production error management. ```typescript // If cookie not set, returns undefined const value = await getValueFromCookie("nonexistent"); // value === undefined // If invalid value, returns fallback const theme = await getPreference( "theme_mode", ["light", "dark"], "light" ); // If cookie is "invalid", returns "light" ``` ```typescript try { const themeMode = await getPreference("theme_mode", THEME_MODE_VALUES, "light"); } catch (error) { console.error("Failed to read preference:", error); // Use fallback } ``` -------------------------------- ### Sidebar Variant and Persistence Example Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Shows how to retrieve the current sidebar variant from the preferences store and update it. The `setSidebarVariant` function modifies the local state, and persistence can be handled separately. ```typescript const sidebarVariant = usePreferencesStore(s => s.sidebarVariant); setSidebarVariant("floating"); ``` -------------------------------- ### Get Type-Safe Preference (Server Action) Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md Retrieve a preference value from the server, ensuring it matches one of the allowed values and providing a default. ```typescript const mode = await getPreference( "theme_mode", ["light", "dark", "system"], "light" ); // mode: "light" | "dark" | "system" ``` -------------------------------- ### Update and Persist Preferences in Client Component Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Update application preferences like theme mode and font, and persist these changes using the persistPreference function. This example demonstrates how to use state setters from the preferences store and trigger persistence on user interaction. ```typescript "use client"; import { usePreferencesStore } from "@/stores/preferences/preferences-provider"; import { persistPreference } from "@/lib/preferences/preferences-storage"; export function ThemeSwitcher() { const themeMode = usePreferencesStore((s) => s.themeMode); const setThemeMode = usePreferencesStore((s) => s.setThemeMode); const font = usePreferencesStore((s) => s.font); const setFont = usePreferencesStore((s) => s.setFont); const handleThemeChange = async (newMode: ThemeMode) => { setThemeMode(newMode); await persistPreference("theme_mode", newMode); }; const handleFontChange = async (newFont: FontKey) => { setFont(newFont); applyFont(newFont); // Assuming applyFont is defined elsewhere await persistPreference("font", newFont); }; return (
); } ``` -------------------------------- ### Navigate into Project Directory Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/CONTRIBUTING.md Change your current directory to the cloned project folder. ```bash cd next-shadcn-admin-dashboard ``` -------------------------------- ### Initialize Root Layout with Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Shows how to fetch preferences on the server and pass them to the `PreferencesStoreProvider` in the root layout for Server-Side Rendering (SSR). This ensures preferences are available immediately on the client. ```typescript import { getPreference } from "@/server/server-actions"; import { PreferencesStoreProvider } from "@/stores/preferences/preferences-provider"; export default async function RootLayout({ children }) { const themeMode = await getPreference("theme_mode", THEME_MODE_VALUES, "light"); // ... get other preferences ... return ( {children} ); } ``` -------------------------------- ### Get Value from Server Cookie Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/05-utilities.md Retrieves a cookie value on the server-side, suitable for SSR applications. This is an asynchronous operation. ```typescript import { getValueFromCookie } from "@/server/server-actions"; const themeMode = await getValueFromCookie("theme_mode"); ``` -------------------------------- ### Clone the Repository Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/README.md Clone the project repository to your local machine to begin development. ```bash git clone https://github.com/arhamkhnz/next-shadcn-admin-dashboard.git ``` -------------------------------- ### Get Client-Side Cookie Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/05-utilities.md Retrieves the value of a specified cookie from the client's browser. Returns `undefined` if the cookie does not exist. ```typescript import { getClientCookie } from "@/lib/cookie.client"; const theme = getClientCookie("theme_mode"); // "dark" | undefined ``` -------------------------------- ### Get Value from Cookie (Server Action) Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md Retrieve a value from a cookie on the server. The value can be a string or undefined if the key is not found. ```typescript const value = await getValueFromCookie("key"); // value: string | undefined ``` -------------------------------- ### Project Structure Overview Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/01-overview.md Illustrates the colocation-based architecture of the Studio Admin project, showing the organization of Next.js app router, components, libraries, and other modules. ```tree src/ ├── app/ # Next.js app router │ ├── (main)/ # Main authenticated layout │ │ ├── dashboard/ # Dashboard variants │ │ ├── auth/ # Authentication pages │ │ ├── chat/ # Chat feature │ │ └── [...] │ └── (external)/ # External pages ├── components/ │ ├── ui/ # shadcn/ui components │ ├── date-range-picker.tsx # Custom components │ └── [...] ├── lib/ │ ├── preferences/ # Theme & layout preferences │ ├── fonts/ # Font registry │ ├── utils.ts # Utility functions │ └── [...] ├── hooks/ # Custom React hooks ├── stores/ # Zustand stores ├── config/ # Application configuration ├── navigation/ # Navigation definitions └── server/ # Server actions ``` -------------------------------- ### Clone the Repository Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/CONTRIBUTING.md Clone the Studio Admin repository to your local machine. Replace YOUR_USERNAME with your GitHub username. ```bash git clone https://github.com/YOUR_USERNAME/next-shadcn-admin-dashboard.git ``` -------------------------------- ### Tailwind CSS Font Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/04-fonts.md Example of how to configure Tailwind CSS to use the generated font CSS variables for sans-serif fonts. ```javascript // In Tailwind config const config = { theme: { fontFamily: { sans: ["var(--font-geist)", "sans-serif"], }, }, } ``` -------------------------------- ### All Available Preference Keys Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/08-configuration.md Lists all possible keys for user preferences, including theme, font, layout, and sidebar settings. ```typescript type PreferenceKey = | "theme_mode" | "theme_preset" | "font" | "content_layout" | "navbar_style" | "sidebar_variant" | "sidebar_collapsible" ``` -------------------------------- ### DateRange Interface Definition (react-day-picker) Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/11-types-reference.md Represents a date range with optional start and end dates, typically used by date pickers. ```typescript interface DateRange { from?: Date; to?: Date; } ``` -------------------------------- ### Format, Lint, and Organize Imports Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/README.md Use Biome to format code, lint for quality, and organize imports. This command applies fixes directly to the files. ```bash npx @biomejs/biome check --write ``` -------------------------------- ### Migration Step 3: Use New Preference in Server Actions Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Illustrates the final step in extending the preference system, showing how to use the newly added preference type within server actions. ```typescript import { YOUR_FEATURE_VALUES } from "@/lib/preferences/your-feature"; const setting = await getPreference( "your_feature", YOUR_FEATURE_VALUES, "option1" ); ``` -------------------------------- ### Cookie Utilities (Client-side) Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/05-utilities.md Client-side functions for managing cookies, including setting, getting, and deleting them. Supports automatic expiration for cookie setting. ```APIDOC ## setClientCookie ### Description Sets a cookie with automatic expiration. ### Method `setClientCookie(key: string, value: string, days: number = 7): void` ### Parameters - **key** (string) - Required - Cookie name - **value** (string) - Required - Cookie value - **days** (number) - Optional - Days until expiration (default: 7) ### Request Example ```typescript import { setClientCookie } from "@/lib/cookie.client"; setClientCookie("user_pref", "dark-mode"); setClientCookie("session_id", "abc123", 30); // expires in 30 days ``` ## getClientCookie ### Description Retrieves a cookie value or `undefined` if not found. ### Method `getClientCookie(key: string): string | undefined` ### Parameters - **key** (string) - Required - Cookie name ### Response Example ```typescript import { getClientCookie } from "@/lib/cookie.client"; const theme = getClientCookie("theme_mode"); // "dark" | undefined ``` ## deleteClientCookie ### Description Deletes a cookie immediately. ### Method `deleteClientCookie(key: string): void` ### Parameters - **key** (string) - Required - Cookie name ### Request Example ```typescript import { deleteClientCookie } from "@/lib/cookie.client"; deleteClientCookie("session_id"); ``` ``` -------------------------------- ### Integrate Application Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Utilizes imported application configuration for dynamic rendering of titles, meta descriptions, and copyright information. ```typescript import { APP_CONFIG } from "@/config/app-config"; export function Header() { return

{APP_CONFIG.name}

; } export function MetaTags() { return ( <> {APP_CONFIG.meta.title} ); } export function Footer() { return
{APP_CONFIG.copyright}
; } ``` -------------------------------- ### Defining and Using Custom Preference Types Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Illustrates how to define a custom type for preferences and use it with the `getPreference` server action. ```typescript type CustomSetting = "option1" | "option2" | "option3"; const CUSTOM_SETTING_VALUES: readonly CustomSetting[] = [ "option1", "option2", "option3", ] as const; // In server action const setting = await getPreference( "custom_setting", CUSTOM_SETTING_VALUES, "option1" ); // Type: CustomSetting ``` -------------------------------- ### Get Local Storage Value Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/05-utilities.md Safely retrieves a value from the browser's localStorage. Returns `null` if the key is not found or an error occurs during retrieval. ```typescript import { getLocalStorageValue } from "@/lib/local-storage.client"; const prefs = getLocalStorageValue("user_preferences"); if (prefs) { const parsed = JSON.parse(prefs); } ``` -------------------------------- ### Predefined Allowlists Imports Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Illustrates how to import predefined allowlist values for theme modes and layout configurations from their respective library files. ```typescript // src/lib/preferences/theme.ts import { THEME_MODE_VALUES, THEME_PRESET_VALUES } from "@/lib/preferences/theme"; // src/lib/preferences/layout.ts import { SIDEBAR_VARIANT_VALUES, SIDEBAR_COLLAPSIBLE_VALUES, CONTENT_LAYOUT_VALUES, NAVBAR_STYLE_VALUES, } from "@/lib/preferences/layout"; ``` -------------------------------- ### Using Path-Specific Cookies for Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Demonstrates how to set cookies with specific paths to scope their availability, distinguishing between global and feature-specific preferences. ```typescript // ✅ Global preference await setValueToCookie("theme_mode", "dark", { path: "/" }); // ✅ Feature-specific await setValueToCookie("sidebar_state", "collapsed", { path: "/dashboard" }); ``` -------------------------------- ### Usage of APP_CONFIG in Components Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/08-configuration.md Demonstrates how to import and use the APP_CONFIG object in React components for rendering dynamic content like headers, footers, and head tags. ```typescript import { APP_CONFIG } from "@/config/app-config"; export function Header() { return

{APP_CONFIG.name}

; } export function Footer() { return

{APP_CONFIG.copyright}

; } export function Head() { return ( <> {APP_CONFIG.meta.title} ); } ``` -------------------------------- ### Optimized State Selection with Zustand Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md Demonstrates the correct way to select specific state slices from a Zustand store to improve performance by avoiding unnecessary re-renders. Use selector functions for granular state access. ```typescript ✅ usePreferencesStore(s => s.themeMode) ❌ usePreferencesStore(s => s) // subscribes to all changes ``` -------------------------------- ### Migration Step 1: Add Preference Type Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Shows the first step in migrating or extending the preference system by adding a new type definition and its associated values. ```typescript // src/lib/preferences/your-feature.ts export const YOUR_FEATURE_VALUES = ["option1", "option2"] as const; export type YourFeature = (typeof YOUR_FEATURE_VALUES)[number]; ``` -------------------------------- ### Wrap Root Layout with Preferences Provider Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Set up the root layout component to include the PreferencesStoreProvider. This component reads initial preferences from the server for SSR and wraps the application's children. ```typescript // app/layout.tsx import { getPreference } from "@/server/server-actions"; import { THEME_MODE_VALUES, THEME_PRESET_VALUES } from "@/lib/preferences/theme"; import { SIDEBAR_VARIANT_VALUES, SIDEBAR_COLLAPSIBLE_VALUES, CONTENT_LAYOUT_VALUES, NAVBAR_STYLE_VALUES, } from "@/lib/preferences/layout"; import { PreferencesStoreProvider } from "@/stores/preferences/preferences-provider"; import { fontVars } from "@/lib/fonts/registry"; import { fontRegistry } from "@/lib/fonts/registry"; export default async function RootLayout({ children, }: { children: React.ReactNode }) { // Read preferences from server (for SSR) const themeMode = await getPreference( "theme_mode", THEME_MODE_VALUES, "light" ); const themePreset = await getPreference( "theme_preset", THEME_PRESET_VALUES, "default" ); const font = await getPreference( "font", Object.keys(fontRegistry) as string[], "geist" ); const contentLayout = await getPreference( "content_layout", CONTENT_LAYOUT_VALUES, "centered" ); const navbarStyle = await getPreference( "navbar_style", NAVBAR_STYLE_VALUES, "sticky" ); return ( {children} ); } ``` -------------------------------- ### Get Current Preferences in Client Component Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Access current theme mode and sidebar variant settings within a client component using the usePreferencesStore hook. This allows components to react to and display the current application preferences. ```typescript "use client"; import { usePreferencesStore } from "@/stores/preferences/preferences-provider"; export function SettingsPanel() { const themeMode = usePreferencesStore((s) => s.themeMode); const sidebarVariant = usePreferencesStore((s) => s.sidebarVariant); return (

Current theme: {themeMode}

Sidebar variant: {sidebarVariant}

); } ``` -------------------------------- ### usePreferencesStore Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/02-hooks.md Accesses the global preferences store (Zustand) for theme, layout, and font settings. Must be used within PreferencesStoreProvider. ```APIDOC ## usePreferencesStore ### Description Accesses the global preferences store (Zustand) for theme, layout, and font settings. Must be used within `PreferencesStoreProvider`. ### Signature ```typescript export function usePreferencesStore(selector: (state: PreferencesState) => T): T ``` ### Parameters - `selector` (`(state: PreferencesState) => T`): Function that selects a slice of the preferences state ### Returns - `T`: The selected state value ### Throws - `Error("Missing PreferencesStoreProvider")`: Hook is called outside `PreferencesStoreProvider` context ### Example ```typescript import { usePreferencesStore } from "@/stores/preferences/preferences-provider"; export function ThemeSwitcher() { const themeMode = usePreferencesStore((s) => s.themeMode); const setThemeMode = usePreferencesStore((s) => s.setThemeMode); return ( ); } ``` ### Available State Selectors ```typescript type PreferencesState = { themeMode: ThemeMode; // "light" | "dark" | "system" resolvedThemeMode: ResolvedThemeMode; // "light" | "dark" themePreset: ThemePreset; // "default" | "brutalist" | "soft-pop" | "tangerine" font: FontKey; // Font family key contentLayout: ContentLayout; // "centered" | "full-width" navbarStyle: NavbarStyle; // "sticky" | "scroll" sidebarVariant: SidebarVariant; // "sidebar" | "inset" | "floating" sidebarCollapsible: SidebarCollapsible; // "icon" | "offcanvas" isSynced: boolean; // Whether store is synced with DOM // Setters setThemeMode(mode: ThemeMode): void; setResolvedThemeMode(mode: ResolvedThemeMode): void; setThemePreset(preset: ThemePreset): void; setFont(font: FontKey): void; setContentLayout(layout: ContentLayout): void; setNavbarStyle(style: NavbarStyle): void; setSidebarVariant(variant: SidebarVariant): void; setSidebarCollapsible(mode: SidebarCollapsible): void; setIsSynced(val: boolean): void; } ``` ### Hydration Safety The store syncs with DOM attributes on mount, preventing hydration mismatches. The `isSynced` flag indicates when the store is fully initialized. ```typescript export function ConfigurableComponent() { const isSynced = usePreferencesStore((s) => s.isSynced); if (!isSynced) { return
Loading preferences...
; } return ; } ``` ``` -------------------------------- ### Theme Mode Options Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md An array of objects defining options for theme mode selection, each with a label and a value. ```typescript [ { label: "Light", value: "light" }, { label: "Dark", value: "dark" }, { label: "System", value: "system" }, ] ``` -------------------------------- ### subscribeToSystemTheme Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/03-preferences-system.md Listens to OS theme preference changes for 'system' mode. It accepts a callback function that is invoked when the theme mode changes and returns an unsubscribe function to stop listening. ```APIDOC ## subscribeToSystemTheme ### Description Listens to OS theme preference changes (for "system" mode). ### Signature ```typescript export function subscribeToSystemTheme( onChange: (mode: ResolvedThemeMode) => void ): () => void ``` ### Returns An unsubscribe function to stop listening. ``` -------------------------------- ### Theme Preset Options Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md An array of objects defining theme preset options, including labels, values, and primary color configurations. ```typescript [ { label: "Default", value: "default", primary: {...} }, { label: "Brutalist", value: "brutalist", primary: {...} }, { label: "Soft Pop", value: "soft-pop", primary: {...} }, { label: "Tangerine", value: "tangerine", primary: {...} }, ] ``` -------------------------------- ### useIsLg Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/02-hooks.md Detects whether the viewport meets or exceeds the large breakpoint (1024px). It listens to matchMedia events and returns a stable boolean value after mount. ```APIDOC ## useIsLg ### Description Detects whether the viewport meets or exceeds the large breakpoint (1024px). ### Signature ```typescript export function useIsLg(): boolean ``` ### Returns - `boolean`: `true` when viewport is ≥1024px, `false` otherwise. Initial render returns `false` until component mounts. ### Behavior - Listens to `matchMedia` events for viewport changes - Returns stable boolean value after mount - Unsubscribes from media query listener on unmount ### Example ```typescript import { useIsLg } from "@/hooks/use-lg"; export function TwoColumnLayout() { const isLg = useIsLg(); return (
); } ``` ``` -------------------------------- ### Migration Step 2: Update Preference Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Details the second step in extending the preference system by updating the central configuration to include the new preference type. ```typescript // src/lib/preferences/preferences-config.ts export type PreferenceValueMap = { // ... your_feature: YourFeature; } ``` -------------------------------- ### Accessing Root User Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/08-configuration.md Demonstrates how to import and access the `rootUser` object, which is a convenience export of the first user in the mock data array. ```typescript import { rootUser } from "@/data/users"; console.log(rootUser.name); // "Arham Khan" console.log(rootUser.role); // "administrator" ``` -------------------------------- ### SSR with Preferences in Root Layout Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Fetches user preferences on the server for Server-Side Rendering (SSR) to initialize client-side stores. ```typescript // app/layout.tsx import { getPreference } from "@/server/server-actions"; import { THEME_MODE_VALUES } from "@/lib/preferences/theme"; import { PreferencesStoreProvider } from "@/stores/preferences/preferences-provider"; export default async function RootLayout({ children, }: { children: React.ReactNode; }) { // Get preferences on server for SSR const themeMode = await getPreference( "theme_mode", THEME_MODE_VALUES, "light" ); return ( {children} ); } ``` -------------------------------- ### Common Imports for Studio Admin Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md Essential imports for various functionalities including preferences, types, hooks, utilities, components, data, configuration, and server actions. ```typescript // Preferences import { usePreferencesStore } from "@/stores/preferences/preferences-provider"; import { persistPreference } from "@/lib/preferences/preferences-storage"; // Types import type { ThemeMode, ThemePreset, SidebarVariant } from "@/lib/preferences/ப்புகளை"; import type { FontKey } from "@/lib/fonts/registry"; // Hooks import { useIsMobile } from "@/hooks/use-mobile"; import { useIsLg } from "@/hooks/use-lg"; // Utilities import { cn } from "@/lib/utils"; import { formatCurrency, getInitials } from "@/lib/utils"; // Components import { DateRangePicker } from "@/components/date-range-picker"; import { SimpleIcon } from "@/components/simple-icon"; // Data import { sidebarItems } from "@/navigation/sidebar/sidebar-items"; import { users, rootUser } from "@/data/users"; // Config import { APP_CONFIG } from "@/config/app-config"; // Server import { getPreference, setValueToCookie } from "@/server/server-actions"; ``` -------------------------------- ### Lazy Load Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md Improve initial load performance by asynchronously fetching preferences. Avoid awaiting all preferences simultaneously; fetch them as needed. ```typescript const themeMode = await getPreference(...); // Don't await all preferences in series ``` -------------------------------- ### Using Type-Safe Constants for Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/09-server-actions.md Highlights the best practice of using type-safe constants with `getPreference` compared to using literal arrays. ```typescript // ✅ Good const theme = await getPreference("theme_mode", THEME_MODE_VALUES, "light"); // ❌ Avoid const theme = await getPreference("theme_mode", ["light", "dark"], "light"); ``` -------------------------------- ### Build Dynamic Sidebar Navigation Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Constructs a navigation sidebar by mapping over predefined sidebar items, handling active states and new tab links. ```typescript import { sidebarItems } from "@/navigation/sidebar/sidebar-items"; import Link from "next/link"; import { usePathname } from "next/navigation"; export function Sidebar() { const pathname = usePathname(); return ( ); } ``` -------------------------------- ### Display User Profile Information Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Renders basic user details like name, email, and role from imported user data. ```typescript import { users, rootUser } from "@/data/users"; import { APP_CONFIG } from "@/config/app-config"; export function ProfileMenu() { return (

{rootUser.name}

{rootUser.email}

{rootUser.role}
); } export function UserList() { return (
    {users.map((user) => (
  • {user.name} {user.name}
    • ))}
); } ``` -------------------------------- ### Safe Preference Access with Loading State Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md Safely access preferences from the store, displaying a loading state if preferences are not yet synced. ```typescript const isSynced = usePreferencesStore(s => s.isSynced); if (!isSynced) return ; return ; ``` -------------------------------- ### Safely Access Preferences Store Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Demonstrates safe access to the `usePreferencesStore` by checking the `isSynced` state before rendering UI elements. This prevents errors during the initial loading of preferences. ```typescript "use client"; import { usePreferencesStore } from "@/stores/preferences/preferences-provider"; export function SafePreferences() { const isSynced = usePreferencesStore((s) => s.isSynced); const themeMode = usePreferencesStore((s) => s.themeMode); if (!isSynced) { return
Initializing preferences...
; } return
Theme: {themeMode}
; } ``` -------------------------------- ### Access Global Preferences with usePreferencesStore Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/02-hooks.md This hook provides access to the global preferences store (Zustand) for managing theme, layout, and font settings. It must be used within a `PreferencesStoreProvider` context. It accepts a selector function to extract specific state slices. ```typescript export function usePreferencesStore(selector: (state: PreferencesState) => T): T ``` ```typescript import { usePreferencesStore } from "@/stores/preferences/preferences-provider"; export function ThemeSwitcher() { const themeMode = usePreferencesStore((s) => s.themeMode); const setThemeMode = usePreferencesStore((s) => s.setThemeMode); return ( ); } ``` ```typescript type PreferencesState = { themeMode: ThemeMode; // "light" | "dark" | "system" resolvedThemeMode: ResolvedThemeMode; // "light" | "dark" themePreset: ThemePreset; // "default" | "brutalist" | "soft-pop" | "tangerine" font: FontKey; // Font family key contentLayout: ContentLayout; // "centered" | "full-width" navbarStyle: NavbarStyle; // "sticky" | "scroll" sidebarVariant: SidebarVariant; // "sidebar" | "inset" | "floating" sidebarCollapsible: SidebarCollapsible; // "icon" | "offcanvas" isSynced: boolean; // Whether store is synced with DOM // Setters setThemeMode(mode: ThemeMode): void; setResolvedThemeMode(mode: ResolvedThemeMode): void; setThemePreset(preset: ThemePreset): void; setFont(font: FontKey): void; setContentLayout(layout: ContentLayout): void; setNavbarStyle(style: NavbarStyle): void; setSidebarVariant(variant: SidebarVariant): void; setSidebarCollapsible(mode: SidebarCollapsible): void; setIsSynced(val: boolean): void; } ``` ```typescript export function ConfigurableComponent() { const isSynced = usePreferencesStore((s) => s.isSynced); if (!isSynced) { return
Loading preferences...
; } return ; } ``` -------------------------------- ### AppConfig Interface Definition Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/11-types-reference.md Represents the application's configuration, including name, version, copyright, and meta information. ```typescript interface AppConfig { name: string; version: string; copyright: string; meta: { title: string; description: string; }; } ``` -------------------------------- ### Application Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/08-configuration.md Defines application metadata such as name, version, copyright, and meta tags for SEO and social sharing. This configuration is typically located at src/config/app-config.ts. ```typescript export const APP_CONFIG = { name: "Studio Admin", version: "2.2.0", copyright: `© ${currentYear}, Studio Admin.`, meta: { title: "Studio Admin - Modern Next.js Dashboard Starter Template", description: "Studio Admin is a modern, open-source dashboard starter template built with Next.js 16, Tailwind CSS v4, and shadcn/ui. Perfect for SaaS apps, admin panels, and internal tools—fully customizable and production-ready.", }, } ``` -------------------------------- ### Responsive Component with Hydration Handling Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/README.md Conditionally render different layouts based on screen size using the `useIsMobile` hook. It's crucial to handle the `undefined` state during hydration to prevent layout shifts. ```typescript const isMobile = useIsMobile(); if (isMobile === undefined) return null; // Hydration return isMobile ? : ; ``` -------------------------------- ### PREFERENCE_PERSISTENCE Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/03-preferences-system.md Defines the persistence method for each preference key. This configuration determines how settings are saved and retrieved. ```typescript export const PREFERENCE_PERSISTENCE: PreferencePersistenceConfig = { theme_mode: "client-cookie", theme_preset: "client-cookie", font: "client-cookie", content_layout: "client-cookie", navbar_style: "client-cookie", sidebar_variant: "client-cookie", sidebar_collapsible: "client-cookie", } ``` -------------------------------- ### Font Options Configuration Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/12-quick-reference.md An array of objects defining font options, each with a key, label, and CSS variable for theming. ```typescript [ { key: "geist", label: "Geist", variable: "--font-geist" }, { key: "inter", label: "Inter", variable: "--font-inter" }, // ... 15 more ] ``` -------------------------------- ### Render Sidebar Navigation Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/07-navigation.md Renders the main sidebar navigation by mapping through predefined sidebar items. Requires 'sidebarItems' to be imported. ```typescript import { sidebarItems } from "@/navigation/sidebar/sidebar-items"; export function Sidebar() { return ( ); } ``` -------------------------------- ### Server Actions API Reference Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/00-index.md Provides a reference for server actions related to cookie and preference management. Includes functions for reading/writing cookies and retrieving preferences with validation. ```typescript const value = await getValueFromCookie("key"); await setValueToCookie("key", "value", { maxAge: 3600 }); const mode = await getPreference("theme_mode", MODES, "light"); ``` -------------------------------- ### Apply Theming Based on Preferences Source: https://github.com/arhamkhnz/next-shadcn-admin-dashboard/blob/main/_autodocs/10-integration-guide.md Applies theme-specific styles to components based on user preferences for dark or light mode. ```typescript "use client"; import { usePreferencesStore } from "@/stores/preferences/preferences-provider"; import { cn } from "@/lib/utils"; export function ThemedCard({ children }: { children: React.ReactNode }) { const resolvedThemeMode = usePreferencesStore((s) => s.resolvedThemeMode); return (
{children}
); } ```