⚡ Shadcn Kit React Template

This repository provides a ready-to-use template for quickly bootstrapping a React application, running it locally, and deploying it to ServiceNow via SDK 4.

The template comes pre-installed with everything you need to build a full-stack TypeScript-based React application:

• Vite – Fast development server.
• Tailwind CSS – Utility-first CSS framework.
• Shadcn UI – Accessible, customizable React components.
• Shadcn-Kit – Shadcn components tailored for ServiceNow.
• TanStack Query – Asynchronous state management and caching.

Once combined with your ServiceNow development expertise, you can deliver modern full-stack applications to your users in no time.

PLEASE NOTE: Building this template will only work in a local node environment e.g. via VS Code. Support for ServiceNow IDE is not currently included.

---

🖥️ Local Development

Start by getting the template running locally:

1. Clone or fork this repository, then cd into it.
2. If you cloned it and want a fresh base, delete the .git folder.
3. Install dependencies:
   • Run: npm install
4. Authenticate with the ServiceNow SDK for the instance you want to develop against:
   • Run: npx @servicenow/sdk auth --add <instance>
   • Follow the prompts to connect and save an authentication profile.
5. Start the dev server:
   • Run: npm run dev

The Vite dev server now reads the instance URL and authentication details directly from your saved ServiceNow SDK session, so no project .env file is required for local development. If the session expires, simply stop your dev server, then restart it.

If successful, you should see the following preview:

---

🚀 Build & Deploy to ServiceNow

Once local development is working, prepare to build and deploy to your ServiceNow instance:

1. Authenticate with the SDK if you have not already done so:

   • Run: npx @servicenow/sdk auth --add <instance>
   • Follow the prompts to connect and save an authentication profile.

2. Configure now.config.json in the project root:

   • name – The name of the scoped application in ServiceNow (e.g. "Shadcn Kit Example").
   • scope – The scope name, starting with x_<company_key>.
     • Find your company key in either sn_appauthor.all_company_keys or glide.appcreator.company.code system properties.
     • Example: if your company code is shadkit, then the scope can be x_shadkit_react.
   • scopeId – A valid sys_id for the application. You can generate one with a background script by running gs.info(gs.generateGUID());

3. Update shadcn.now.ts (rename if desired, but keep the .now.ts suffix):

   • Set the UI page endpoint (must start with your app scope and end with .do, e.g. x_shadkit_react_template.do).
   • Adjust other fields as needed for your app.

4. Build the app for ServiceNow:

   • Run: npm run build

5. Deploy to your instance:

   • Run: npm run deploy

After deployment, you should see a new scoped application in your instance. Navigate to its UI page endpoint to confirm the app is running.

---

🛠️ Prebuild Modifications

To make Vite, Tailwind, and Shadcn work with ServiceNow’s Rollup build process, the following adjustments were made in now.prebuild.mjs:

• Tailwind – Compile index.css into index.build.css, which is then bundled.
• Environment Variables – Include baseline variables (mode/dev/prod/baseUrl) for use inside ServiceNow.
• Alias Plugin – Map @ to src/client for cleaner imports.
• nodeResolve Plugin – Handle resolution of hoisted dependencies in node_modules.
• url Plugin – Map image imports from src/client/assets to their deployed counterparts.
• Manual Chunking - Manually chunked some of the larger dependencies sn-shadcn-kit makes use of into their own jsdbx files. These chunks will only apply if you import any components that require them.

Quick note on tailwind - If you find when deploying to ServiceNow some tailwind classes you have added to your app do not get applied, then go to the sys_app record for your scope and find the index.build.css application file and delete it, then re-deploy the app. I have noticed sometimes this file doesn't get refreshed when changes have been made to it and i'm not sure why.

---

🤖 AI Agents

The template comes equipped with an AGENTS.md file that should help give the necessary context and constraints to working within a ServiceNow fluent/react application. Your AI assistant (claude, codex, gemini etc) should automatically pick this up, but double check if there is any configuration needed with their respective docs. This template makes the assumption that you have the now-sdk-explain skill installed with your AI coding agent.

As you begin building out your application, if you notice incorrect behaviour from your agentic coding assistant, then you should make updates to this file to resolve the issue.

When working with *.server.js files, remember to add global ServiceNow objects (e.g. GlideRecord, gs) to .eslintrc to avoid linting errors.

---

🧹 Cleaning Up

Once you’re happy with the template and ready to transform it into your own application, clean up any unnecessary files:

• Clear the src/client/assets folder. (Use this folder for any media assets to be sent to ServiceNow.)
• Clear the src/client/routes folder and create your own route pages.
• Update src/client/router.tsx with your own route components.
• Configure src/client/queryClient.ts to set your preferred TanStack Query options.
• Update the <title> in src/client/index.html.
• Update package.json with an appropriate name for your application.
• update AGENTS.md with any specific context for your chosen AI model to assist you in building out your application.