[feat]: Document use of aliases 'components' and 'utils'

[sebastiancarlos]

Feature description

First of all, thanks a lot for your work on shadcn/ui!

The documentation for components.json aliases doesn't explain the purpose of the components and utils aliases. I would particularly like to know how they differ from the ui and lib aliases.

To figure out how these paths are used, I ran the command npx shadcn@latest init (to create a Next.js project on an empty folder), followed by npx shadcn@latest add --all to add all components.

Files were created in @/lib, @/hooks and @ui, but not for the components and utils aliases. This makes me wonder if those other aliases are used at all currently.

I think any clarification here would help users better understand the project structure. Thanks for your time!

Note: A clue about the component vs ui aliases might be this phrase found in the changelog:

The add command is now much more capable. You can now add UI components but also import more complex components (coming soon).

[spennyp]

Likely related to this bug where alias is ignored: https://github.com/shadcn-ui/ui/issues/5433

[shadcn]

This issue has been automatically marked as stale due to two years of inactivity. It will be closed in 7 days unless there’s further input. If you believe this issue is still relevant, please leave a comment or provide updated details. Thank you.

[shadcn]

No stale. Something went wrong with the stale bot.

[boan-anbo]

Second documenting the fields, especially what "component" means compared to "ui". There are AI generated documents trying to explain the difference but doesn't make much sense: https://medium.com/@enayetflweb/understanding-components-json-in-shadcn-ui-73e889aab0c6

[tresorama]

What i found is that...

alias.ui

Low Level components go here.
Like Button, Select... and all others from https://ui.shadcn.com/docs/components

alias.component

Blocks components go here.
Like this dashboard-01, installed with pnpx shadcn@latest add dashboard-01

---

I usually customize aliases like this

// components.json
{
"tailwind": {
    "config": "",
    "css": "src/components/ds/tw.css",
    // ...omitted
  },
"aliases": {
    "components": "@/components/shadcn/blocks",
    "ui": "@/components/shadcn/ui",
    "lib": "@/components/shadcn/lib",
    "utils": "@/components/shadcn/lib/cn",
    "hooks": "@/components/shadcn/hooks"
  }
}

.
├── app
│   ├── dashboard
│   │   ├── data.json
│   │   └── page.tsx
│   ├── favicon.ico
│   ├── layout.tsx
│   └── page.tsx
└── components
    ├── ds
    │   ├── cn.ts
    │   ├── index.ts
    │   └── tw.css
    ├── mine
    └── shadcn
        ├── blocks
        │   └── dashboard-01
        │       └── components
        │           ├── app-sidebar.tsx
        │           ├── chart-area-interactive.tsx
        │           ├── data-table.tsx
        │           ├── nav-documents.tsx
        │           ├── nav-main.tsx
        │           ├── nav-secondary.tsx
        │           ├── nav-user.tsx
        │           ├── section-cards.tsx
        │           └── site-header.tsx
        ├── hooks
        │   └── use-mobile.ts
        ├── lib
        │   └── cn.ts
        └── ui
            ├── avatar.tsx
            ├── badge.tsx
            ├── breadcrumb.tsx
            ├── button.tsx
            ├── card.tsx
            ├── chart.tsx
            ├── checkbox.tsx
            ├── drawer.tsx
            ├── dropdown-menu.tsx
            ├── input.tsx
            ├── label.tsx
            ├── select.tsx
            ├── separator.tsx
            ├── sheet.tsx
            ├── sidebar.tsx
            ├── skeleton.tsx
            ├── sonner.tsx
            ├── table.tsx
            ├── tabs.tsx
            ├── toggle-group.tsx
            ├── toggle.tsx
            └── tooltip.tsx