تشغيل أي مهارة في Manus بنقرة واحدة

shadcn-impl-framework-integration

النجوم٠

التفرعات٠

آخر تحديث١٩ مايو ٢٠٢٦ في ١٢:٤٥

Use when initializing shadcn ui inside a Vite, Next.js (App or Pages Router), React Router v7 (former Remix), Astro, or TanStack Start project, or when diagnosing per-framework init issues like wrong rsc flag, broken `@/*` alias resolution, or missing ThemeProvider wiring. Prevents the recurring failure mode where the CLI is run with the wrong `-t` template and produces a `components.json` whose `rsc` value mismatches the framework's RSC capability, silently dropping `"use client"` directives in Vite or duplicating them in Next.js. Covers per-framework init commands, the four alias-resolution systems (tsconfig paths for Next/Vite/React-Router, package.json#imports for TanStack Start, astro.config + tsconfig for Astro), components.json defaults per framework, Tailwind v3 vs v4 wiring per framework, and the three distinct ThemeProvider patterns (next-themes for Next.js, custom React Context for Vite/React-Router/TanStack Start, inline script for Astro). Keywords: shadcn vite, shadcn nextjs, shadcn nextjs app ro

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

Impertio-Studio

Impertio-Studio/shadcn-ui-Claude-Skill-Package

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

مطوّرو البرمجياتمهن الحاسوب والرياضيات·SOC 15-1252

مستكشف الملفات

4 ملفات

SKILL.md

readonly

المزيد من هذا المستودع

نفس المستودع

shadcn-core-cli

Impertio-Studio/shadcn-ui-Claude-Skill-Package

Use when running any shadcn CLI command (init, add, view, search, apply, preset, build, docs, info, migrate), when writing or editing components.json, when choosing between tsconfig path aliases and package.json#imports aliases (new in shadcn@4.7.0), when wiring a custom or private registry, or when a shadcn invocation overwrote local component edits unexpectedly. Prevents the silent-overwrite trap from running `add` without `--diff` after local modifications, the "Cannot find baseColor" failure from a malformed components.json, the registry-resolution miss from forgetting the `{name}` placeholder, and the immutable-field surprise from trying to change `style`, `baseColor`, or `cssVariables` after init. Covers every CLI command and flag, the complete components.json schema, registry resolution semantics, and the package.json#imports alternative to tsconfig paths. Keywords: shadcn cli, npx shadcn add, pnpm dlx shadcn, shadcn init, shadcn diff, shadcn update, shadcn migrate, shadcn migrate icons, shadcn migrate

2026-05-190

shadcn-impl-component-install

Impertio-Studio/shadcn-ui-Claude-Skill-Package

