Getting Started

Welcome to Nostromo UI! This guide helps you get started with our UI library.

Prerequisites

Node.js: >= 20.0.0
React: >= 18.0.0
TypeScript: >= 5.0.0 (recommended)
Tailwind CSS: >= 4.0.0 (theming is CSS-first; there is no JS preset)

Installation

From npm

Install Nostromo UI in your project:


# npm
npm install @jarllyng/nostromo
 
# pnpm
pnpm add @jarllyng/nostromo
 
# yarn
yarn add @jarllyng/nostromo

From GitHub (development/local)

For local development, you can clone the repository:


git clone https://github.com/JarlLyng/nostromo-ui.git
cd nostromo-ui
pnpm install
pnpm build

Peer Dependencies

Nostromo UI requires the following peer dependencies:


npm install react react-dom
npm install -D tailwindcss

Theming Setup

1. Import the CSS

One import pulls in Tailwind, the design tokens and the base layer; the second picks a theme.


/* In your main stylesheet */
@import "@jarllyng/nostromo/tailwind.css";
@import "@jarllyng/nostromo/themes/nostromo.css"; /* or mother / lv-426 / sulaco */

If your setup imports CSS from JavaScript instead:


// In your entry file (e.g. main.tsx)
import "@jarllyng/nostromo/tailwind.css";
import "@jarllyng/nostromo/themes/nostromo.css";

2. Apply Theme


<html data-theme="nostromo" data-color-scheme="light">
  <!-- Your content -->
</html>

3. Customize Brand Colors (Optional)


[data-theme="mybrand"] {
  --nostromo-color-brand-500: 220 100% 50%; /* Your brand blue */
  --nostromo-color-brand-600: 220 100% 40%; /* Darker variant */
}

Tokens live in the --nostromo-* namespace and hold bare HSL channels. The library maps them onto Tailwind’s --color-* namespace internally, so bg-brand-500 picks your value up automatically.

Complete Theming Guide →

Basic Usage


import { Button } from "@jarllyng/nostromo";
 
export default function MyComponent() {
  return <Button>Click me</Button>;
}

Tailwind CSS Configuration

There isn’t any. On Tailwind v4 the design tokens are registered through @theme inside @jarllyng/nostromo/tailwind.css, so importing that file is the whole setup — no tailwind.config.js, no preset, no content array.

The import also declares an @source pointing at the library’s own compiled output, because Tailwind v4 skips node_modules when scanning for class names. That means you do not need to add the package to a content glob yourself.

Project Setup Examples

Next.js (App Router):


// app/layout.tsx
import "@jarllyng/nostromo/tailwind.css";
import "@jarllyng/nostromo/themes/nostromo.css";
 
export default function RootLayout({ children }) {
  return (
    <html data-theme="nostromo" data-color-scheme="light">
      <body>{children}</body>
    </html>
  );
}

Vite:


// main.tsx
import "@jarllyng/nostromo/tailwind.css";
import "@jarllyng/nostromo/themes/nostromo.css";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
 
ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Dark Mode Toggle:


// Theme toggle example
function ThemeToggle() {
  const [isDark, setIsDark] = useState(false);
 
  useEffect(() => {
    document.documentElement.setAttribute(
      "data-color-scheme",
      isDark ? "dark" : "light",
    );
  }, [isDark]);
 
  return (
    <button onClick={() => setIsDark(!isDark)}>
      {isDark ? "Light" : "Dark"} Mode
    </button>
  );
}

Next Steps

Explore components to see all available components - every page has live, editable examples
Read API documentation for detailed props
Check theming guide for customization

Support

Have questions? Check our FAQ or contact us on GitHub.