litcn

litcn

Lightweight Lit components with shadcn-inspired theming, Tailwind CSS v4 styling, and Lucide icons.

View Live Demo & Interactive Documentation → Explore all components with live examples, copy-paste code snippets, and interactive playgrounds.

Features

• Two Types of Components: Functional components for stateless UI elements (Button, Card, Badge) and Custom elements for components with internal state (theme-toggle, language-selector)
• shadcn/ui Themes: Compatible with shadcn/ui design system. Built-in default and Claude themes. Dark mode support via dark class
• TypeScript First: Full TypeScript support with type definitions. IDE autocomplete for all components and i18n
• Tailwind CSS v4: Modern styling with the latest Tailwind features
• Lucide Icons: Complete icon set with tree-shaking support

Quick Start

1. Installation

npm install lit litcn

2. Setup Tailwind CSS v4

Option A: Vite Plugin (Recommended)

npm install -D @tailwindcss/vite

// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
   plugins: [tailwindcss()],
});

Option B: Tailwind CLI

npm install -D @tailwindcss/cli

// package.json scripts
"scripts": {
  "dev": "tailwindcss -i ./src/app.css -o ./dist/app.css --watch",
  "build": "tailwindcss -i ./src/app.css -o ./dist/app.css --minify"
}

3. Configure CSS

/* src/app.css */

/* Import theme (includes dark mode and utilities) */
@import "litcn/styles/themes/default.css";

/* Tell Tailwind to scan litcn components */
@source "../node_modules/litcn/dist";

/* Import Tailwind */
@import "tailwindcss";

4. Configure TypeScript (Important for LitElement)

If you're using LitElement components with decorators (custom elements or your own components extending LitElement), you must configure TypeScript properly:

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "useDefineForClassFields": false  // Critical for LitElement reactivity!
  }
}

Note: useDefineForClassFields: false is essential for LitElement's @property() and @state() decorators to work correctly. Without this setting, reactive properties won't trigger updates properly.

5. Use Components

import { html, render } from "lit";
import { Button } from "litcn/dist/Button.js";
import { Card } from "litcn/dist/Card.js";
import { icon } from "litcn/dist/icons.js";
import "litcn/dist/ThemeToggle.js";
import { Send } from "lucide";
import "./app.css";

const App = () => html`
   <div class="p-8 bg-background text-foreground min-h-screen">
      <!-- litcn components with internal state are full LitElement instances with custom tags -->
      <theme-toggle class="fixed top-4 right-4"></theme-toggle>

      <!-- litcn components without internal state are functional components returning TemplateResult -->
      ${Card(html`
         <h1 class="text-2xl font-bold mb-4">Hello litcn!</h1>

         ${Button({
            children: html`
               ${icon(Send, "sm")}
               <span>Send Message</span>
            `,
         })}
      `)}
   </div>
`;

render(App(), document.body);

Components

Actions

• Buttons - All button variants and states
• Copy Button - Copy text to clipboard
• Download Button - Download files

Layout

• Cards - Content containers with header, content, and footer sections
• Separators - Visual dividers
• Split Panel - Resizable layouts
• Dialogs - Modal dialogs

Forms

• Inputs - Text, email, password inputs
• Textareas - Multi-line text input
• Selects - Dropdown selections
• Checkboxes - Boolean selections
• Switches - Toggle controls
• Labels - Form labels

Feedback

• Badges - Status indicators
• Alerts - Important messages with variants
• Progress - Progress indicators

Content

• Code Block - Syntax highlighted code with copy functionality
• Markdown - Rendered markdown with KaTeX math support
• Diff Viewer - Code difference viewer

Utilities

• Theme Toggle - Dark/light mode switcher
• Language Selector - i18n language switcher
• icon() - Render Lucide icons with size variants
• i18n() - Internationalization support

Component Types

Functional Components

Stateless components that return TemplateResult:

import { Button, Card, Badge } from "litcn";

// Use directly in templates
${Button({ variant: "primary", children: "Click me" })}
${Badge({ children: "New" })}

Custom Elements

Stateful components that extend LitElement:

// Custom elements are automatically registered when using the main import
import "litcn";

// Use as HTML tags
<theme-toggle></theme-toggle>
<code-block .code=${"console.log('Hello')"} language="javascript"></code-block>

Tree-Shaking & Bundle Optimization

IMPORTANT: The root index (litcn) now only exports core utilities (component system, i18n, and icons). Individual components are not exported from the root to encourage optimal tree-shaking.

Recommended Import Strategy

// ✔ Optimal - only includes what you use (~50-100KB)
import { Button } from "litcn/dist/Button.js";
import { Card } from "litcn/dist/Card.js";
import { icon } from "litcn/dist/icons.js";
import "litcn/dist/ThemeToggle.js";

// ⚠️ Root index only exports core utilities (NOT components)
import { i18n, setTranslations, createComponent } from "litcn";

What's exported from the root index:

