Getting Started

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

Prerequisites

These are the published package’s own requirements, taken from its engines and peerDependencies. Building the library itself asks for more, and CONTRIBUTING.md says what.

Node.js: >= 20.0.0
React: ^18.2.0 or ^19
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.