style-zx 0.0.8 → 0.0.9
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 +35 -30
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,18 +6,18 @@
|
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
9
|
+
- **Zero Runtime**: Styles are extracted to static CSS files during the build process. No runtime style injection or overhead.
|
|
10
|
+
- **Ultra Lightweight**: The plugin output is tiny (~5KB), ensuring minimal impact on your build process.
|
|
11
|
+
- **`zx` Prop**: Style any component directly with the `zx` prop (inspired by MUI's `sx` and other similar libraries).
|
|
12
|
+
- **TypeScript Support**: Full type safety for CSS properties and theme variables.
|
|
13
|
+
- **Theming**: Define a theme and access variables easily (e.g., `"$theme.colors.primary"`).
|
|
14
|
+
- **Aliases**: Shorthand properties for common styles (e.g., `p`, `m`, `px`, `my`, `bg`).
|
|
15
|
+
- **Nested Selectors**: Support for pseudo-classes and nested selectors (e.g., `&:hover`, `& > div`).
|
|
16
|
+
- **Vite Integration**: Seamless integration as a Vite plugin with HMR support.
|
|
17
17
|
|
|
18
18
|
## Installation
|
|
19
19
|
|
|
20
|
-
1.
|
|
20
|
+
1. **Install the package** (assuming local or published package):
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
23
|
npm install style-zx
|
|
@@ -25,15 +25,15 @@
|
|
|
25
25
|
yarn add style-zx
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
2.
|
|
28
|
+
2. **Add the Vite plugin** in `vite.config.ts`:
|
|
29
29
|
|
|
30
30
|
```typescript
|
|
31
31
|
import { defineConfig } from 'vite'
|
|
32
32
|
import react from '@vitejs/plugin-react'
|
|
33
|
-
import styleZx from 'style-zx/
|
|
33
|
+
import styleZx from 'style-zx/plugin'
|
|
34
34
|
|
|
35
35
|
export default defineConfig({
|
|
36
|
-
plugins: [
|
|
36
|
+
plugins: [styleZx(), react()],
|
|
37
37
|
})
|
|
38
38
|
```
|
|
39
39
|
|
|
@@ -56,7 +56,7 @@ Use the `zx` prop on any HTML element. Numeric values for dimensions are treated
|
|
|
56
56
|
|
|
57
57
|
### Theming
|
|
58
58
|
|
|
59
|
-
1.
|
|
59
|
+
1. **Define your theme** and create the hook:
|
|
60
60
|
|
|
61
61
|
```typescript
|
|
62
62
|
// src/style-zx/theme.ts
|
|
@@ -75,7 +75,7 @@ Use the `zx` prop on any HTML element. Numeric values for dimensions are treated
|
|
|
75
75
|
});
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
2.
|
|
78
|
+
2. **Use theme variables** in your components. You can reference them as strings starting with `$theme.`.
|
|
79
79
|
|
|
80
80
|
```tsx
|
|
81
81
|
import { useTheme } from './style-zx';
|
|
@@ -116,33 +116,38 @@ You can use standard CSS nesting syntax.
|
|
|
116
116
|
## Comparison & Concept
|
|
117
117
|
|
|
118
118
|
### The Concept
|
|
119
|
+
|
|
119
120
|
`style-zx` relies on **static analysis**. The build plugin scans your code for the `zx` prop, extracts the object literal, generates a unique class hash, creates CSS rules, and replaces the `zx` prop with a `className`.
|
|
120
121
|
|
|
121
122
|
### vs. Pigment CSS
|
|
123
|
+
|
|
122
124
|
Both libraries aim for zero-runtime CSS-in-JS.
|
|
123
|
-
|
|
124
|
-
-
|
|
125
|
+
|
|
126
|
+
- **Pigment CSS**: A more robust, complex solution often integrated with Next.js and MUI's ecosystem. It handles more complex dynamic scenarios but requires deeper integration. Also the project is not actively maintained at the moment.
|
|
127
|
+
- **Style-ZX**: A lightweight, Vite-first approach. It focuses on simplicity and the specific `zx` prop API. It's easier to set up for simple Vite projects but may have fewer features than Pigment.
|
|
125
128
|
|
|
126
129
|
### vs. Emotion / Styled-Components
|
|
127
|
-
|
|
128
|
-
-
|
|
130
|
+
|
|
131
|
+
- **Emotion/Styled-Components**: Runtime CSS-in-JS. They parse styles in the browser, generate classes, and inject tags. This offers great flexibility (dynamic props) but incurs a runtime performance cost (script execution + style recalculation).
|
|
132
|
+
- **Style-ZX**: No runtime cost. The browser just loads a CSS file.
|
|
129
133
|
|
|
130
134
|
### vs. Tailwind CSS
|
|
131
|
-
|
|
132
|
-
-
|
|
135
|
+
|
|
136
|
+
- **Tailwind**: Utility-first. You compose classes (`p-4 bg-white`).
|
|
137
|
+
- **Style-ZX**: Object-based. You write CSS-like objects (`{ p: 16, bg: 'white' }`). This is often preferred by developers who like keeping styles colocated but find long class strings hard to read.
|
|
133
138
|
|
|
134
139
|
## Caveats & Limitations
|
|
135
140
|
|
|
136
|
-
1.
|
|
137
|
-
-
|
|
138
|
-
-
|
|
139
|
-
-
|
|
140
|
-
2.
|
|
141
|
-
3.
|
|
141
|
+
1. **Static Analysis Only**: The values in `zx` must be statically analyzable at build time.
|
|
142
|
+
- ✅ `zx={{ color: 'red' }}`
|
|
143
|
+
- ✅ `zx={{ color: '$theme.colors.primary' }}` (if theme is static)
|
|
144
|
+
- ❌ `zx={{ color: props.color }}` (Dynamic props are **not** supported directly in the build step. Use CSS variables for dynamic values).
|
|
145
|
+
2. **Vite Only**: Currently designed specifically as a Vite plugin.
|
|
146
|
+
3. **No Dynamic Function Interpolations**: You cannot pass a function to `zx` that depends on runtime state.
|
|
142
147
|
|
|
143
148
|
## Gains
|
|
144
149
|
|
|
145
|
-
-
|
|
146
|
-
-
|
|
147
|
-
-
|
|
148
|
-
-
|
|
150
|
+
- **Performance**: Zero JS runtime for styles means faster TTI (Time to Interactive) and less main-thread work.
|
|
151
|
+
- **Bundle Size**: The plugin itself is extremely small (~5KB), keeping your dev dependencies lean.
|
|
152
|
+
- **Developer Experience**: Write styles in TypeScript right next to your components. Get autocomplete and type checking.
|
|
153
|
+
- **Maintainability**: Styles are scoped and colocated, reducing dead code and global namespace pollution.
|