claude-toolkit 0.15.0 → 0.17.0-rc.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.
Files changed (70) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +55 -14
  3. package/bin/cli.ts +75 -19
  4. package/core/skills/ct-typescript-conventions/SKILL.md +59 -1
  5. package/package.json +6 -7
  6. package/src/generator.ts +66 -27
  7. package/src/refresh-hint.ts +95 -0
  8. package/templates/skill-rules.base.json +29 -6
  9. package/bin/postinstall.mjs +0 -69
  10. package/docs/README.md +0 -59
  11. package/docs/agents/code-reviewer.md +0 -76
  12. package/docs/agents/github-workflow.md +0 -98
  13. package/docs/best-practices/capacitor/README.md +0 -64
  14. package/docs/best-practices/capacitor/capacitor-8.md +0 -60
  15. package/docs/best-practices/capacitor/capgo-setup.md +0 -151
  16. package/docs/best-practices/capacitor/channels-and-rollouts.md +0 -101
  17. package/docs/best-practices/capacitor/live-updates-ota.md +0 -75
  18. package/docs/best-practices/capacitor/security-encryption.md +0 -68
  19. package/docs/best-practices/solidjs/README.md +0 -43
  20. package/docs/best-practices/solidjs/anti-patterns.md +0 -166
  21. package/docs/best-practices/solidjs/component-patterns.md +0 -131
  22. package/docs/best-practices/solidjs/context-and-global-state.md +0 -131
  23. package/docs/best-practices/solidjs/control-flow.md +0 -124
  24. package/docs/best-practices/solidjs/data-fetching.md +0 -205
  25. package/docs/best-practices/solidjs/effects-and-lifecycle.md +0 -113
  26. package/docs/best-practices/solidjs/performance.md +0 -100
  27. package/docs/best-practices/solidjs/props-patterns.md +0 -100
  28. package/docs/best-practices/solidjs/reactivity-model.md +0 -104
  29. package/docs/best-practices/solidjs/signals-and-state.md +0 -78
  30. package/docs/best-practices/solidjs/stores-and-nested-state.md +0 -111
  31. package/docs/best-practices/solidjs/typescript-integration.md +0 -186
  32. package/docs/best-practices/testing/README.md +0 -84
  33. package/docs/best-practices/testing/playwright-e2e.md +0 -649
  34. package/docs/best-practices/testing/storybook-interaction.md +0 -455
  35. package/docs/best-practices/testing/vitest-unit.md +0 -451
  36. package/docs/best-practices/typescript/README.md +0 -45
  37. package/docs/best-practices/typescript/any-and-unknown.md +0 -73
  38. package/docs/best-practices/typescript/deriving-vs-decoupling.md +0 -83
  39. package/docs/best-practices/typescript/discriminated-unions.md +0 -75
  40. package/docs/best-practices/typescript/enums-alternatives.md +0 -72
  41. package/docs/best-practices/typescript/essential-patterns.md +0 -119
  42. package/docs/best-practices/typescript/generics-patterns.md +0 -105
  43. package/docs/best-practices/typescript/micro-opinions.md +0 -87
  44. package/docs/best-practices/typescript/runtime-validation.md +0 -62
  45. package/docs/best-practices/typescript/satisfies-operator.md +0 -100
  46. package/docs/best-practices/typescript/tsconfig-cheat-sheet.md +0 -129
  47. package/docs/best-practices/typescript/type-organization.md +0 -64
  48. package/docs/best-practices/typescript/type-vs-interface.md +0 -80
  49. package/docs/commands/code-quality.md +0 -36
  50. package/docs/commands/onboard.md +0 -63
  51. package/docs/commands/pr-review.md +0 -91
  52. package/docs/commands/pr-summary.md +0 -50
  53. package/docs/commands/proto-check.md +0 -59
  54. package/docs/commands/ticket.md +0 -56
  55. package/docs/skills/code-style.md +0 -26
  56. package/docs/skills/systematic-debugging.md +0 -70
  57. package/docs/skills/testing-patterns.md +0 -140
  58. package/docs/skills/typescript-conventions.md +0 -191
  59. package/docs/skills/verification-before-completion.md +0 -103
  60. package/docs/stacks/capacitor-ota.md +0 -145
  61. package/docs/stacks/cloudflare-d1-kv.md +0 -144
  62. package/docs/stacks/esnext-idioms.md +0 -25
  63. package/docs/stacks/i18n-typesafe.md +0 -141
  64. package/docs/stacks/playwright-patterns.md +0 -179
  65. package/docs/stacks/protobuf-contracts.md +0 -85
  66. package/docs/stacks/rust-wasm-patterns.md +0 -106
  67. package/docs/stacks/solidjs-patterns.md +0 -110
  68. package/docs/stacks/storybook-patterns.md +0 -177
  69. package/docs/stacks/vanilla-extract-patterns.md +0 -115
  70. package/docs/stacks/vite-vitest-patterns.md +0 -485
@@ -1,131 +0,0 @@
1
- # Component Patterns
2
-
3
- > Sources: [TypeScript](https://docs.solidjs.com/configuration/typescript), [Props](https://docs.solidjs.com/concepts/components/props) — SolidJS Docs
4
-
5
- ## Component Type Hierarchy
6
-
7
- SolidJS provides four component types for TypeScript:
8
-
9
- ```typescript
10
- import type { Component, ParentComponent, FlowComponent, VoidComponent } from "solid-js";
11
- ```
12
-
13
- | Type | Children | Use Case |
14
- |---|---|---|
15
- | `Component<P>` | No opinion | Base type, generic components |
16
- | `ParentComponent<P>` | Optional `JSX.Element` | Components that accept children |
17
- | `FlowComponent<P, C>` | Required, typed | Control flow (`Show`, `For`-like) |
18
- | `VoidComponent<P>` | Forbidden | Leaf components (icons, inputs) |
19
-
20
- ```typescript
21
- const Card: ParentComponent<{ title: string }> = (props) => {
22
- return (
23
- <div class="card">
24
- <h2>{props.title}</h2>
25
- {props.children}
26
- </div>
27
- );
28
- };
29
-
30
- const Icon: VoidComponent<{ name: string }> = (props) => {
31
- return <svg class={`icon-${props.name}`} />;
32
- };
33
- ```
34
-
35
- ## Generic Components
36
-
37
- The `Component` types cannot be used for generic components. Use function declarations instead:
38
-
39
- ```typescript
40
- function List<T>(props: { items: T[]; render: (item: T) => JSX.Element }): JSX.Element {
41
- return <For each={props.items}>{props.render}</For>;
42
- }
43
-
44
- // Usage — T is inferred
45
- <List items={users()} render={(user) => <span>{user.name}</span>} />
46
- ```
47
-
48
- ## Refs
49
-
50
- Refs may be `undefined` before mount. Always account for this:
51
-
52
- ```typescript
53
- const MyComponent: VoidComponent = () => {
54
- let inputRef: HTMLInputElement | undefined;
55
-
56
- onMount(() => {
57
- inputRef?.focus(); // Safe access after mount
58
- });
59
-
60
- return <input ref={inputRef} />;
61
- };
62
- ```
63
-
64
- Alternatively, use the definite assignment assertion in JSX: `ref={inputRef!}`.
65
-
66
- ## Composition Over Inheritance
67
-
68
- Solid components are plain functions — compose them by passing components as props or using children:
69
-
70
- ```typescript
71
- const Layout: ParentComponent<{ sidebar: JSX.Element }> = (props) => {
72
- return (
73
- <div class="layout">
74
- <aside>{props.sidebar}</aside>
75
- <main>{props.children}</main>
76
- </div>
77
- );
78
- };
79
-
80
- <Layout sidebar={<Navigation />}>
81
- <PageContent />
82
- </Layout>
83
- ```
84
-
85
- ## Event Handling
86
-
87
- Inline event handlers get automatic type inference. For extracted handlers, use `JSX.EventHandler`:
88
-
89
- ```typescript
90
- const onInput: JSX.EventHandler<HTMLInputElement, InputEvent> = (event) => {
91
- // event.currentTarget is HTMLInputElement
92
- // event.target may be any element within
93
- console.log(event.currentTarget.value);
94
- };
95
- ```
96
-
97
- ### Custom Events
98
-
99
- Extend the JSX namespace:
100
-
101
- ```typescript
102
- declare module "solid-js" {
103
- namespace JSX {
104
- interface CustomEvents {
105
- customClick: CustomEvent<{ id: string }>;
106
- }
107
- }
108
- }
109
- ```
110
-
111
- ## Custom Directives
112
-
113
- Register with `use:` prefix. Declare via the JSX namespace:
114
-
115
- ```typescript
116
- declare module "solid-js" {
117
- namespace JSX {
118
- interface Directives {
119
- tooltip: string;
120
- }
121
- }
122
- }
123
-
124
- function tooltip(el: HTMLElement, accessor: () => string) {
125
- // Set up tooltip on el using accessor()
126
- onCleanup(() => { /* teardown */ });
127
- }
128
-
129
- // Usage
130
- <div use:tooltip={"Hello!"} />
131
- ```
@@ -1,131 +0,0 @@
1
- # Context & Global State
2
-
3
- > Sources: [Context](https://docs.solidjs.com/concepts/context), [Complex State Management](https://docs.solidjs.com/guides/complex-state-management) — SolidJS Docs
4
-
5
- ## When to Use Context
6
-
7
- Context solves **prop drilling** — passing state through many component layers that don't use it themselves. Use it for:
8
-
9
- - Theme / appearance settings
10
- - Authentication state
11
- - Feature flags
12
- - Any state needed by many descendants
13
-
14
- **When NOT to use context:**
15
- - If only a few components need the data, pass props directly
16
- - If you can restructure the component tree to avoid drilling
17
- - For truly global singletons, a module-level signal may be simpler
18
-
19
- ## Basic Context Pattern
20
-
21
- ```typescript
22
- import { createContext, useContext } from "solid-js";
23
- import { createStore } from "solid-js/store";
24
-
25
- // 1. Create context
26
- const CounterContext = createContext<{
27
- count: number;
28
- increment: () => void;
29
- }>();
30
-
31
- // 2. Create provider component
32
- function CounterProvider(props: ParentProps) {
33
- const [state, setState] = createStore({ count: 0 });
34
- const value = {
35
- get count() { return state.count; },
36
- increment() { setState("count", c => c + 1); },
37
- };
38
-
39
- return (
40
- <CounterContext.Provider value={value}>
41
- {props.children}
42
- </CounterContext.Provider>
43
- );
44
- }
45
-
46
- // 3. Consume with useContext
47
- function Counter() {
48
- const ctx = useContext(CounterContext);
49
- return <button onClick={ctx.increment}>{ctx.count}</button>;
50
- }
51
- ```
52
-
53
- ## Safe useContext with Error Throwing
54
-
55
- `useContext` returns `undefined` when no provider exists above. Create a custom hook that throws a helpful error:
56
-
57
- ```typescript
58
- function useCounter() {
59
- const ctx = useContext(CounterContext);
60
- if (!ctx) {
61
- throw new Error("useCounter must be used within a CounterProvider");
62
- }
63
- return ctx;
64
- }
65
- ```
66
-
67
- This also **narrows the TypeScript type** — no more `| undefined`.
68
-
69
- ## Context + Store Pattern (Recommended)
70
-
71
- Combine `createStore` with context for scalable state. Stores give you fine-grained reactivity; context distributes it without prop drilling.
72
-
73
- ```typescript
74
- function createTaskStore() {
75
- const [state, setState] = createStore({
76
- tasks: [] as Task[],
77
- filter: "all" as "all" | "active" | "completed",
78
- });
79
-
80
- return {
81
- get tasks() { return state.tasks; },
82
- get filter() { return state.filter; },
83
- addTask(text: string) {
84
- setState("tasks", state.tasks.length, {
85
- id: crypto.randomUUID(),
86
- text,
87
- completed: false,
88
- });
89
- },
90
- toggleTask(id: string) {
91
- setState("tasks", t => t.id === id, "completed", c => !c);
92
- },
93
- setFilter(filter: "all" | "active" | "completed") {
94
- setState("filter", filter);
95
- },
96
- };
97
- }
98
-
99
- const TaskContext = createContext<ReturnType<typeof createTaskStore>>();
100
-
101
- function TaskProvider(props: ParentProps) {
102
- return (
103
- <TaskContext.Provider value={createTaskStore()}>
104
- {props.children}
105
- </TaskContext.Provider>
106
- );
107
- }
108
- ```
109
-
110
- **Why this works well in Solid:** Updating a signal at the top of the tree does NOT cause children to re-render. Only the specific reactive expressions that read the changed property update. There is no performance penalty for high-level state.
111
-
112
- ## HMR Consideration
113
-
114
- To avoid recreating context during Hot Module Replacement, define `createContext` in its **own module** (separate file), not inline in a component file.
115
-
116
- ## Module-Level Signals vs Context
117
-
118
- For truly global, app-wide singletons (e.g., a theme toggle), a module-level signal is simpler:
119
-
120
- ```typescript
121
- // theme.ts
122
- export const [theme, setTheme] = createSignal<"light" | "dark">("light");
123
-
124
- // Any component can import directly
125
- import { theme, setTheme } from "./theme";
126
- ```
127
-
128
- Use context instead when:
129
- - Different subtrees need different values (e.g., per-user state)
130
- - You need testability (mock providers in tests)
131
- - The state has complex dependencies
@@ -1,124 +0,0 @@
1
- # Control Flow
2
-
3
- > Sources: [Show](https://docs.solidjs.com/reference/components/show), [For](https://docs.solidjs.com/reference/components/for), [SolidJS Tutorials](https://www.solidjs.com/tutorial) — SolidJS Docs
4
-
5
- ## Why Control Flow Components?
6
-
7
- In Solid, **avoid JavaScript-native conditionals and `.map()` in JSX**. Solid's control flow components provide explicit boundaries that the compiler can optimize — they track dependencies and minimize DOM operations.
8
-
9
- ## `<Show>` — Conditional Rendering
10
-
11
- Renders children when `when` is truthy. Optionally provides a `fallback`.
12
-
13
- ```typescript
14
- <Show when={user()} fallback={<LoginPrompt />}>
15
- <Dashboard />
16
- </Show>
17
- ```
18
-
19
- ### Callback Form for Type Narrowing
20
-
21
- The callback form provides a non-null accessor — essential for TypeScript:
22
-
23
- ```typescript
24
- <Show when={user()}>
25
- {(nonNullUser) => <span>{nonNullUser().name}</span>}
26
- </Show>
27
- ```
28
-
29
- TypeScript cannot narrow accessor types through control flow, so the callback form is the idiomatic way to access narrowed values.
30
-
31
- ## `<For>` — List Rendering
32
-
33
- Renders a list, keyed by **reference** (not index). Only re-renders items that actually change.
34
-
35
- ```typescript
36
- <For each={items()}>
37
- {(item, index) => (
38
- <li>{index()}: {item.name}</li>
39
- )}
40
- </For>
41
- ```
42
-
43
- - `item` is the value (not reactive for primitives)
44
- - `index()` is a signal — call it as a function
45
- - Items are tracked by reference — avoid recreating objects
46
-
47
- ### `<Index>` — Keyed by Index
48
-
49
- For primitive arrays where values change but positions are stable:
50
-
51
- ```typescript
52
- <Index each={names()}>
53
- {(name, i) => <li>{i}: {name()}</li>}
54
- </Index>
55
- ```
56
-
57
- - `name` is a signal (reactive)
58
- - `i` is a plain number (not reactive)
59
-
60
- **Rule of thumb:** Use `<For>` for arrays of objects, `<Index>` for arrays of primitives.
61
-
62
- ## `<Switch>` / `<Match>` — Multi-Branch Conditional
63
-
64
- ```typescript
65
- <Switch fallback={<p>Unknown state</p>}>
66
- <Match when={state() === "loading"}>
67
- <Spinner />
68
- </Match>
69
- <Match when={state() === "error"}>
70
- <ErrorDisplay />
71
- </Match>
72
- <Match when={state() === "ready"}>
73
- <Content />
74
- </Match>
75
- </Switch>
76
- ```
77
-
78
- First matching `<Match>` wins. Use `fallback` on `<Switch>` for the default case.
79
-
80
- ## `<ErrorBoundary>` — Error Catching
81
-
82
- Catches errors thrown in child components and renders a fallback:
83
-
84
- ```typescript
85
- <ErrorBoundary fallback={(err, reset) => (
86
- <div>
87
- <p>Error: {err.message}</p>
88
- <button onClick={reset}>Retry</button>
89
- </div>
90
- )}>
91
- <RiskyComponent />
92
- </ErrorBoundary>
93
- ```
94
-
95
- The `reset` function re-renders the children, giving the component a fresh chance.
96
-
97
- ## `<Suspense>` — Async Loading States
98
-
99
- Displays a fallback while waiting for async resources to resolve:
100
-
101
- ```typescript
102
- <Suspense fallback={<Skeleton />}>
103
- <UserProfile /> {/* Uses createResource internally */}
104
- </Suspense>
105
- ```
106
-
107
- Suspense detects any `createResource` read within its boundary and holds rendering until all resolve. Nested Suspense boundaries allow granular loading states.
108
-
109
- ## `<Dynamic>` — Dynamic Component
110
-
111
- Render a component determined at runtime:
112
-
113
- ```typescript
114
- <Dynamic component={isAdmin() ? AdminPanel : UserPanel} user={user()} />
115
- ```
116
-
117
- ## Don't Use
118
-
119
- | Instead of | Use |
120
- |---|---|
121
- | `{condition && <Component />}` | `<Show when={condition}>` |
122
- | `{condition ? <A /> : <B />}` | `<Show when={condition} fallback={<B />}>` |
123
- | `{items.map(i => ...)}` | `<For each={items()}>` |
124
- | Nested ternaries | `<Switch>` / `<Match>` |
@@ -1,205 +0,0 @@
1
- # Data Fetching
2
-
3
- > Sources: [Fetching Data](https://docs.solidjs.com/guides/fetching-data), [createResource](https://docs.solidjs.com/reference/basic-reactivity/create-resource) — SolidJS Docs
4
-
5
- ## createResource
6
-
7
- The primary tool for async data in SolidJS. Wraps an async operation into a reactive signal with built-in loading, error, and state tracking.
8
-
9
- ```typescript
10
- const [user, { mutate, refetch }] = createResource(userId, async (id) => {
11
- const res = await fetch(`/api/users/${id}`);
12
- return res.json();
13
- });
14
- ```
15
-
16
- - `userId` is the **source signal** — when it changes, the fetcher re-runs
17
- - The fetcher receives the source value as its first argument
18
- - Returns a resource signal with reactive properties
19
-
20
- ### Resource Properties
21
-
22
- ```typescript
23
- user() // The resolved data (or undefined)
24
- user.loading // Boolean — is a fetch in progress?
25
- user.error // Error object if the fetch failed
26
- user.state // "unresolved" | "pending" | "ready" | "refreshing" | "errored"
27
- user.latest // Most recent successful data (persists during refetch)
28
- ```
29
-
30
- ## Handling States in JSX
31
-
32
- ### With Control Flow
33
-
34
- ```typescript
35
- <Show when={!user.loading} fallback={<Spinner />}>
36
- <Show when={!user.error} fallback={<Error message={user.error.message} />}>
37
- <UserCard user={user()} />
38
- </Show>
39
- </Show>
40
- ```
41
-
42
- ### With Suspense + ErrorBoundary (recommended)
43
-
44
- ```typescript
45
- <ErrorBoundary fallback={(err, reset) => (
46
- <div>
47
- <p>Failed: {err.message}</p>
48
- <button onClick={reset}>Retry</button>
49
- </div>
50
- )}>
51
- <Suspense fallback={<Skeleton />}>
52
- <UserCard /> {/* reads createResource internally */}
53
- </Suspense>
54
- </ErrorBoundary>
55
- ```
56
-
57
- Suspense detects resource reads within its boundary and shows the fallback until all resolve. This is the idiomatic pattern.
58
-
59
- ## Optimistic Updates with `mutate`
60
-
61
- Update the UI immediately, then let the server catch up:
62
-
63
- ```typescript
64
- const [tasks, { mutate, refetch }] = createResource(fetchTasks);
65
-
66
- function addTask(text: string) {
67
- // Optimistic: update UI immediately
68
- mutate(prev => [...(prev ?? []), { id: "temp", text, completed: false }]);
69
-
70
- // Then sync with server
71
- postTask(text).then(() => refetch());
72
- }
73
- ```
74
-
75
- `mutate` overwrites the resource value without calling the fetcher.
76
-
77
- ## Refetching
78
-
79
- Force a refetch independent of the source signal:
80
-
81
- ```typescript
82
- const [prices, { refetch }] = createResource(fetchPrices);
83
-
84
- // Poll every 10 seconds
85
- const interval = setInterval(refetch, 10_000);
86
- onCleanup(() => clearInterval(interval));
87
- ```
88
-
89
- ## createAsync (SolidStart / Solid Router)
90
-
91
- For SolidStart apps, `createAsync` is the recommended async primitive. It's a thin wrapper over `createResource` designed for router-integrated data loading:
92
-
93
- ```typescript
94
- import { createAsync } from "@solidjs/router";
95
-
96
- const user = createAsync(() => getUser());
97
- ```
98
-
99
- `createAsync` is intended to become the standard async primitive in Solid 2.0.
100
-
101
- ## Runtime Validation with Zod / Valibot
102
-
103
- Data entering your app from APIs, forms, or `localStorage` should be validated at runtime — TypeScript types don't exist at runtime. See [TypeScript Runtime Validation](../typescript/runtime-validation.md) for when to validate.
104
-
105
- ### Validating API Responses in `createResource`
106
-
107
- Parse and type-narrow data inside the fetcher so the resource signal is guaranteed to hold valid data:
108
-
109
- ```typescript
110
- import { z } from "zod";
111
-
112
- const UserSchema = z.object({
113
- id: z.string(),
114
- name: z.string(),
115
- email: z.string().email(),
116
- });
117
-
118
- type User = z.infer<typeof UserSchema>;
119
-
120
- const [user] = createResource(userId, async (id): Promise<User> => {
121
- const res = await fetch(`/api/users/${id}`);
122
- const json = await res.json();
123
- return UserSchema.parse(json); // Throws on invalid shape
124
- });
125
- ```
126
-
127
- `z.infer<typeof Schema>` keeps your TypeScript types and runtime validation in sync — no duplication.
128
-
129
- ### A Reusable Typed Fetch Helper
130
-
131
- ```typescript
132
- const fetchTyped = async <T extends z.ZodSchema>(
133
- url: string,
134
- schema: T,
135
- ): Promise<z.infer<T>> => {
136
- const res = await fetch(url);
137
- return schema.parse(await res.json());
138
- };
139
-
140
- // Usage with createResource
141
- const [user] = createResource(userId, (id) =>
142
- fetchTyped(`/api/users/${id}`, UserSchema)
143
- );
144
- ```
145
-
146
- ### Form Validation
147
-
148
- [@modular-forms/solid](https://modularforms.dev/solid/guides/validate-your-fields) has built-in Zod integration via the `zodForm` adapter:
149
-
150
- ```typescript
151
- import { createForm } from "@modular-forms/solid";
152
- import { zodForm } from "@modular-forms/solid";
153
-
154
- const LoginSchema = z.object({
155
- email: z.string().min(1, "Required").email("Invalid email"),
156
- password: z.string().min(8, "Min 8 characters"),
157
- });
158
-
159
- type LoginForm = z.infer<typeof LoginSchema>;
160
-
161
- const [form, { Form, Field }] = createForm<LoginForm>({
162
- validate: zodForm(LoginSchema),
163
- });
164
- ```
165
-
166
- ### Valibot as a Lighter Alternative
167
-
168
- [Valibot](https://valibot.dev/) provides the same validation patterns with a tree-shakeable design — ~1.4kb vs Zod's ~13kb for a typical form schema. Ryan Carniato (SolidJS creator) has endorsed it, and `@modular-forms/solid` supports it natively via `valiForm`.
169
-
170
- ```typescript
171
- import * as v from "valibot";
172
-
173
- const UserSchema = v.object({
174
- id: v.string(),
175
- name: v.pipe(v.string(), v.nonEmpty()),
176
- email: v.pipe(v.string(), v.email()),
177
- });
178
-
179
- type User = v.InferInput<typeof UserSchema>;
180
- ```
181
-
182
- **Choose based on your constraints:**
183
-
184
- | Criteria | Zod | Valibot |
185
- | --------------- | --------- | ---------- |
186
- | Bundle size | ~13kb | ~1.4kb |
187
- | Tree-shakeable | No | Yes |
188
- | Ecosystem | Larger | Growing |
189
- | API style | Chaining | Functional |
190
- | Runtime speed | Baseline | ~2x faster |
191
-
192
- ## Don't Fetch in Effects
193
-
194
- ```typescript
195
- // WRONG — no loading state, no error handling, race conditions
196
- createEffect(async () => {
197
- const data = await fetch(`/api/${id()}`);
198
- setResult(await data.json());
199
- });
200
-
201
- // RIGHT — built-in state management, cancellation, reactivity
202
- const [result] = createResource(id, fetchData);
203
- ```
204
-
205
- Effects run after render, causing a flash of empty state. Resources integrate with Suspense and provide proper loading/error states.
@@ -1,113 +0,0 @@
1
- # Effects & Lifecycle
2
-
3
- > Sources: [Effects](https://docs.solidjs.com/concepts/effects), [onMount](https://docs.solidjs.com/reference/lifecycle/on-mount), [onCleanup](https://docs.solidjs.com/reference/lifecycle/on-cleanup) — SolidJS Docs
4
-
5
- ## createEffect
6
-
7
- Runs a side effect whenever its tracked dependencies change. Dependencies are automatically detected.
8
-
9
- ```typescript
10
- createEffect(() => {
11
- document.title = `${count()} items`;
12
- });
13
- ```
14
-
15
- ### When to Use Effects
16
-
17
- Effects are for **interacting with the outside world** — the DOM, third-party libraries, logging, WebSockets.
18
-
19
- **Use effects for:**
20
- - DOM manipulation not covered by JSX
21
- - Third-party library integration
22
- - WebSocket connections
23
- - Logging / analytics
24
-
25
- **Don't use effects for:**
26
- - Derived values → use `createMemo` or inline derivation
27
- - State synchronization → derive instead of sync
28
- - Data fetching → use `createResource`
29
-
30
- ### The #1 Anti-Pattern: Syncing State
31
-
32
- ```typescript
33
- // WRONG — creates glitchy intermediate states
34
- createEffect(() => {
35
- setDoubled(count() * 2);
36
- });
37
-
38
- // RIGHT — derive the value
39
- const doubled = createMemo(() => count() * 2);
40
- ```
41
-
42
- When you use effects to sync state, the reactive graph must choose an execution order, which can produce inconsistent intermediate states that flash in the UI.
43
-
44
- ## `on` — Explicit Dependencies
45
-
46
- When you need to control which signals trigger an effect:
47
-
48
- ```typescript
49
- import { on } from "solid-js";
50
-
51
- createEffect(on(userId, (id) => {
52
- // Only runs when userId changes, not when other signals read inside change
53
- fetchUserData(id);
54
- }));
55
- ```
56
-
57
- `on` also provides the previous value:
58
-
59
- ```typescript
60
- createEffect(on(count, (current, previous) => {
61
- console.log(`Changed from ${previous} to ${current}`);
62
- }));
63
- ```
64
-
65
- ## onMount
66
-
67
- Runs once after the component's initial render, when DOM elements are available. Non-reactive — it doesn't track signals.
68
-
69
- ```typescript
70
- onMount(() => {
71
- // DOM is ready, refs are populated
72
- inputRef?.focus();
73
-
74
- // Good for one-time setup
75
- const chart = new Chart(canvasRef);
76
- });
77
- ```
78
-
79
- **Use for:** ref access, one-time DOM setup, measurements, API calls that should only happen once.
80
-
81
- ## onCleanup
82
-
83
- Runs when the enclosing reactive scope is disposed or re-executed. Essential for preventing memory leaks.
84
-
85
- ```typescript
86
- // In a component — runs when component unmounts
87
- onCleanup(() => {
88
- chart.destroy();
89
- });
90
-
91
- // In an effect — runs before each re-execution and on dispose
92
- createEffect(() => {
93
- const id = setInterval(() => tick(), props.interval);
94
- onCleanup(() => clearInterval(id));
95
- });
96
- ```
97
-
98
- **Always clean up:**
99
- - Event listeners
100
- - Timers (`setInterval`, `setTimeout`)
101
- - WebSocket connections
102
- - Third-party library instances
103
- - Subscriptions
104
-
105
- ## Lifecycle Order
106
-
107
- 1. Component function runs (synchronous)
108
- 2. Reactive expressions are set up (signals, memos, effects registered)
109
- 3. DOM is created and mounted
110
- 4. `onMount` callbacks fire
111
- 5. Effects run (in dependency order)
112
- 6. On signal change: effects re-run, `onCleanup` fires before each re-run
113
- 7. On unmount: all `onCleanup` callbacks fire