• Component system: ComponentLitBase, createComponent, defineComponent, styleComponent, and related types
• i18n system: i18n, setTranslations, setLanguage, getCurrentLanguage, defaultEnglish, defaultGerman
• Icons: icon function and related utilities

Available component paths:

• Functional components: /dist/Button.js, /dist/Card.js, /dist/Input.js, /dist/Select.js, /dist/Checkbox.js, etc.
• Custom elements: /dist/ThemeToggle.js, /dist/CodeBlock.js, /dist/MarkdownBlock.js, /dist/LanguageSelector.js, etc.
• Core utilities: /dist/mini.js (fc, createState, refs)

Bundle Size:

• Direct imports: ~50-100KB (only what you use)
• Importing all components: ~400KB+ (if you manually import everything)

Themes

litcn uses shadcn/ui compatible themes with CSS custom properties for colors, borders, and shadows.

Built-in Themes

• default - Clean, modern theme
• claude - Claude-inspired theme

Switch themes by importing a different CSS file:

@import "litcn/styles/themes/claude.css";

Dark Mode

Toggle dark mode via the dark class:

document.documentElement.classList.toggle("dark");

Or use the built-in <theme-toggle> component.

Custom Themes

For custom themes and theme generators:

• shadcn/ui themes
• Tweakcn theme generator

Internationalization

1. Define TypeScript Interface (for autocomplete)

declare module "litcn" {
   interface i18nMessages extends LiteCNRequiredMessages {
      Welcome: string;
      Settings: string;
      cartItems: (count: number) => string;
      greeting: (name: string, time: string) => string;
   }
}

2. Set Translations

import { setTranslations, defaultEnglish, defaultGerman } from "litcn";

const translations = {
   en: {
      ...defaultEnglish, // Includes required messages like "Copy", "Copied!"
      Welcome: "Welcome",
      Settings: "Settings",
      cartItems: (count: number) =>
         count === 0 ? "Your cart is empty" : count === 1 ? "1 item in your cart" : `${count} items in your cart`,
      greeting: (name: string, time: string) => `Good ${time}, ${name}!`,
   },
   de: {
      ...defaultGerman, // Includes required messages like "Kopieren", "Kopiert!"
      Welcome: "Willkommen",
      Settings: "Einstellungen",
      cartItems: (count: number) =>
         count === 0
            ? "Ihr Warenkorb ist leer"
            : count === 1
              ? "1 Artikel im Warenkorb"
              : `${count} Artikel im Warenkorb`,
      greeting: (name: string, time: string) => `Guten ${time}, ${name}!`,
   },
};

setTranslations(translations);

3. Use in Your App

import { i18n, getCurrentLanguage, setLanguage } from "litcn";

// Simple strings
${i18n("Welcome")}
${i18n("Settings")}

// Functions with parameters
${i18n("cartItems")(3)}  // "3 items in your cart"
${i18n("greeting")("Alice", "morning")}  // "Good morning, Alice!"

// Language management
getCurrentLanguage()  // "en" or "de"
setLanguage("de")     // switches to German, reloads page

// Add language selector to UI
<language-selector></language-selector>

Development

The litcn repository includes both the component library and a comprehensive example gallery showcasing all components.

Setup

# Clone the repository
git clone https://github.com/shaneholloman/litcn.git
cd litcn

# Install dependencies
npm install

Development Workflow

Run the development server with hot module replacement:

npm run dev

This command orchestrates:

• TypeScript compilation of the litcn library (watching for changes in /src, outputting to /dist)
• Vite dev server for the example gallery (in /example), automatically picking up the latest litcn builds

Open the URL displayed by Vite (typically http://localhost:5173) to view the example gallery. Any changes to either the litcn source code or the example application will trigger automatic rebuilds and browser updates through HMR.

Project Structure

litcn/
├── src/              # litcn component library source
├── dist/             # Compiled library output
├── styles/           # Theme CSS files
├── example/          # Interactive component gallery
│   └── src/
│       └── pages/    # Individual component demos
└── package.json      # Library package configuration

Code Quality

Run formatting and linting checks for both the library and example:

npm run check

This command:

• Formats all code with Prettier
• Lints with Biome for code quality and style consistency
• Type-checks both the library and example with TypeScript
• Automatically runs on git commit via Husky pre-commit hooks

Building for Production

# Build the library
npm run build

# Build the example gallery
cd example && npm run build

Publishing & Deployment

Publishing to npm

# Build and publish the library to npm
npm run build
npm publish --access public

Deploying the Documentation Site

# Quick sync (when only source files changed)
./scripts/run.sh sync

# Full deploy (when Docker/infrastructure changed)
./scripts/run.sh deploy

The sync command builds and syncs files without restarting services, while deploy also restarts the Docker containers on the server.

Examples

See the /example directory for a complete working example with all components, or visit the live demo.

Resources

• npm Package
• GitHub Repository
• Live Demo
• Lit Documentation
• Tailwind CSS v4

License

MIT