ServiceNow Shadcn Directory

The Shadcn Directory is a small, lightweight demo application that can be installed onto ServiceNow instances.
It showcases the sn-shadcn-kit npm package by providing a modern React-based UI for browsing users and groups, contacting them directly, and saving favourites for future reference.

By combining sn-shadcn-kit components with a modern frontend stack, this app demonstrates an alternative to ServiceNow’s standard UI options (Service Portal, UI Builder), offering faster performance and a richer user experience.

---

Figure 1: Favourites page in light mode

---

⚡ Quick Start (Installation)

1. Download the update set from the /public folder of this repository.
2. Import and commit it into your ServiceNow instance.
3. Open the app from: Shadcn UI → My Directory.

See Configuration for options to tailor it to your instance.

---

🛠 Technology Stack

• TypeScript – Static typing for fewer runtime errors and better maintainability.
• React 19 – Modern component-based UI framework.
• Vite – Fast dev server and optimized builds.
• TanStack Router – Type-safe, file-based router with layouts and data preloading.
• TanStack Query – Async state management with query caching and re-use.
• Zustand – Lightweight state management with a minimal API.
• Tailwind CSS – Utility-first CSS framework for fast, composable styling.
• Shadcn UI – Accessible, customizable React components (basis for sn-shadcn-kit).

💡 Together, these tools bring features not typically seen in ServiceNow apps: one-click theming, customizable responsive design, route caching, and more.

---

📐 Layout and Routes

The application provides three routes: Users, Groups, and Favourites.
Each route shares a common layout with navigation tabs, a width switcher (left), and a theme switcher (right).

• Width Switcher – Toggle between fluid width (full window) and fixed width (standard container).
• Theme Switcher – Switch between light, dark, or system themes.

Figure 2: Layout bar with width and theme switchers

---

👥 Users and Groups

The Users and Groups routes are nearly identical—one shows user records, the other shows group records.

Each page consists of:

• Header

  • Quick search by name
  • Advanced search via the filter icon + condition builder

• Data Table

  • Click a name to view a pop-out detail card
  • Sort/hide columns via headers
  • Control rows per page (saved as a preference)

The condition builder works just like ServiceNow’s native one but styled with Shadcn UI.
For example, querying all active users where the name starts with Vince:

Figure 3: Condition builder in dark mode

Here’s the group page with a group selected:

Figure 4: Group details card in dark mode

---

⭐ Favourites

The Favourites route displays all saved users and groups. To keep things lightweight, favourites are stored in user preferences, so no extra database tables are required.

• Displays up to 6 users and 3 groups by default
• Additional favourites appear in a carousel
• Supports searching favourites by name

Figure 5: Browsing favourites in light mode

---

⚙️ Configuration

The app is designed to work on any instance with minimal setup, but admins can tweak settings:

UI View: shadcn_ui

Contains list layouts for Users and Groups, defining which fields display in the app. Update these layouts to customize columns.

System Property: shadcn_directory_app_config

A JSON object for further configuration:

• userPrimaryField – Field shown on the user card under a user’s name (default: email).
• accessorRole – Role required to access the app (default: shadcn_directory_user).
  • If you change it, also update the My Directory module’s role so users can see it.
• userDefaultQuery – Encoded query string applied by default to the Users route. Users still have the ability to change the query, but clearing the query resets it back to the default. (e.g. "active=true").
• groupDefaultQuery – Same as above, but for Groups.
• imLink – Enables instant messaging integration via a variable substitution with a field on the user record.
  • Example (Microsoft Teams):

    https://teams.microsoft.com/l/chat/0/0?users={email}
    

---

🔍 Update Set Review

Before committing the update set, review the changes. You should see updates of these types:

• Application Menu / Module – App navigation in ServiceNow
• UI View / List Layouts – User/group table layouts
• Role – Default app access role
• Script Include – Server-side logic
• Scripted REST API / Resources – Endpoints for app–instance communication
• System Properties – Default config + HTML page storage

---

📢 Summary

This application is both a useful directory tool and a demo project showcasing how sn-shadcn-kit can bring modern UI/UX practices into ServiceNow. It blends React, Tailwind, and Shadcn UI to deliver a fast, accessible, and customizable frontend experience.