Skip to content

Commit 7eca624

Browse files
owjs3901owjs3901
authored
Docs: core concept
docs: update core concepts documentation
2 parents 9f071db + 956b3b1 commit 7eca624

File tree

4 files changed

+193
-0
lines changed

4 files changed

+193
-0
lines changed

‎apps/landing/src/app/(detail)/docs/LeftMenu.tsx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,21 @@ export function LeftMenu() {
77
<VStack gap="6px">
88
<MenuItem to="/docs/overview">Overview</MenuItem>
99
<MenuItem to="/docs/installation">Installation</MenuItem>
10+
<MenuItem
11+
subMenu={[
12+
{ to: '/docs/core-concepts/zero-runtime', children: 'Zero Runtime' },
13+
{
14+
to: '/docs/core-concepts/no-dependencies',
15+
children: 'No Dependencies',
16+
},
17+
{
18+
to: '/docs/core-concepts/style-storage',
19+
children: 'Style Storage',
20+
},
21+
]}
22+
>
23+
Core Concepts
24+
</MenuItem>
1025
<MenuItem to="/docs/features">Features</MenuItem>
1126
<MenuItem
1227
subMenu={[

‎apps/landing/src/app/(detail)/docs/core-concepts/no-dependencies/page.mdx‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
export const metadata = {
2+
title: "Core-Concepts",
3+
alternates: {
4+
canonical: '/docs/core-concepts/no-dependencies',
5+
}
6+
7+
}
8+
9+
# No Dependencies
10+
11+
Devup UI converts pure React source code without additional UI runtime code.
12+
13+
This section explains what “No Dependencies” means in practice, why it matters, and how Devup UI achieves it without requiring client-side style engines, extra plugins, or manual pre-generation steps.
14+
15+
## Motivation
16+
17+
- Many CSS-in-JS libraries rely on JavaScript at runtime to compute styles, inject `<style>` tags, or resolve variables.
18+
- When dynamic values (e.g., variables, expressions) are used, these solutions often fall back to runtime dependencies—a partial solution that reintroduces costs.
19+
- In frameworks like Next.js, such runtime-style systems frequently cannot be used inside RSC (React Server Components).
20+
21+
We asked: Can we deliver truly zero-runtime CSS that also works in RSC—without extra UI runtime code?
22+
23+
Our approach is grounded in static analysis. Once code is built and shipped, it should contain the definitive answer—no further computation required on the client.
24+
25+
## What “No Dependencies” Means
26+
27+
- No UI runtime code is added to your bundle for styling.
28+
- No extra plugins, pre-generation scripts, or PostCSS configs are required.
29+
- Pure React remains your source of truth; styles are compiled at build time into static CSS.
30+
- Works in RSC and the edge/runtime contexts where client-side style engines are unavailable or undesired.
31+
32+
## How It Works?
33+
34+
1. Parse your React source into an AST using Rust-based tooling.
35+
2. Perform static analysis to extract all style semantics from components and props.
36+
3. Resolve and de-duplicate styles, generating compact, atomic class names.
37+
4. Emit a new AST with class names applied and a CSS virtual file populated with the minimal rule set.
38+
5. Bundle emits static CSS and class-applied markup—no client-side style engine.
39+
40+
## Compatibility
41+
42+
- Next.js (including RSC): Safe to use without runtime style engines.
43+
- Vite, Rsbuild, Webpack: Supported via official plugins.
44+
- Works with server-first and edge contexts that restrict DOM/JS-based style injection.
45+
46+
## Class Naming Policy
47+
48+
- Class names never start with a digit (to satisfy CSS constraints).
49+
- We minimize class name length while maintaining safety.
50+
For example, tokens like `ad` may be flagged by content blockers; we emit `a-d` instead to break filter matches.
51+
- To avoid common ad-blocker heuristics, we segment suspicious tokens by inserting a hyphen(`-`).
52+
- Example mappings:
53+
- `ad` → `a-d`
54+
- Scope: applied to Devup UI–generated atomic class tokens only; user-supplied `className` strings are not rewritten.
55+
- Allowed characters include `a`–`z`, combinations like `az`, `a0`, and safe hyphen/underscore placements.
56+
57+
## Advantages if Using
58+
59+
Devup UI brings the convenience of CSS-in-JS together with the performance of static CSS—delivering the best of both worlds with no extra UI runtime dependencies.
60+
61+
1. **Zero runtime**: All styles are compiled to static CSS at build time.
62+
2. **De-duplication**: Identical styles are generated once and reused globally.
63+
3. **Performance**: Rust-powered pipeline provides fast, scalable builds.
64+
4. **Smaller bundles**: No redundant classes, no UI runtime styling code.

‎apps/landing/src/app/(detail)/docs/core-concepts/style-storage/page.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
export const metadata = {
2+
title: "Core-Concepts",
3+
alternates: {
4+
canonical: '/docs/core-concepts/style-storage',
5+
}
6+
7+
}
8+
9+
# Style Storage
10+
11+
Devup UI removes duplication by storing and looking up styles in a single storage, reusing the same atomic class for identical style declarations.
12+
13+
This document explains the de-duplication principle, the requirement for a single storage, its relationship with build order, the single CSS output option, per-page CSS splitting, and the key–value style storage with deterministic ordering.
14+
15+
### How it works
16+
17+
- Even if the same style appears in multiple places, it is generated as exactly one atomic class (no duplicates).
18+
- If a style already exists in storage, the existing class is reused. Otherwise, a new class is generated and registered.
19+
20+
### Why a single storage is required
21+
22+
- To guarantee deduplication and reuse, there must be exactly one style storage in the build pipeline.
23+
- Multiple storages fragment duplicate detection and may cause the same style to be generated with different class names.
24+
25+
## Single CSS option
26+
27+
- `single css`: emit all generated styles as a single CSS output file.
28+
- Default is `false`.
29+
- Pros: simplifies loading paths; maximizes browser caching benefits.
30+
- Cons: for very large apps or when styles vary significantly per page, it can increase initial load.
31+
32+
### Style ordering and key–value storage
33+
34+
- The storage uses a key–value model: the style signature as the key, and the generated class name and rule as the value.
35+
- Rule order follows the discovery order during the build. Rules with equal priority are merged deterministically to keep the output predictable.
36+
37+
### Per‑page CSS splitting (optional)
38+
39+
- You can split CSS per page so that only the rules needed for that page are loaded.
40+
- This can improve initial load time in large applications. A reasonable caution is that using only a single global CSS might constrain initial load for some pages.
41+
- Excessive splitting can increase network requests and fragment caching. Balance it according to your app size and navigation patterns.
42+
43+
### Relation to Zero Runtime
44+
45+
- Style Storage is resolved at compile time; no client‑side style engine or extra runtime computation is required.
46+
- For background and rationale, see the Zero Runtime guide: [Zero Runtime](/docs/core-concepts/zero-runtime)

‎apps/landing/src/app/(detail)/docs/core-concepts/zero-runtime/page.mdx‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
export const metadata = {
2+
title: 'Zero-Runtime',
3+
alternates: {
4+
canonical: '/docs/core-concepts/zero-runtime',
5+
},
6+
}
7+
8+
# Zero Runtime
9+
10+
Devup UI is a CSS-in-JS preprocessor that requires no runtime. By moving style computation to build time, Devup UI avoids browser runtime overhead. We are building a preprocessor that accounts for all syntactic cases.
11+
12+
## End-to-end Process
13+
14+
### 1. **Source Code Input**
15+
16+
Your application code written in JSX/TSX/JS/TS is provided as input.
17+
18+
For example, consider the following `<Button>` component.
19+
20+
```tsx
21+
<Button
22+
_hover={{ bg: 'red' }}
23+
bg="blue"
24+
className="btn"
25+
color="white"
26+
fontSize={['10px', null, null, '16px']}
27+
>
28+
Click me!
29+
</Button>
30+
```
31+
32+
### 2. **AST Transformation (Rust + oxc)**
33+
34+
We use **oxc** (a Rust-based JavaScript tooling suite) to convert code into an AST (Abstract Syntax Tree).
35+
36+
- **Lexer**: breaks source code into tokens
37+
- **Parser**: structures tokens into an AST
38+
39+
This step is required to enable optimizations performed later by the **Style Storage**.
40+
41+
### **3. Style Caching Logic (Core logic)**
42+
43+
Core logic written in Rust + WebAssembly optimizes styles by consulting the Style Storage: **Style Storage Check**
44+
45+
- **Existing style?** → Reuse the existing class name (cached result)
46+
- **New style?** → Generate a new class and register it
47+
48+
### **4. Code Generation Paths**
49+
50+
Based on the caching results in step 3, two parallel outputs are produced.
51+
52+
- **New AST**
53+
- Generate a new AST in TypeScript
54+
- Inject resolved style class names
55+
56+
- **Update CSS Virtual File**
57+
- Append newly generated style classes to the CSS virtual file
58+
- Do not regenerate existing styles
59+
60+
### **5. Final Output**
61+
62+
The bundler (Vite, Rsbuild, Next.js, Webpack) emits optimized code.
63+
64+
```html
65+
<button className="btn a b c d e">Click me!</button>
66+
```
67+
68+
Inline style props are compiled into **atomic CSS classes**, achieving zero runtime.

0 commit comments

Comments
 (0)