Skip to content

QUICKSTART.md

Latest commit

 

History

History
165 lines (117 loc) · 4.75 KB

QUICKSTART.md

File metadata and controls

165 lines (117 loc) · 4.75 KB
Raw

ShellUI Quick Start

This quick start uses ShellUI 0.4.0-alpha.3, a prerelease, with Tailwind CSS 4.3.2. The CLI runs on .NET 8 or later and works in Blazor projects on .NET 8, 9 and 10.

Prerequisites

  • .NET 8 SDK or later
  • A Blazor project
  • The ShellUI.CLI tool
  • Node.js and npm only when choosing --tailwind npm

Check the SDK with:

dotnet --version

Install the CLI

A global tool is invoked as shellui:

dotnet tool install -g ShellUI.CLI --version 0.4.0-alpha.3
shellui --version

If the project has a .NET tool manifest, use dotnet shellui instead. See CLI installation.

Create and initialize a project

dotnet new blazor -n MyBlazorApp
cd MyBlazorApp
shellui init --yes --tailwind standalone

init detects the project type and sets up:

  • Components/UI/
  • wwwroot/input.css and wwwroot/app.css
  • tailwind.config.js
  • Build/ShellUI.targets
  • shellui.json
  • Components/_Imports.razor when it is present
  • The host file used by the project

Standalone mode downloads Tailwind 4.3.2 once per machine, into ~/.shellui/bin, and does not require Node.js. To use npm instead:

shellui init --yes --tailwind npm

npm mode requires Node.js and npm. The current CLI invokes npm through cmd, so use standalone mode on non-Windows systems or run the npm commands manually.

Add components

Add one target, several space-separated targets, or comma-separated targets:

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

Dependencies are copied automatically. Use --force to overwrite an existing component source file:

shellui add button --force

Use the exact names shown by shellui list. There are 93 direct targets; dependency-only registry entries are not direct targets.

Use a component

After init, the project imports YourProject.Components.UI. For a project named MyBlazorApp:

@using MyBlazorApp.Components.UI

<Card Class="max-w-md">
    <h2 class="text-lg font-semibold">Welcome</h2>
    <Input Placeholder="Enter your email" Type="email" />
    <Button>Click me</Button>
</Card>

card installs its component parts automatically. button and input are separate targets, so add them explicitly when using them.

Tailwind CSS v4

Edit wwwroot/input.css, not the generated wwwroot/app.css. The current v4 input begins with:

@import "tailwindcss";
@custom-variant dark (&:is(.dark *));

:root {
  --primary: oklch(0.55 0.22 264.53);
  --primary-foreground: oklch(1 0 0);
}

@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

For an npm-based Tailwind workflow, use the v4 CLI package:

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

shellui init --tailwind npm --yes performs the package installation and creates the build integration. A normal build also runs Tailwind:

dotnet build

Manage installed components

shellui list
shellui list --installed
shellui list --available
shellui update button
shellui update button card
shellui update --all
shellui remove button card

update rewrites the selected source files and skips any you have changed (use --force to overwrite those). Commit before running it.

remove accepts component names separated by spaces and has no options. It removes the named files, but it does not perform reverse-dependency cleanup. For layout blocks such as dashboard-02, remove lists the files that still use the layout. Check references before removing a component that another component may use.

Apply a theme

The CLI supports tweakcn themes:

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 by default and writes shellui.theme.lock. Use --emit-override for a separate CSS file. Run theme update from the project root to re-fetch the recorded theme.

Troubleshooting

  • Use shellui for a global tool and dotnet shellui for a local manifest.
  • Run shellui list to verify a target name.
  • Check that wwwroot/input.css contains @import "tailwindcss";.
  • Check ~/.shellui/bin for standalone mode or run npm install for npm mode.
  • Run dotnet build to invoke the generated Tailwind target.

Related documentation