Getting started

Installation

Packages, styles and the theme script — from nothing to your first component.

Packages

terminal

npm install @toimetdev/pathlogs-core @toimetdev/pathlogs-hooks @toimetdev/pathlogs-tokens

core depends on the other two, so strictly speaking one package would be enough. Installing all three is still more convenient: that way @toimetdev/pathlogs-hooks and @toimetdev/pathlogs-tokens show up in your package.json as direct dependencies rather than as a detail of someone else's tree.

React 18 or newer is a peer dependency. The packages pull in nothing else: no clsx, no radix, no date utilities.

Styles

Three imports into your main CSS file — usually `globals.css`:

src/app/globals.css

@import "tailwindcss";

@import "@toimetdev/pathlogs-tokens/styles/index.css";
@import "@toimetdev/pathlogs-core/styles/components.css";
@import "@toimetdev/pathlogs-tokens/styles/tailwind.css";

What each line does:

tokens/styles/index.css — variables, base styles, animations and the styles for drag-scrollable strips;
core/styles/components.css — the look of the package's components;
tokens/styles/tailwind.css — the bridge to Tailwind v4: turns tokens into the utilities bg-surface, text-muted, border-edge.

Theme script

The theme lives in localStorage and in a data-theme attribute on <html>. So the page never flashes the wrong theme before hydration, that attribute is set by a tiny synchronous script in <head>:

src/app/layout.tsx

import { themeScript } from "@toimetdev/pathlogs-tokens";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: themeScript() }} />
      </head>
      <body>{children}</body>
    </html>
  );
}

Checking it works

If everything is wired up, buttons look like this and follow the theme:

If nothing is styled, it is almost always the import order, or the CSS landing in the wrong file. The components do not rely on Tailwind, so missing styles simply mean components.css never arrived.

Without Tailwind

The core components are marked up with their own pl-* classes and work in a project with any CSS framework, or none at all. In that case two imports are enough:

css

@import "@toimetdev/pathlogs-tokens/styles/index.css";
@import "@toimetdev/pathlogs-core/styles/components.css";

Registry widgets are a different matter: they are marked up with Tailwind. If your project has no Tailwind, say so when configuring the CLI (--no-tailwind) and it will warn you that widgets will arrive unstyled.