Getting Started

gsxui components are copy-in: the CLI vendors real .gsx source into your own module. You can also import the gsxui package directly.

1. Install the CLIs

go install github.com/gsxhq/gsx/cmd/gsx@latest
go install github.com/gsxhq/gsxui/cmd/gsxui@latest

2. Initialize your project

Create a fresh GSX app, then initialize gsxui inside it:

gsx init app --yes
cd app
gsxui init

gsxui initialized.
  css:  web/gsxui/index.css
  js:   web/gsxui/index.js
  vite: Tailwind CSS configured
  next: gsxui add button

For the unmodified npm/Vite scaffold produced by gsx init --yes, this is the complete setup. gsxui init:

installs Tailwind CSS and wires it into vite.config.ts and web/main.js
vendors the gsxui CSS and JS entries into web/gsxui/
installs the class merger (ui/merge/merge.go) that lets caller classes override component styles (see Theming)

Rerunning it is safe — nothing is duplicated.

Manual integration

If you customized the Vite config, entry file, package manager, or gsxui paths, gsxui initstops before writing anything and prints what to wire up yourself:

Automatic integration currently supports an unmodified gsx init npm/Vite scaffold with the default gsxui JS and CSS paths.

Integrate this project manually:
  npm install --save-dev tailwindcss@^4.3.3 @tailwindcss/vite@^4.3.3 tw-animate-css@^1.4.0
  vite.config.ts: import tailwindcss from "@tailwindcss/vite" and add tailwindcss() to plugins
  web/main.js: import "./gsxui/index.js" and import "./gsxui/index.css"

Or, to run without Vite entirely, delete vite.config.ts and web/main.js and
re-run gsxui init: it will vendor everything self-contained (no npm), and you
serve the gsxui JS directory statically, load index.js with one
<script type="module"> tag, and build index.css with any Tailwind v4 tool
(e.g. npx @tailwindcss/cli -i web/gsxui/index.css -o dist.css).

Not using Vite — or npm — at all? See npm-free: gsxui initdetects the missing scaffold and initializes without either.

3. Add components

gsxui add button card

adding: button card
done — build with: go build ./...

Dependencies come along automatically — gsxui add native-select also vendors icon. You own every file this writes: gsxui add never touches a file you've modified unless you pass --overwrite, which is also how you refresh components after upgrading the gsxui binary (discarding local edits to those files).

4. Your first page

gsx init already scaffolded a working app. Replace the Index component in app.gsx with a Card around a Button, adding the ui import:

import "app/ui"

component Index(title string) {
	<Layout title={title}>
		<div class="flex min-h-svh items-center justify-center bg-background p-8 text-foreground">
			<ui.Card class="w-full max-w-sm">
				<ui.CardHeader>
					<ui.CardTitle>Hello, gsxui</ui.CardTitle>
					<ui.CardDescription>Your first page.</ui.CardDescription>
				</ui.CardHeader>
				<ui.CardContent>
					<ui.Button>Click me</ui.Button>
				</ui.CardContent>
			</ui.Card>
		</div>
	</Layout>
}

Then start the development loop:

go tool gsx dev

gsx dev watches your sources, rebuilds the server, and reloads the browser on save. Open the printed URL to see your Card and Button in gsxui's default theme. Next: restyle it.