Skip to content

FAQ.md

Latest commit

 

History

History
271 lines (183 loc) · 8.73 KB

FAQ.md

File metadata and controls

271 lines (183 loc) · 8.73 KB
Raw

ShellUI Frequently Asked Questions

Answers for the current ShellUI source and the currently published packages.

Versions and target frameworks

Which version should I use?

Use the latest stable release, 0.3.5. It uses Tailwind CSS 4.3.2. The 0.4.0-alpha.3 prerelease, with 93 direct component targets, needs --version 0.4.0-alpha.3:

dotnet tool install -g ShellUI.CLI

The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10. The ShellUI.Components NuGet package targets .NET 8, 9 and 10. (0.4.0-alpha.3 and the 0.3 line need .NET 10 for both.)

Which command prefix should I use?

Use shellui for a global installation. After dotnet new tool-manifest and a local tool install, use dotnet shellui.

shellui --version
dotnet shellui --version

NuGet and CLI

What is the difference?

ShellUI.Components is a NuGet package. It provides compiled Razor components in the ShellUI.Components namespace and is updated by changing the package version and restoring the project.

The CLI copies source templates into the application. Components go in Components/UI/, and layout blocks go in Components/Layout/. You own and edit those files.

dotnet add package ShellUI.Components
shellui init
shellui add button card

The package and CLI can be used in the same project, but avoid defining the same component in both namespaces. Choose the package or the local source for a given component.

Can the CLI add several components at once?

Yes. add accepts space-separated names, comma-separated names, or both:

shellui add button input card
shellui add button,input,card
shellui add button,card dialog

Use the exact names printed by shellui list. Dependency-only entries are installed automatically and are not counted among the 93 direct targets.

Which names should I use?

Use the registry names, such as button, input, card, dialog, dropdown, date-picker, radio-group, file-upload, data-table, and chart. Do not translate a target into a guessed component name.

Tailwind and Node.js

Do I need Node.js?

Not for standalone mode:

shellui init --yes --tailwind standalone

Standalone mode downloads the Tailwind 4.3.2 CLI once per machine (into ~/.shellui/bin, or SHELLUI_CACHE_DIR) and the generated build target runs it from there. Projects hold no copy of the binary, and later projects set up offline. The binary is a build tool: it never ships with your app, which only gets the generated app.css.

npm mode is also supported. It requires Node.js and npm:

shellui init --yes --tailwind npm
npm install -D tailwindcss@^4.3.2 @tailwindcss/cli@^4.3.2
npx @tailwindcss/cli -i ./wwwroot/input.css -o ./wwwroot/app.css --watch

The npm commands are Tailwind v4 commands. The generated wwwroot/input.css uses @import "tailwindcss";; wwwroot/app.css is generated output. The current CLI invokes npm through cmd; on non-Windows systems use standalone mode or run the npm commands manually.

Managing CLI components

How do I list components?

shellui list
shellui list --installed
shellui list --available

There are 93 direct targets. Use the command output as the authoritative name list.

What happens when I update a component?

update rewrites the selected components from the current templates and installs any dependencies they gained:

shellui update button
shellui update button card
shellui update --all

Running shellui update without names also updates all installed components. Files you have changed since the CLI wrote them are skipped; add --force to overwrite them. There is no diff or merge, so commit first.

What happens when I remove a component?

remove deletes the named component files and updates shellui.json. It has no options and does not perform reverse-dependency cleanup. Layout blocks such as dashboard-02 are removed from Components/Layout, and remove lists the files that still use the layout (usually Routes.razor):

shellui remove button
shellui remove button card

If another component still uses a removed file, update that usage or remove the dependent component yourself.

Configuration

What does shellui.json contain?

The serialized properties are PascalCase. The main fields are:

Field Meaning
Schema Schema identifier
Style default, new-york, or minimal
ComponentsPath Usually Components/UI
LayoutPath Usually Components/Layout
Tailwind Tailwind settings
InstalledComponents Installed component records
ProjectType Detected Blazor project type

A representative Tailwind and component record is:

{
  "Style": "default",
  "ComponentsPath": "Components/UI",
  "LayoutPath": "Components/Layout",
  "Tailwind": {
    "Enabled": true,
    "Version": "4.3.2",
    "Method": "standalone",
    "ConfigPath": "tailwind.config.js",
    "CssPath": "wwwroot/app.css"
  },
  "InstalledComponents": [
    {
      "Name": "button",
      "Version": "0.4.0-alpha.3",
      "InstalledAt": "2026-01-01T00:00:00Z",
      "IsCustomized": false
    }
  ],
  "ProjectType": 1
}

IsCustomized is metadata only. It does not provide a merge workflow, and update overwrites the file.

Which files does init create or update?

  • Components/UI/
  • wwwroot/input.css
  • wwwroot/app.css
  • tailwind.config.js
  • Build/ShellUI.targets
  • shellui.json
  • Components/_Imports.razor when it is present

The host file is Components/App.razor for a Blazor Web App or wwwroot/index.html for a standalone WebAssembly project.

Theming

Can I apply a tweakcn theme?

Yes:

shellui theme init <url-or-id> --yes --tailwind standalone
shellui theme apply <url-or-id>
shellui theme apply <url-or-id> --emit-override wwwroot/theme.css
shellui theme update

theme apply updates wwwroot/input.css unless --emit-override is used. The command records the source in shellui.theme.lock, and theme update re-fetches that source.

Existing projects and troubleshooting

How do I override a component's classes?

Pass them in Class. Components combine their own classes with yours through Shell.Cn, and when two classes set the same CSS property under the same variants, yours win:

<Button Class="px-8 bg-destructive">Delete</Button>

The button's own px-4 and bg-primary are dropped, so you don't need Tailwind's ! important modifier. Variants are separate: hover:bg-primary/90 stays unless you also pass a hover:bg-… class. Classes Cn doesn't recognise are always kept.

Can I put ShellUI in a Razor class library shared by several apps?

Yes, for example one library used by a Blazor Web App and a MAUI Blazor Hybrid app. Run shellui init in the library; it recognises a Razor class library and prints what each app needs: links to _content/<Library>/app.css and shellui.js, the theme script, @source lines for markup that lives in an app, and prerender: false for apps that restore state from browser storage. See Using ShellUI from a Razor class library.

Can I use ShellUI in an existing Blazor app?

Yes. Run the CLI from the project root:

cd MyExistingApp
shellui init --yes --tailwind standalone
shellui add button card
dotnet build

Review the changes to Components/App.razor, Components/_Imports.razor, the project file, and the generated Tailwind files before committing them.

The command is not found

Use the prefix that matches the installation:

shellui --version
dotnet shellui --version

For a local tool, run dotnet tool restore from the directory containing .config/dotnet-tools.json.

A component is not found

Run:

shellui list

Use the exact target name shown in the list.

Tailwind output is stale

Check that wwwroot/input.css exists and starts with the Tailwind v4 import, then run:

dotnet build

For standalone mode, check ~/.shellui/bin. For npm mode, run npm install.

Package updates and licensing

How do I update the NuGet package?

Pass the version explicitly:

dotnet add package ShellUI.Components

Then restore and build the project.

What license does ShellUI use?

The repository uses the MIT license. See LICENSE.txt.

Related documentation