Use when adding a new component to a project that already uses shadcn, when bootstrapping shadcn for the first time in a fresh app, when deciding between `shadcn add`, a hand-built primitive, or a pre-built block, when wiring path aliases (tsconfig paths or the new package.json#imports resolver from shadcn@4.7.0), when re-running `add` against a file you have already customised, or when an `add` invocation has surfaced broken imports or missing radix dependencies. Prevents the silent-overwrite destruction from running `add --overwrite` without `--diff` first, the broken-imports trap from running `add` before `init`, the alias-mismatch bug where `tsconfig` paths and `components.json` aliases disagree, the bypass-the-CLI mistake of pip-installing `@radix-ui/react-*` packages by hand instead of letting `add` resolve them, and the long-tail stale-code problem from never re-running the CLI after upstream bug fixes ship. Covers the full add-or-customise-or-block decision tree, the init-then-add-then-customise workf

2026-05-190

shadcn-core-registry

Impertio-Studio/shadcn-ui-Claude-Skill-Package

Use when authoring or consuming a shadcn registry, when configuring the `registries` field in components.json, when wiring a private or paid component library behind a namespace prefix like `@myorg/datepicker`, when securing a custom registry with bearer tokens or API keys, when hosting a `registry.json` plus per-item JSON files, or when explaining why the `style`, `baseColor`, or `cssVariables` fields cannot be changed after `init`. Prevents the missing-`{name}`-placeholder trap that breaks every namespace install, the committed-secret leak from inlining an API key instead of using `${ENV_VAR}` expansion, the alias-mismatch silent failure from setting `aliases.components` to one path while imports reference another, the immutable-field surprise from editing `style`/`baseColor`/`cssVariables` post-init, and the Tailwind v3-vs-v4 config-shape confusion. Covers every components.json field in depth (purpose, constraints, defaults, immutability), the URL-template syntax with `{name}` and `{style}` placeholders, e

2026-05-190

shadcn-errors-cmdk-version-drift

Impertio-Studio/shadcn-ui-Claude-Skill-Package

Use when a shadcn ui Command primitive (command palette, Combobox, search list, fuzzy filter, multi-select dropdown) stops filtering, renders the full list regardless of typing, fails to highlight or click items, throws "TypeError : undefined is not iterable (cannot read property Symbol(Symbol.iterator))" on a CommandItem rendered outside CommandList, silently ignores a third `keywords` argument passed to the `filter` prop, no longer matches values typed in uppercase, loses keyboard focus inside a Vaul Drawer, returns zero results despite `shouldFilter={false}`, or fails to import `CommandLoading` from the shadcn wrapper. Prevents the six recurring drift traps : (1) writing a 2-arg `(value, search) => number` filter against cmdk >= 1.0.0 where the signature is `(value, search, keywords) => number` so the third argument is silently dropped and per-item `keywords` boosting never fires, (2) writing a custom `filter` that does a case-sensitive `===` or `includes` check against raw `value` and raw `search` so that

2026-05-190

shadcn-agents-cva-validator

Impertio-Studio/shadcn-ui-Claude-Skill-Package

Use when reviewing, validating, or auditing a shadcn ui component that uses class-variance-authority (cva), when an LLM has just produced a Button-like, Badge-like, Alert-like, or any other cva-driven component and you must verify the variant API before accepting the diff, when a consumer className does not visually win and you suspect cva merge order or a missing cn() call, when extending an existing shadcn component with a new variant or compoundVariant and you want a deterministic checklist before commit, when porting a hand-written variants-via-if-branches component to cva, when writing a custom primitive that should follow the shadcn convention, when verifying that VariantProps inference is exported so consumers can extend the component type, or when running a code-review pass on AI-generated cva code to catch the canonical mistakes (nested cn inside cva, compoundVariants placed before variants, missing defaultVariants, raw className concatenation, asChild without Slot, variant key typos that silently di

2026-05-190

shadcn-agents-form-validator

Impertio-Studio/shadcn-ui-Claude-Skill-Package

Use when validating a react-hook-form + zod + shadcn Form integration in a code review, a draft AI-generated form, or a bug report ("my validation does not trigger", "the error message never shows", "the Select does not bind", "submit fires but values are undefined", "the field reads as uncontrolled then controlled"), when auditing whether a zod schema and a shadcn Form composition agree on every field name, when verifying Controller-vs-register correctness for custom controls (Select, Checkbox, RadioGroup, Switch, DatePicker, Combobox), when confirming every FormField has a FormMessage so zod errors are visible to the user, when checking that defaultValues covers every schema key (no undefined-to-string controlled / uncontrolled warning), when verifying the submit handler is wrapped in form.handleSubmit, when checking that zodResolver is actually passed to useForm, when ensuring no nested FormProvider / shadcn Form context is duplicated, and when emitting a structured pass / fail verdict over a form code blo

2026-05-190

name	shadcn-impl-framework-integration
description	Use when initializing shadcn ui inside a Vite, Next.js (App or Pages Router), React Router v7 (former Remix), Astro, or TanStack Start project, or when diagnosing per-framework init issues like wrong rsc flag, broken `@/*` alias resolution, or missing ThemeProvider wiring. Prevents the recurring failure mode where the CLI is run with the wrong `-t` template and produces a `components.json` whose `rsc` value mismatches the framework's RSC capability, silently dropping `"use client"` directives in Vite or duplicating them in Next.js. Covers per-framework init commands, the four alias-resolution systems (tsconfig paths for Next/Vite/React-Router, package.json#imports for TanStack Start, astro.config + tsconfig for Astro), components.json defaults per framework, Tailwind v3 vs v4 wiring per framework, and the three distinct ThemeProvider patterns (next-themes for Next.js, custom React Context for Vite/React-Router/TanStack Start, inline script for Astro). Keywords: shadcn vite, shadcn nextjs, shadcn nextjs app router, shadcn nextjs pages router, shadcn remix, shadcn react router v7, shadcn astro, shadcn tanstack start, framework integration, alias setup vite, components json nextjs, components json vite, rsc true, rsc false, init template flag, -t next, -t vite, -t astro, -t start, -t react-router, ThemeProvider next-themes, ThemeProvider vite, dark mode astro inline script, suppressHydrationWarning, app router vs pages router, init for next.js, how do I set up shadcn in vite, my @ alias does not resolve, use client missing, hydration mismatch dark mode, tailwind v4 @tailwindcss/vite
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn-impl-framework-integration

Per-framework setup matrix for the shadcn ui CLI. Five supported templates (next, vite, react-router, astro, start) differ in: init flag, components.json.rsc default, alias-resolution system, Tailwind plugin, and dark-mode strategy. Each axis is non-substitutable. Pick by framework first, then apply the exact recipe.

Quick Reference Decision Tree

Q1. Which framework is the host project?
    Next.js (App or Pages Router)   --> Section: Next.js
    Vite + React                    --> Section: Vite
    React Router v7 (former Remix)  --> Section: React Router
    Astro + React integration       --> Section: Astro
    TanStack Start                  --> Section: TanStack Start
    Laravel + Inertia               --> Run `laravel new` first, then
                                        `npx shadcn@latest init` (no `-t`)
    other (CRA, Parcel, Rspack)     --> NOT supported by CLI; use Vite recipe
                                        and adapt alias config manually

Q2. Do I run rsc:true or rsc:false?
    framework has React Server Components (Next.js App Router, TanStack Start
        with RSC enabled) --> rsc:true
    framework is client-only (Vite, React Router v7 by default, Astro,
        Next.js Pages Router) --> rsc:false
    rule: NEVER set rsc:true unless the bundler actually compiles
          "use client" boundaries. Wrong value silently breaks SSR.

Q3. Which Tailwind version?
    Tailwind v4 (default for Vite, Next.js, Astro, TanStack Start in 2026)
        --> single CSS file with `@import "tailwindcss";`, NO tailwind.config.js,
            plugin: @tailwindcss/vite (Vite/TanStack Start/Astro) OR
            @tailwindcss/postcss (Next.js).
    Tailwind v3 (legacy projects only)
        --> tailwind.config.{js,ts} with `content` array, HSL space-separated
            CSS variables. See shadcn-errors-tailwind-v3-v4-migration.

Per-Framework Setup Matrix

Framework	Init flag	`rsc`	`tsx`	Alias system	Tailwind plugin	Dark-mode strategy
Next.js (App Router)	`-t next`	`true`	`true`	`tsconfig.json#paths` (`@/*`)	`@tailwindcss/postcss`	`next-themes` ThemeProvider in `app/layout.tsx`
Next.js (Pages Router)	`-t next`	`false`	`true`	`tsconfig.json#paths` (`@/*`)	`@tailwindcss/postcss`	`next-themes` ThemeProvider in `_app.tsx`
Vite + React	`-t vite`	`false`	`true`	`tsconfig.json` + `tsconfig.app.json` + `vite.config.ts#resolve.alias`	`@tailwindcss/vite`	Custom React Context ThemeProvider
React Router v7	`-t react-router`	`false`	`true`	tsconfig paths (`~/*`)	`@tailwindcss/vite`	Custom Context in `app/root.tsx`
Astro + React	`-t astro`	`false`	`true`	`tsconfig.json#paths` (`@/*`)	`@tailwindcss/vite`	Inline `<script is:inline>` in Layout
TanStack Start	`-t start`	`true`	`true`	tsconfig paths OR `package.json#imports`	`@tailwindcss/vite`	Custom Context in `__root.tsx`

ALWAYS use the matching -t flag. NEVER hand-edit components.json.rsc to true in a Vite project. NEVER omit the alias entry from vite.config.ts (TypeScript resolves but Vite's bundler will not).

Section: Next.js

ALWAYS pass -t next. App Router is the documented default; Pages Router still works but loses the auto-injected "use client" benefit.

# new project
pnpm create next-app@latest my-app
cd my-app
pnpm dlx shadcn@latest init -t next

# add components
pnpm dlx shadcn@latest add button

components.json for Next.js App Router:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "utils": "@/lib/utils",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

tsconfig.json without --src-dir:

{ "compilerOptions": { "paths": { "@/*": ["./*"] } } }

tsconfig.json with --src-dir:

{ "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }

ThemeProvider in app/layout.tsx:

// components/theme-provider.tsx
"use client"
import * as React from "react"
import { ThemeProvider as NextThemesProvider } from "next-themes"
export function ThemeProvider(props: React.ComponentProps<typeof NextThemesProvider>) {
  return <NextThemesProvider {...props} />
}

// app/layout.tsx
import { ThemeProvider } from "@/components/theme-provider"
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

ALWAYS set suppressHydrationWarning on <html>. Without it, next-themes will log a hydration mismatch on every page load because the server renders without a theme class and the client adds one before React hydrates.

For Pages Router, mount the same ThemeProvider in pages/_app.tsx and set components.json.rsc to false (Pages Router has no RSC).

Section: Vite

pnpm create vite@latest my-app --template react-ts
cd my-app
pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node
pnpm dlx shadcn@latest init -t vite
pnpm dlx shadcn@latest add button

vite.config.ts MUST register @tailwindcss/vite AND the @ alias:

import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
})

Vite's TypeScript template ships TWO tsconfig files. Both MUST declare the alias or the editor and the bundler will disagree:

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

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

src/index.css (Tailwind v4 single-line import):

@import "tailwindcss";

components.json for Vite: "rsc": false. ALWAYS. Vite has no concept of server components and the CLI will skip the "use client" directive if rsc is true, producing components that fail at runtime when they touch browser-only APIs.

Vite has NO next-themes equivalent. Use the custom React Context ThemeProvider in examples.md and mount it at the root of App.tsx.

Section: React Router v7 (former Remix)

pnpm create react-router@latest my-app
cd my-app
pnpm dlx shadcn@latest init -t react-router
pnpm dlx shadcn@latest add button

create-react-router pre-configures Tailwind and the ~/* alias. The shadcn CLI writes components.json with rsc:false and aliases pointing at ~/components/ui, ~/lib/utils etc. Imports use ~, NOT @:

import { Button } from "~/components/ui/button"

Loaders and actions are React Router primitives, not shadcn primitives. shadcn <Form> works with useFetcher or <Form method="post"> from react-router. See examples.md for the loader-driven pattern.

Dark mode: same custom React Context as Vite, mounted in app/root.tsx. The <Meta />, <Links />, and <Scripts /> from react-router stay intact; wrap <Outlet />.

Section: Astro

Astro is islands-first. Static HTML is shipped by default; React components hydrate only when given a client:* directive.

pnpm create astro@latest astro-app -- --template with-tailwindcss --install --add react --git
cd astro-app
pnpm dlx shadcn@latest init -t astro
pnpm dlx shadcn@latest add button

astro.config.mjs:

import { defineConfig } from "astro/config"
import react from "@astrojs/react"
import tailwindcss from "@tailwindcss/vite"
export default defineConfig({
  integrations: [react()],
  vite: { plugins: [tailwindcss()] },
})

tsconfig.json:

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } } }

components.json has rsc:false. Astro components (.astro files) are server-only by definition; shadcn components are React and need a hydration directive when interactive:

---
import { Button } from "@/components/ui/button"
import ModeToggle from "@/components/mode-toggle"
---
<!-- presentational, no JS needed -->
<Button>Static</Button>

<!-- interactive, MUST hydrate -->
<ModeToggle client:load />

client:load hydrates immediately. client:idle waits for requestIdleCallback. client:visible waits for intersection. client:only="react" skips SSR. ALWAYS pick the latest valid directive; never ship interactivity without one.

Dark mode in Astro: inline <script is:inline> in the Layout (runs before hydration to prevent flash). See examples.md.

Section: TanStack Start

pnpm dlx shadcn@latest init --template start
# or for an existing project:
pnpm dlx shadcn@latest init -t start
pnpm dlx shadcn@latest add card

TanStack Start supports RSC (newer feature). components.json ships with rsc:true when generated by the -t start template. The bundler is Vite under the hood; alias resolution can use either tsconfig paths or package.json#imports. Default is tsconfig paths with @/*.

Components import inside route files:

import { createFileRoute } from "@tanstack/react-router"
import { Card, CardHeader, CardTitle } from "@/components/ui/card"

export const Route = createFileRoute("/")({ component: App })
function App() { return <Card><CardHeader><CardTitle>Hi</CardTitle></CardHeader></Card> }

Dark mode: TanStack Start does NOT ship next-themes. Use the same custom Context pattern as Vite, mounted in app/routes/__root.tsx around <Outlet />.

Alias Setup Per Framework

ALWAYS keep tsconfig paths and the bundler alias in lockstep. A mismatch produces "module not found" at runtime even when the editor resolves it.

Framework	Editor (tsconfig)	Bundler	Astro/runtime
Next.js	`paths`: `"@/": ["./"]` or `["./src/*"]`	webpack/turbopack auto	n/a
Vite	`paths` in `tsconfig.json` AND `tsconfig.app.json`	`vite.config.ts#resolve.alias`	n/a
React Router	`paths`: `"~/": ["./app/"]` (auto-generated)	Vite under the hood	n/a
Astro	`paths`: `"@/": ["./src/"]`	Vite under the hood	`astro.config.mjs` integrations only
TanStack Start	`paths`: `"@/": ["./src/"]` OR `package.json#imports`	Vite	n/a

If components.json.aliases.ui = "@/components/ui" then tsconfig MUST resolve @/components/ui/button to ./src/components/ui/button.tsx (or ./components/ui/button.tsx without --src-dir). The bundler MUST agree. NEVER let them drift.

ThemeProvider Per Framework

Three distinct strategies. Mixing them is a recipe for hydration warnings.

Next.js : next-themes with <ThemeProvider attribute="class"> and suppressHydrationWarning on <html>. App Router places it in app/layout.tsx; Pages Router in pages/_app.tsx. Pages Router users also need a <Script> in _document.tsx to set the class before hydration, OR accept a flash.
Vite, React Router, TanStack Start : custom ThemeProvider using React Context + localStorage + matchMedia. No external library. Full code in examples.md.
Astro : inline <script is:inline> in the layout, runs before any React hydration, sets dark class on documentElement. The React ModeToggle island uses client:load and a useEffect that re-syncs the class. This is the only pattern that survives Astro's SSR-first model without a flash.

ALWAYS pick the strategy that matches the framework template flag. NEVER install next-themes in a Vite or Astro project; it depends on Next.js runtime APIs that are absent.

Companion Skills

shadcn-core-cli : full init, add, diff, build flag reference
shadcn-impl-component-install : per-component add workflow, dry-run, overwrite policy, monorepo -c flag
shadcn-impl-rsc-vs-client-boundaries : when each shadcn component needs "use client", validator agent, RSC-safe component list
shadcn-impl-theming-custom : token customization, oklch vs HSL, @theme inline, per-framework token wiring
shadcn-errors-tailwind-v3-v4-migration : migrating from tailwind.config.js + HSL to @import "tailwindcss" + oklch
shadcn-errors-cli-sync-mismatch : recovering from init overwriting customized components.json or globals.css

Reference Links

See methods.md for the init-command + tsconfig matrix per framework. See examples.md for end-to-end setups per framework. See anti-patterns.md for the five recurring init failures.