@shopify/shop-minis-react

React component library for Shopify Shop Minis with Tailwind CSS v4 support. This library provides a comprehensive set of components with minimal setup required for consumers.

Features

• 🎨 Tailwind CSS v4 with CSS-first design tokens
• 📦 Source-only distribution for optimal tree-shaking
• 🎯 TypeScript first with full type safety
• 🔧 Minimal setup for consumers
• 🎭 Dark mode support out of the box
• ♿ Accessible components built with Radix UI

Installation

pnpm add @shopify/shop-minis-react
# or
npm install @shopify/shop-minis-react
# or
yarn add @shopify/shop-minis-react

Peer Dependencies

pnpm add react react-dom tailwindcss typescript

Quick Setup

1. Import Styles

Add the library's CSS to your main CSS file or app entry point:

/* src/index.css or src/app.css */
@import "@shopify/shop-minis-react/styles";

/* Your custom styles */
@layer base {
  :root {
    /* Override CSS variables if needed */
    --radius: 0.5rem;
  }
}

2. Use Components

import { Button, Card, CardContent, CardHeader, CardTitle } from '@shopify/shop-minis-react'

function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello Shop Minis</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
      </CardContent>
    </Card>
  )
}

Advanced Configuration

Custom Theme

You can customize the design system by overriding theme variables:

:root {
  /* Customize primary brand color */
  --theme-primary: #00843d;
  --theme-primary-foreground: #ffffff;

  /* Customize other semantic colors */
  --theme-secondary: #f0f0f0;
  --theme-destructive: #cc0000;

  /* Customize border radius */
  --radius: 0.75rem;
}

.dark {
  --theme-primary: #10b554;
  --theme-background: #1a1a1a;
}

See THEME-CUSTOMIZATION.md for detailed customization options.

Vite Configuration

For optimal development experience with Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  optimizeDeps: {
    include: ['@shopify/shop-minis-react']
  }
})

Component Philosophy

This library follows a source-only distribution model, meaning:

• ✅ Tree-shaking friendly - Only import what you use
• ✅ TypeScript native - Full type safety without compilation artifacts
• ✅ CSS-first theming - Customize appearance via CSS variables
• ✅ Build-time optimization - Components are optimized with your build

Available Components

• Layout: Card, Container, Grid
• Forms: Button, Input, Label, Textarea
• Feedback: Alert, Toast, Loading
• Navigation: Tabs, Breadcrumb
• Overlays: Dialog, Popover, Tooltip
• Data Display: Badge, Avatar, Separator

Troubleshooting

Styles Missing or Components Look Unstyled

If your components appear unstyled, it's likely a Tailwind content scanning issue:

1. Ensure CSS is imported:

   @import "@shopify/shop-minis-react/styles";

2. Check Tailwind content scanning: Your tailwind.config.js must include our library files:

   content: [
     './src/**/*.{js,ts,jsx,tsx}',
     // This line is CRITICAL:
     './node_modules/@shopify/shop-minis-react/src/**/*.{js,ts,jsx,tsx}',
   ]

3. Use our preset (easiest):

   const shopMinisConfig = require('@shopify/shop-minis-react/tailwind')
   module.exports = { ...shopMinisConfig, /* your config */ }

4. Verify build process: Ensure your build tool processes the imported CSS file.

Contributing

This package is part of the Shopify Shop Client monorepo. Please refer to the main repository for contribution guidelines.

License

See LICENSE.txt for details.