2026-03-04 14:18:44 -08:00
# Lit-Only Architecture (No Build)
2026-03-04 11:13:15 -08:00
2026-03-04 14:18:44 -08:00
A minimal, no-build web application using only Lit web components with local state management.
> **Note:** This is the `lit-only` branch. For the full-featured version with Zustand state management and IndexedDB persistence, see the `main` branch.
2026-03-04 11:13:15 -08:00
2026-03-04 12:23:40 -08:00
## For TSX/React Developers
2026-03-04 14:18:44 -08:00
If you're coming from React/TSX, here's how this minimal architecture maps to familiar concepts:
2026-03-04 12:23:40 -08:00
| React/TSX Pattern | This Architecture |
|-------------------|-------------------|
2026-03-04 14:18:44 -08:00
| `useState` | Lit's `static properties` with `state: true` |
| Props drilling | Property passing via `.prop=${value}` |
| Custom events | `CustomEvent` with `bubbles: true` |
2026-03-04 12:23:40 -08:00
| JSX | Lit's `html` tagged template literals |
| CSS-in-JS / CSS Modules | Lit's `css` tagged template literals |
2026-03-04 14:18:44 -08:00
| React Router | Simple route state in root component |
2026-03-04 12:23:40 -08:00
| Build step (Vite/Webpack) | Import maps (no build!) |
### Key Differences
1. **No Virtual DOM** : Lit uses native Web Components with efficient DOM updates
2. **No Build Step** : Import maps let you use npm packages directly from CDN
2026-03-04 14:18:44 -08:00
3. **Local State Only** : Each component manages its own state, parent manages shared state
4. **Event-Based Communication** : Child components emit events, parent handles them
5. **Tagged Templates** : Instead of JSX, use `html\` < div > ...</ div > \``
2026-03-04 12:23:40 -08:00
## Architecture Overview
* **Lit-based web components** - Standards-based, framework-agnostic UI
* **No-build tooling** - Import maps only, no bundler required
2026-03-04 14:18:44 -08:00
* **Local state management** - Component properties and state
* **Event-driven** - CustomEvents for child-to-parent communication
2026-03-04 11:13:15 -08:00
2026-03-04 14:18:44 -08:00
## Project Structure
2026-03-04 11:13:15 -08:00
```
2026-03-04 14:18:44 -08:00
components/
app-root.js ← Root component with shared state
nav-bar.js ← Navigation component
page-home.js ← Home page component
page-items.js ← Items page component
index.html ← Entry point with inline importmap
README.md
tasks.md
2026-03-04 11:13:15 -08:00
```
2026-03-04 14:18:44 -08:00
## Data Flow Pattern
2026-03-04 12:23:40 -08:00
2026-03-04 14:18:44 -08:00
### Parent-to-Child (Props)
2026-03-04 12:23:40 -08:00
2026-03-04 14:18:44 -08:00
```javascript
// Parent passes data down
html`<child-component .items=${this.items}></child-component>`
// Child receives via properties
static properties = {
items: { type: Array }
}
```
### Child-to-Parent (Events)
```javascript
// Child emits event
this.dispatchEvent(new CustomEvent('add-item', {
detail: { item: newItem },
bubbles: true,
composed: true
}))
// Parent listens
html`<child-component @add-item=${(e) => this.handleAdd(e.detail.item)}></child-component>`
2026-03-04 12:23:40 -08:00
```
2026-03-04 14:18:44 -08:00
## State Management Pattern
2026-03-04 12:23:40 -08:00
```mermaid
graph TD
2026-03-04 14:18:44 -08:00
A[app-root] -->|.user, .items, .route| B[nav-bar]
A -->|.user, .items| C[page-home]
A -->|.items| D[page-items]
B -->|@navigate event| A
D -->|@add -item event| A
D -->|@remove -item event| A
2026-03-04 12:23:40 -08:00
style A fill:#f9f ,stroke:#333 ,stroke-width:2px
style B fill:#bbf ,stroke:#333 ,stroke-width:2px
2026-03-04 14:18:44 -08:00
style C fill:#bfb ,stroke:#333 ,stroke-width:2px
style D fill:#bfb ,stroke:#333 ,stroke-width:2px
2026-03-04 12:23:40 -08:00
```
## Quick Start Example
2026-03-04 14:18:44 -08:00
### 1. Define a Component
2026-03-04 12:23:40 -08:00
```javascript
// components/counter.js
import { LitElement, html, css } from 'lit'
class Counter extends LitElement {
2026-03-04 14:18:44 -08:00
static properties = {
count: { type: Number, state: true }
}
constructor() {
super()
this.count = 0
}
2026-03-04 12:23:40 -08:00
static styles = css`
button { padding: 1rem; font-size: 1.2rem; }
`
render() {
return html`
< div >
2026-03-04 14:18:44 -08:00
< p > Count: ${this.count}< / p >
< button @click =${() = > this.count++}>
2026-03-04 12:23:40 -08:00
Increment
< / button >
< / div >
`
}
}
customElements.define('my-counter', Counter)
```
2026-03-04 14:18:44 -08:00
### 2. Use in HTML (no build step!)
2026-03-04 12:23:40 -08:00
```html
<!DOCTYPE html>
< html >
< head >
< script type = "importmap" >
{
"imports": {
2026-03-04 14:18:44 -08:00
"lit": "https://esm.sh/lit@3 "
2026-03-04 12:23:40 -08:00
}
}
< / script >
< / head >
< body >
< script type = "module" src = "components/counter.js" > < / script >
< my-counter > < / my-counter >
< / body >
< / html >
2026-03-04 11:13:15 -08:00
```
2026-03-04 12:23:40 -08:00
2026-03-04 14:18:44 -08:00
## Component Communication Patterns
### Pattern 1: Shared State in Root
```javascript
class AppRoot extends LitElement {
static properties = {
items: { type: Array, state: true }
}
constructor() {
super()
this.items = []
}
addItem(item) {
this.items = [...this.items, item]
}
render() {
return html`
< child-component
.items=${this.items}
@add =${(e) => this.addItem(e.detail.item)}
>< / child-component >
`
}
}
```
### Pattern 2: Local State in Component
```javascript
class MyComponent extends LitElement {
static properties = {
_draft: { type: String, state: true }
}
constructor() {
super()
this._draft = ''
}
render() {
return html`
< input
.value=${this._draft}
@input =${e => this._draft = e.target.value}
/>
`
}
}
```
2026-03-04 12:23:40 -08:00
## Benefits Over React/TSX
✅ **No build step** - Edit and refresh, instant feedback
2026-03-04 14:18:44 -08:00
✅ **Minimal dependencies** - Just Lit, nothing else
2026-03-04 12:23:40 -08:00
✅ **Smaller bundle** - No framework runtime, just standards
✅ **Better encapsulation** - Shadow DOM, scoped styles
✅ **Framework agnostic** - Works anywhere, even in React apps
✅ **Future-proof** - Built on web standards
2026-03-04 14:18:44 -08:00
✅ **Easy to learn** - Simple mental model, no complex state management
## When to Use This vs. Full Stack
### Use Lit-Only When:
- Building small to medium apps
- Don't need persistence
- State is simple and hierarchical
- Want maximum simplicity
### Use Full Stack (main branch) When:
- Need IndexedDB persistence
- Complex state shared across many components
- Need cross-tab synchronization
- Want time-travel debugging
- Building larger applications
2026-03-04 12:23:40 -08:00
## See Also
- [tasks.md ](./tasks.md ) - Current issues and improvements
- [Lit Documentation ](https://lit.dev )
- [Web Components ](https://developer.mozilla.org/en-US/docs/Web/Web_Components )
2026-03-04 14:18:44 -08:00
- [Import Maps ](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap )
