solidjs-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SolidJS Patterns and Best Practices

SolidJS 模式与最佳实践

Comprehensive correctness and performance guide for SolidJS and SolidStart applications, maintained by OmniAura. Contains 49 rules across 9 categories, prioritized by impact to guide automated refactoring and code generation. Built from production experience migrating from React to SolidJS.

由OmniAura维护的SolidJS与SolidStart应用程序全面性正确性及性能指南。包含9个类别下的49条规则，按影响优先级排序，可指导自动化重构与代码生成。基于从React迁移至SolidJS的生产环境经验构建。

When to Apply

适用场景

Reference these guidelines when:

Writing new SolidJS components or SolidStart pages
Migrating React code to SolidJS
Implementing data fetching (Solid Query, createAsync, createResource)
Working with SolidStart server functions ("use server")
Reviewing code for reactivity correctness issues
Optimizing bundle size or rendering performance
Setting up state management (signals, stores, context)
Writing tests for reactive code

在以下场景中参考本指南：

编写新的SolidJS组件或SolidStart页面
将React代码迁移至SolidJS
实现数据获取（Solid Query、createAsync、createResource）
处理SolidStart服务器函数（"use server"）
审查代码中的响应式正确性问题
优化包体积或渲染性能
搭建状态管理（signals、stores、context）
为响应式代码编写测试

Rule Categories by Priority

按优先级划分的规则类别


reactivity-
data-
component-
state-
rendering-
start-
perf-
testing-
interop-

Priority	Category	Impact	Prefix
1	Reactivity Correctness	CRITICAL	`reactivity-`
2	Data Fetching & Server	CRITICAL	`data-`
3	Component Patterns	HIGH	`component-`
4	State Management	HIGH	`state-`
5	Rendering & Control Flow	MEDIUM-HIGH	`rendering-`
6	SolidStart Patterns	MEDIUM-HIGH	`start-`
7	Performance Optimization	MEDIUM	`perf-`
8	Testing	LOW-MEDIUM	`testing-`
9	External Interop	LOW	`interop-`


reactivity-
data-
component-
state-
rendering-
start-
perf-
testing-
interop-

优先级	类别	影响程度	前缀
1	响应式正确性	严重（CRITICAL）	`reactivity-`
2	数据获取与服务器端	严重（CRITICAL）	`data-`
3	组件模式	高（HIGH）	`component-`
4	状态管理	高（HIGH）	`state-`
5	渲染与控制流	中高（MEDIUM-HIGH）	`rendering-`
6	SolidStart 模式	中高（MEDIUM-HIGH）	`start-`
7	性能优化	中（MEDIUM）	`perf-`
8	测试	中低（LOW-MEDIUM）	`testing-`
9	外部互操作	低（LOW）	`interop-`

Quick Reference

速查指南

1. Reactivity Correctness (CRITICAL)

1. 响应式正确性（严重）

```
reactivity-no-destructure-props
```
- Never destructure props — breaks reactivity
```
reactivity-no-helper-access
```
- Access signals/stores directly in JSX, not via helpers
```
reactivity-no-set-map-signal
```
- Use store instead of Set/Map with signal for collections
```
reactivity-no-rest-spread
```
- Use splitProps instead of rest spread
```
reactivity-signals-not-refs
```
- Use signals for timing-sensitive state, not plain refs
```
reactivity-no-direct-mutation
```
- Never mutate store values directly
```
reactivity-no-effect-order
```
- Don't assume effect execution order
```
reactivity-cleanup-effects
```
- Always clean up effects with onCleanup
```
reactivity-on-explicit-tracking
```
- Use on() to break circular dependencies
```
reactivity-create-deferred
```
- Use createDeferred for expensive computations on rapid input
```
reactivity-create-reaction
```
- Use createReaction to separate tracking from side effects
```
reactivity-no-signal-capture
```
- Don't capture signals in closures outside reactive context

```
reactivity-no-destructure-props
```
- 切勿解构props——这会破坏响应式特性
```
reactivity-no-helper-access
```
- 在JSX中直接访问signals/stores，而非通过辅助函数
```
reactivity-no-set-map-signal
```
- 对于集合类型，使用store而非结合signal的Set/Map
```
reactivity-no-rest-spread
```
- 使用splitProps替代剩余扩展运算符
```
reactivity-signals-not-refs
```
- 对时间敏感的状态使用signals，而非普通refs
```
reactivity-no-direct-mutation
```
- 切勿直接修改store的值
```
reactivity-no-effect-order
```
- 不要假设effect的执行顺序
```
reactivity-cleanup-effects
```
- 始终使用onCleanup清理effects
```
reactivity-on-explicit-tracking
```
- 使用on()打破循环依赖
```
reactivity-create-deferred
```
- 对快速输入场景下的昂贵计算使用createDeferred
```
reactivity-create-reaction
```
- 使用createReaction将跟踪与副作用分离
```
reactivity-no-signal-capture
```
- 不要在响应式上下文之外的闭包中捕获signals

2. Data Fetching & Server (CRITICAL)

2. 数据获取与服务器端（严重）

```
data-no-destructure-query
```
- Never destructure Solid Query results
```
data-parallel-queries
```
- Don't create query waterfalls
```
data-guard-suspense
```
- Guard .data access to prevent unwanted Suspense
```
data-include-all-query-keys
```
- Include all dependencies in query keys
```
data-query-options-function
```
- Wrap query options in arrow function
```
data-mutation-invalidation
```
- Invalidate queries after mutations

```
data-no-destructure-query
```
- 切勿解构Solid Query的结果
```
data-parallel-queries
```
- 不要创建查询瀑布
```
data-guard-suspense
```
- 对.data的访问进行防护，以避免不必要的Suspense
```
data-include-all-query-keys
```
- 在查询键中包含所有依赖项
```
data-query-options-function
```
- 将查询选项包裹在箭头函数中
```
data-mutation-invalidation
```
- 执行mutation后使查询失效

3. Component Patterns (HIGH)

3. 组件模式（高）

```
component-no-early-return
```
- Don't return early before reactive primitives
```
component-merge-props
```
- Use mergeProps for reactive default values
```
component-split-props
```
- Use splitProps to separate and forward props

```
component-no-early-return
```
- 不要在响应式原语之前提前返回
```
component-merge-props
```
- 使用mergeProps处理响应式默认值
```
component-split-props
```
- 使用splitProps分离并转发props

4. State Management (HIGH)

4. 状态管理（高）

```
state-signal-vs-store
```
- Choose signal vs store based on update granularity
```
state-context-pattern
```
- Use typed context with store for global state
```
state-reconcile-async
```
- Use reconcile for fine-grained async updates
```
state-produce-complex-mutations
```
- Use produce() for complex store mutations
```
state-form-store
```
- Use createStore for multi-field form state

```
state-signal-vs-store
```
- 根据更新粒度选择signal或store
```
state-context-pattern
```
- 结合类型化context与store实现全局状态管理
```
state-reconcile-async
```
- 使用reconcile处理细粒度异步更新
```
state-produce-complex-mutations
```
- 使用produce()处理复杂的store变更
```
state-form-store
```
- 使用createStore处理多字段表单状态

5. Rendering & Control Flow (MEDIUM-HIGH)

5. 渲染与控制流（中高）

```
rendering-use-for-not-map
```
- Use
```
<For>
```
instead of .map() for lists
```
rendering-use-show-not-ternary
```
- Use
```
<Show>
```
instead of JSX conditionals
```
rendering-suspense-inside-show
```
- Place Suspense inside conditionals (LazyShow pattern)
```
rendering-use-switch-match
```
- Use Switch/Match for multi-branch conditionals
```
rendering-error-boundary
```
- Wrap risky components in ErrorBoundary
```
rendering-index-vs-for
```
- Choose between For and Index based on what changes

```
rendering-use-for-not-map
```
- 对于列表渲染，使用
```
<For>
```
而非.map()
```
rendering-use-show-not-ternary
```
- 使用
```
<Show>
```
而非JSX条件运算符
```
rendering-suspense-inside-show
```
- 将Suspense置于条件语句内部（LazyShow模式）
```
rendering-use-switch-match
```
- 使用Switch/Match处理多分支条件
```
rendering-error-boundary
```
- 用ErrorBoundary包裹风险组件
```
rendering-index-vs-for
```
- 根据变更内容选择For或Index

6. SolidStart Patterns (MEDIUM-HIGH)

6. SolidStart 模式（中高）

```
start-use-server-validation
```
- Always validate "use server" function inputs
```
start-createasync-not-resource
```
- Use createAsync + query() for data loading
```
start-route-preloading
```
- Always define route preload functions

