react-tenant-theme 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +224 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# react-tenant-theme
|
|
2
|
+
|
|
3
|
+
> A lightweight, production-ready theming engine for multi-tenant React applications.
|
|
4
|
+
|
|
5
|
+
[]()
|
|
6
|
+
[]()
|
|
7
|
+
[]()
|
|
8
|
+
|
|
9
|
+
**Docs:** [Live documentation & examples](https://react-tenant-theme-docs.vercel.app) · **npm:** [react-tenant-theme](https://www.npmjs.com/package/react-tenant-theme)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## ✨ Why This Exists
|
|
14
|
+
|
|
15
|
+
Modern SaaS applications often require:
|
|
16
|
+
|
|
17
|
+
- Multi-tenant branding
|
|
18
|
+
- Light/Dark mode per tenant
|
|
19
|
+
- Scalable design token systems
|
|
20
|
+
- SSR compatibility
|
|
21
|
+
- Zero visual flicker on reload
|
|
22
|
+
|
|
23
|
+
Most theming solutions become fragile at scale.
|
|
24
|
+
|
|
25
|
+
**react-tenant-theme** provides a clean, architecture-first approach to solving this problem using CSS variables and a structured tenant → theme → token model.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 🔑 Key Features
|
|
30
|
+
|
|
31
|
+
- ✅ Multi-tenant support
|
|
32
|
+
- ✅ Per-tenant theme switching
|
|
33
|
+
- ✅ Type-safe token definitions
|
|
34
|
+
- ✅ CSS variable-based design tokens
|
|
35
|
+
- ✅ SSR-safe (Next.js compatible)
|
|
36
|
+
- ✅ No flash of default theme
|
|
37
|
+
- ✅ LocalStorage persistence
|
|
38
|
+
- ✅ Minimal runtime overhead
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 📦 Installation
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm install react-tenant-theme
|
|
46
|
+
# or
|
|
47
|
+
pnpm add react-tenant-theme
|
|
48
|
+
# or
|
|
49
|
+
yarn add react-tenant-theme
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 🚀 Quick Start
|
|
55
|
+
|
|
56
|
+
### 1️⃣ Define Tenants & Themes
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
import type { TenantDefinition } from "react-tenant-theme";
|
|
60
|
+
|
|
61
|
+
const tenants: TenantDefinition[] = [
|
|
62
|
+
{
|
|
63
|
+
id: "acme",
|
|
64
|
+
name: "Acme Inc",
|
|
65
|
+
defaultThemeId: "light",
|
|
66
|
+
themes: [
|
|
67
|
+
{
|
|
68
|
+
id: "light",
|
|
69
|
+
name: "Light",
|
|
70
|
+
tokens: {
|
|
71
|
+
"color-bg": "#ffffff",
|
|
72
|
+
"color-fg": "#111111",
|
|
73
|
+
"color-primary": "#2563eb"
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
id: "dark",
|
|
78
|
+
name: "Dark",
|
|
79
|
+
tokens: {
|
|
80
|
+
"color-bg": "#0b1020",
|
|
81
|
+
"color-fg": "#e5e7eb",
|
|
82
|
+
"color-primary": "#60a5fa"
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
]
|
|
86
|
+
}
|
|
87
|
+
];
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
### 2️⃣ Wrap Your Application
|
|
93
|
+
|
|
94
|
+
```tsx
|
|
95
|
+
import { ThemeProvider } from "react-tenant-theme";
|
|
96
|
+
|
|
97
|
+
<ThemeProvider
|
|
98
|
+
tenants={tenants}
|
|
99
|
+
initialTenantId="acme"
|
|
100
|
+
config={{ prefix: "rt" }}
|
|
101
|
+
>
|
|
102
|
+
<App />
|
|
103
|
+
</ThemeProvider>
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
### 3️⃣ Use the Hook
|
|
109
|
+
|
|
110
|
+
```tsx
|
|
111
|
+
import { useThemeEngine } from "react-tenant-theme";
|
|
112
|
+
|
|
113
|
+
const { tenant, theme, setTenant, setTheme } = useThemeEngine();
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## 🎨 Styling with CSS Variables
|
|
119
|
+
|
|
120
|
+
The library generates scoped CSS variables:
|
|
121
|
+
|
|
122
|
+
```css
|
|
123
|
+
body {
|
|
124
|
+
background: var(--rt-color-bg);
|
|
125
|
+
color: var(--rt-color-fg);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
button {
|
|
129
|
+
background: var(--rt-color-primary);
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Switching tenant or theme updates all tokens instantly.
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 🏗 Architecture Overview
|
|
138
|
+
|
|
139
|
+
react-tenant-theme is structured into three layers:
|
|
140
|
+
|
|
141
|
+
### 1️⃣ Tenant Layer
|
|
142
|
+
Represents a SaaS customer or brand.
|
|
143
|
+
|
|
144
|
+
### 2️⃣ Theme Layer
|
|
145
|
+
Represents visual variants (light, dark, brand).
|
|
146
|
+
|
|
147
|
+
### 3️⃣ Token Layer
|
|
148
|
+
Maps tokens to scoped CSS variables:
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
color-primary → --rt-color-primary
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The runtime engine:
|
|
155
|
+
|
|
156
|
+
- Validates tenant/theme relationships
|
|
157
|
+
- Applies tokens safely
|
|
158
|
+
- Persists user preferences
|
|
159
|
+
- Prevents hydration mismatches
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## ⚡ SSR & Hydration Safety
|
|
164
|
+
|
|
165
|
+
- Uses an isomorphic layout effect
|
|
166
|
+
- Hydrates before first paint
|
|
167
|
+
- Avoids flash-of-default-theme
|
|
168
|
+
- Safe for Next.js / Vite SSR
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 💾 Persistence Strategy
|
|
173
|
+
|
|
174
|
+
Saved to:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
localStorage["react-tenant-theme"]
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Format:
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{
|
|
184
|
+
"tenantId": "acme",
|
|
185
|
+
"themeId": "dark"
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## 🧠 Real-World Use Cases
|
|
192
|
+
|
|
193
|
+
- White-label SaaS dashboards
|
|
194
|
+
- Enterprise admin panels
|
|
195
|
+
- Multi-brand B2B platforms
|
|
196
|
+
- Internal enterprise tools
|
|
197
|
+
- Client-customizable UI systems
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## 🛣 Roadmap
|
|
202
|
+
|
|
203
|
+
- [ ] Configurable storage key
|
|
204
|
+
- [ ] Cookie-based persistence
|
|
205
|
+
- [ ] Pre-hydration inline script
|
|
206
|
+
- [ ] DevTools extension
|
|
207
|
+
- [ ] Tailwind plugin integration
|
|
208
|
+
- [ ] Token validation utilities
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## 🤝 Contributing
|
|
213
|
+
|
|
214
|
+
Contributions welcome. See [GitHub](https://github.com/rusty-jnr/react-tenant-theme) to fork, open issues, or submit PRs.
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## 📄 License
|
|
219
|
+
|
|
220
|
+
MIT
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
Built to address real-world multi-tenant theming challenges in scalable React applications.
|