Shim

Manual setup

Manually setup Shim in your project.

Overview

This guide walks you through manually setting up Shim without the CLI. Use this approach when you need granular control over installation or prefer managing dependencies yourself. For automated setup, see the quick start guide.

Set up

Install Tailwind CSS (v4)

Shim requires Tailwind CSS for styling.

Follow the official Tailwind v4 installation guide for your framework (Next.js, Vite, etc.) before continuing.

Install dependencies

Install the required packages for Shim components:

  • react-aria-components – Core unstyled primitives from Adobe
  • tailwind-variants – Type-safe variant API for Tailwind
  • tailwind-merge – Utility for merging Tailwind classes
  • @radix-ui/colors – Semantic color palette
  • @phosphor-icons/react – Icon set for UI elements
pnpm add react-aria-components tailwind-variants tailwind-merge @radix-ui/colors @phosphor-icons/react
Create utility files

Create style.ts and theme.tsx in your utilities directory (e.g., utils/ or lib/). These files provide styling utilities and theme context used by components.

Visit the Shim repository to copy the latest versions of:

  • style.ts – Design tokens and styling utilities
  • theme.tsx – Theme provider and context
Add theme CSS

Create theme.css in your styles directory (e.g., styles/ or app/). This file includes design tokens, animations, and utility classes. Visit the Shim repository to copy the latest theme.css.

Import the theme CSS file in your main CSS file or root layout. Adjust the path if you used a different location:

app/globals.css
@import "@/styles/theme.css";

Or import directly in your layout:

app/layout.tsx
import "@/styles/theme.css";
Configure path alias

Shim uses the @/ alias—configure it in tsconfig.json (or jsconfig.json) so imports resolve correctly.

tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
Add components

Copy component files directly from the Shim repository or the component docs into your components directory.

Update import paths in the copied files to match your project structure. For example, if components have dependencies on other components or utilities, adjust the imports accordingly:

// From:
import { Field } from "@/shim-ui/field";
import { Theme } from "@/shim-ui/lib/theme";

// To:
import { Field } from "@/src/ui/field";
import { Theme } from "@/src/lib/theme";

Next steps