```
start-use-server-validation
```
- 始终对"use server"函数的输入进行验证
```
start-createasync-not-resource
```
- 使用createAsync + query()处理数据加载
```
start-route-preloading
```
- 始终定义路由预加载函数

7. Performance Optimization (MEDIUM)

7. 性能优化（中）

```
perf-lazy-load-heavy-components
```
- Lazy load heavy components
```
perf-create-selector
```
- Use createSelector for single-selection in large lists
```
perf-memo-expensive
```
- Use createMemo for expensive derived computations
```
perf-route-code-splitting
```
- Use lazy() for route-level code splitting
```
perf-skeleton-suspense
```
- Use skeleton components for Suspense fallbacks
```
perf-use-transition
```
- Use useTransition for non-blocking async updates
```
perf-render-effect
```
- Use createRenderEffect for synchronous DOM measurements

```
perf-lazy-load-heavy-components
```
- 懒加载重型组件
```
perf-create-selector
```
- 在大型列表中使用createSelector实现单选
```
perf-memo-expensive
```
- 使用createMemo处理昂贵的派生计算
```
perf-route-code-splitting
```
- 使用lazy()实现路由级代码分割
```
perf-skeleton-suspense
```
- 为Suspense回退状态使用骨架屏组件
```
perf-use-transition
```
- 使用useTransition处理非阻塞异步更新
```
perf-render-effect
```
- 使用createRenderEffect处理同步DOM测量

8. Testing (LOW-MEDIUM)

8. 测试（中低）

```
testing-createroot
```
- Wrap reactive test code in createRoot
```
testing-render-components
```
- Use render() and Testing Library for component tests
```
testing-render-hook
```
- Use renderHook for testing custom hooks
```
testing-async-waitfor
```
- Use waitFor for async component testing
```
testing-mock-hoisted
```
- Use vi.hoisted with vi.mock for proper mock hoisting

```
testing-createroot
```
- 将响应式测试代码包裹在createRoot中
```
testing-render-components
```
- 使用render()与Testing Library进行组件测试
```
testing-render-hook
```
- 使用renderHook测试自定义hooks
```
testing-async-waitfor
```
- 使用waitFor进行异步组件测试
```
testing-mock-hoisted
```
- 结合vi.hoisted与vi.mock实现正确的mock提升

9. External Interop (LOW)

9. 外部互操作（低）

```
interop-from-browser-apis
```
- Use from() to bridge browser APIs into reactive signals
```
interop-observable-export
```
- Use observable() to expose signals to external libraries

```
interop-from-browser-apis
```
- 使用from()将浏览器API桥接至响应式signals
```
interop-observable-export
```
- 使用observable()向外部库暴露signals

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/reactivity-no-destructure-props.md
rules/data-parallel-queries.md
rules/start-use-server-validation.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Impact rating and tags
Additional context and references

阅读单个规则文件以获取详细说明与代码示例：

rules/reactivity-no-destructure-props.md
rules/data-parallel-queries.md
rules/start-use-server-validation.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及解释
正确代码示例及解释
影响评级与标签
额外上下文与参考资料

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有规则扩展说明的完整指南：

AGENTS.md

Legacy Files

遗留文件

The following files contain additional detailed patterns and are being migrated into individual rules:

```
reactivity.md
```
- Reactivity fundamentals
```
explicit-tracking.md
```
- on() and untrack() patterns
```
state-patterns.md
```
- State management patterns
```
anti-patterns.md
```
- Common anti-patterns
```
advanced-primitives.md
```
- Secondary primitives
```
external-interop.md
```
- from() and observable() patterns
```
solid-query.md
```
- Solid Query patterns
```
performance.md
```
- Performance optimization
```
testing.md
```
- Testing patterns

以下文件包含更多详细模式，正逐步迁移至单个规则中：

```
reactivity.md
```
- 响应式编程基础
```
explicit-tracking.md
```
- on()与untrack()模式
```
state-patterns.md
```
- 状态管理模式
```
anti-patterns.md
```
- 常见反模式
```
advanced-primitives.md
```
- 二级原语
```
external-interop.md
```
- from()与observable()模式
```
solid-query.md
```
- Solid Query模式
```
performance.md
```
- 性能优化
```
testing.md
```
- 测试模式