@barqjs/compiler 0.2.0-next.0 → 0.2.0-next.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 +21 -5
- package/docs/BARQ001.md +3 -3
- package/docs/BARQ002.md +2 -2
- package/docs/BARQ003.md +2 -2
- package/docs/BARQ005.md +16 -83
- package/docs/BARQ015.md +1 -1
- package/docs/BARQ018.md +6 -6
- package/docs/BARQ025.md +4 -4
- package/docs/BARQ027.md +1 -1
- package/docs/BARQ028.md +2 -2
- package/docs/BARQ030.md +65 -0
- package/docs/BARQ031.md +61 -0
- package/docs/BARQ032.md +68 -0
- package/docs/BARQ033.md +81 -0
- package/docs/BARQ034.md +55 -0
- package/docs/README.md +21 -13
- package/index.d.ts +42 -1
- package/index.js +1 -0
- package/package.json +19 -18
- package/skills/compiler-diagnostics/SKILL.md +890 -0
|
@@ -0,0 +1,890 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: compiler-diagnostics
|
|
3
|
+
description: Map a barq compiler diagnostic code (BARQ001 to BARQ034) to its repair. Load when a build, the Vite dev overlay, the terminal or a transform result reports BARQ0NN at a file, line and column. Runtime [CODE] findings are in the diagnostics skill of @barqjs/core.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Repairing barq code from a compiler diagnostic code
|
|
7
|
+
|
|
8
|
+
The barq compiler reports each finding with a stable code, a level (`note`,
|
|
9
|
+
`warning` or `error`) and a position. Find the code's `### BARQ0NN` section
|
|
10
|
+
below: it says what the compiler saw, the repair, and the default level. An
|
|
11
|
+
`error` fails the build. A `warning` or `note` builds, and the code it points
|
|
12
|
+
at is still wrong or slower than it could be, so repair it.
|
|
13
|
+
|
|
14
|
+
Runtime codes such as `[REACTIVE_WRITE_IN_OWNED_SCOPE]` are a different family:
|
|
15
|
+
see `node_modules/@barqjs/core/skills/diagnostics/SKILL.md`.
|
|
16
|
+
|
|
17
|
+
## How a code arrives
|
|
18
|
+
|
|
19
|
+
- **Terminal and build log**: one line per finding,
|
|
20
|
+
`file:line:col: BARQ0NN level: message`.
|
|
21
|
+
- **Vite dev overlay**: a pill in the corner of the page that lists compiler
|
|
22
|
+
findings with the source they are about. The `overlay` option of `barq()`
|
|
23
|
+
chooses what opens it (`"error"` by default).
|
|
24
|
+
- **`barq check`** from `@barqjs/cli`: every file of the project with no build.
|
|
25
|
+
`npx barq check --json` prints `{ summary, findings }`, each finding shaped as
|
|
26
|
+
below with `skill`, the section of this file for its code. `npx barq check
|
|
27
|
+
--fix` applies the repairs that are one spelling (BARQ001, BARQ002, BARQ003,
|
|
28
|
+
BARQ022, BARQ023 and the renames of BARQ024) and reports what is left.
|
|
29
|
+
- **The compiler's `transform` result**: the `diagnostics` array, one object
|
|
30
|
+
per finding, which serialises to JSON as below. `line` and `column` are
|
|
31
|
+
1-based. `docs` is the code's page. `fix`, when present, is a list of
|
|
32
|
+
`{ pos, end, text }` edits over the source that repair the finding.
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"code": "BARQ001",
|
|
37
|
+
"severity": "warning",
|
|
38
|
+
"message": "`count` is an accessor, and here the function itself is used as the value. ...",
|
|
39
|
+
"file": "src/App.tsx",
|
|
40
|
+
"line": 3,
|
|
41
|
+
"column": 42,
|
|
42
|
+
"endLine": 3,
|
|
43
|
+
"endColumn": 47,
|
|
44
|
+
"docs": "https://github.com/salamaashoush/barq/blob/main/packages/compiler/docs/BARQ001.md"
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A finding with no `code` is a syntax error from the parser: fix the syntax at
|
|
49
|
+
that position.
|
|
50
|
+
|
|
51
|
+
Each code also has a page with the full message and more examples at
|
|
52
|
+
`node_modules/@barqjs/compiler/docs/BARQ0NN.md`.
|
|
53
|
+
|
|
54
|
+
## When each code is reported
|
|
55
|
+
|
|
56
|
+
- `BARQ001`, `BARQ002`, `BARQ003`, `BARQ011`, `BARQ018` to `BARQ021`: when the
|
|
57
|
+
`diagnostics` option is on. It is on in development builds, and
|
|
58
|
+
`barq({ compiler: { diagnostics: true } })` runs them in a production build.
|
|
59
|
+
- `BARQ004`, `BARQ010`: development builds only.
|
|
60
|
+
- `BARQ012` to `BARQ017`, `BARQ022` to `BARQ034`: every build.
|
|
61
|
+
- `BARQ008`, `BARQ009`: every build, about suppression comments.
|
|
62
|
+
|
|
63
|
+
`BARQ005`, `BARQ006` and `BARQ007` are retired and never reported. A
|
|
64
|
+
suppression comment that names one of them is reported as `BARQ009`: delete the
|
|
65
|
+
comment.
|
|
66
|
+
|
|
67
|
+
## Setting a level
|
|
68
|
+
|
|
69
|
+
For the whole project, in `vite.config.ts`:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import barq from "@barqjs/vite";
|
|
73
|
+
import { defineConfig } from "vite";
|
|
74
|
+
|
|
75
|
+
export default defineConfig({
|
|
76
|
+
plugins: [
|
|
77
|
+
barq({
|
|
78
|
+
compiler: {
|
|
79
|
+
checks: { BARQ004: "suppress", BARQ001: "error" },
|
|
80
|
+
defaultCategory: "warning",
|
|
81
|
+
},
|
|
82
|
+
}),
|
|
83
|
+
],
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
A level is `suppress`, `note`, `warning` or `error`. An entry in `checks` wins
|
|
88
|
+
over `strictCss` (which makes `BARQ014` to `BARQ017` errors), which wins over
|
|
89
|
+
`defaultCategory` (every code), which wins over the code's own default. When
|
|
90
|
+
calling the compiler's `transform` directly, `checks` is a list of pairs:
|
|
91
|
+
`checks: [["BARQ004", "suppress"]]`.
|
|
92
|
+
|
|
93
|
+
For one line, write a comment directly above the reported line, with the code
|
|
94
|
+
and a reason of at least 10 characters in parentheses:
|
|
95
|
+
|
|
96
|
+
```tsx
|
|
97
|
+
// barq-ignore-next-line BARQ001 (the debug panel shows the source text)
|
|
98
|
+
const label = `${count}`;
|
|
99
|
+
|
|
100
|
+
<div>
|
|
101
|
+
{/* barq-ignore-next-line BARQ001 (the debug panel shows the source text) */}
|
|
102
|
+
<pre>{`${count}`}</pre>
|
|
103
|
+
</div>;
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Between JSX children the comment must be the `{/* ... */}` form. Repair the
|
|
107
|
+
code first. Suppress only a line that is correct as written, and say why in the
|
|
108
|
+
reason.
|
|
109
|
+
|
|
110
|
+
## Accessors used as values
|
|
111
|
+
|
|
112
|
+
A signal's read half, a memo and a keyed `<For>` row are accessors: functions
|
|
113
|
+
that return the value. These three codes are about an accessor used without its
|
|
114
|
+
call. A prop is not an accessor: `props.count` and a destructured `count` are
|
|
115
|
+
values, and are never reported here.
|
|
116
|
+
|
|
117
|
+
### BARQ001
|
|
118
|
+
|
|
119
|
+
Default level: warning.
|
|
120
|
+
|
|
121
|
+
An accessor is used as a value without being called, in a string or in
|
|
122
|
+
arithmetic. It prints its own source text, or gives `NaN`. Call it.
|
|
123
|
+
|
|
124
|
+
```tsx
|
|
125
|
+
// before
|
|
126
|
+
<p>{`total: ${count}`}</p>
|
|
127
|
+
|
|
128
|
+
// after
|
|
129
|
+
<p>{`total: ${count()}`}</p>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`<p>{count}</p>` and `<div id={count}>` are correct and are not reported.
|
|
133
|
+
|
|
134
|
+
### BARQ002
|
|
135
|
+
|
|
136
|
+
Default level: warning.
|
|
137
|
+
|
|
138
|
+
An accessor is used as a condition (`if`, `? :`, `&&`, `!`, a loop test). A
|
|
139
|
+
function is always truthy, so one branch never runs. Call it.
|
|
140
|
+
|
|
141
|
+
```tsx
|
|
142
|
+
// before
|
|
143
|
+
<p>{loading ? "Loading" : "Ready"}</p>
|
|
144
|
+
|
|
145
|
+
// after
|
|
146
|
+
<p>{loading() ? "Loading" : "Ready"}</p>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### BARQ003
|
|
150
|
+
|
|
151
|
+
Default level: warning.
|
|
152
|
+
|
|
153
|
+
A property is read from the accessor instead of from its value, so the result
|
|
154
|
+
is `undefined` (or `0` for `.length`, which is the function's parameter count).
|
|
155
|
+
Call it first. An accessor has no `.value`, `.set` or `.peek`.
|
|
156
|
+
|
|
157
|
+
```tsx
|
|
158
|
+
// before
|
|
159
|
+
<p>{user.email}</p>
|
|
160
|
+
<p>{items.length} items</p>
|
|
161
|
+
|
|
162
|
+
// after
|
|
163
|
+
<p>{user().email}</p>
|
|
164
|
+
<p>{items().length} items</p>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Lists
|
|
168
|
+
|
|
169
|
+
### BARQ004
|
|
170
|
+
|
|
171
|
+
Default level: note.
|
|
172
|
+
|
|
173
|
+
A `<For>` row reads a field of its item once, while the row is built, and the
|
|
174
|
+
items may be store objects. A store changes a field in place, the row is kept,
|
|
175
|
+
and it goes on showing the old value. The reads that are reported: a
|
|
176
|
+
destructured row parameter, a read in statements above the row's JSX, a read
|
|
177
|
+
that picks which JSX to return.
|
|
178
|
+
|
|
179
|
+
Read the field in the row's JSX, or key the list and call the row:
|
|
180
|
+
|
|
181
|
+
```tsx
|
|
182
|
+
// before
|
|
183
|
+
<For each={state.rows}>{({ name }) => <li>{name}</li>}</For>
|
|
184
|
+
|
|
185
|
+
// after
|
|
186
|
+
<For each={state.rows}>{(row) => <li>{row.name}</li>}</For>
|
|
187
|
+
|
|
188
|
+
// or
|
|
189
|
+
<For each={state.rows} keyed={(row) => row.id}>
|
|
190
|
+
{(row) => <li>{row().name}</li>}
|
|
191
|
+
</For>
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### BARQ011
|
|
195
|
+
|
|
196
|
+
Default level: note.
|
|
197
|
+
|
|
198
|
+
`keyed={false}` on a `<For>` whose row holds an element with state of its own
|
|
199
|
+
(`input`, `textarea`, `select`, `video`, `audio`, `details`, `canvas`,
|
|
200
|
+
`dialog`, a custom element). Rows are reused by position, so typed text, the
|
|
201
|
+
caret or playback stays in place when the list reorders and ends up on another
|
|
202
|
+
item. Remove `keyed={false}`, or key by a stable field:
|
|
203
|
+
|
|
204
|
+
```tsx
|
|
205
|
+
// before
|
|
206
|
+
<For each={todos} keyed={false}>
|
|
207
|
+
{(todo) => <input value={todo().text} />}
|
|
208
|
+
</For>
|
|
209
|
+
|
|
210
|
+
// after
|
|
211
|
+
<For each={todos} keyed={(todo) => todo.id}>
|
|
212
|
+
{(todo) => <input value={todo().text} />}
|
|
213
|
+
</For>
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Suppression comments
|
|
217
|
+
|
|
218
|
+
### BARQ008
|
|
219
|
+
|
|
220
|
+
Default level: warning. Stays a warning under `defaultCategory: "error"`.
|
|
221
|
+
|
|
222
|
+
A `barq-ignore-next-line` comment names a code that nothing on the next line
|
|
223
|
+
reports. Delete the comment, or move it directly above the line the diagnostic
|
|
224
|
+
points at (it covers one line, not one statement). Between JSX children write
|
|
225
|
+
it as `{/* barq-ignore-next-line BARQ001 (reason) */}`.
|
|
226
|
+
|
|
227
|
+
### BARQ009
|
|
228
|
+
|
|
229
|
+
Default level: warning. Stays a warning under `defaultCategory: "error"`.
|
|
230
|
+
|
|
231
|
+
A `barq-ignore-next-line` comment is malformed and silences nothing. The
|
|
232
|
+
message says what is missing: the code, a known code, a reason of at least 10
|
|
233
|
+
characters, or the closing parenthesis. Write the full form:
|
|
234
|
+
|
|
235
|
+
```tsx
|
|
236
|
+
// before
|
|
237
|
+
// barq-ignore-next-line BARQ001
|
|
238
|
+
|
|
239
|
+
// after
|
|
240
|
+
// barq-ignore-next-line BARQ001 (the debug panel shows the source text)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
A comment naming the retired `BARQ005`, `BARQ006` or `BARQ007` is reported
|
|
244
|
+
here too: delete it.
|
|
245
|
+
|
|
246
|
+
## Components and props
|
|
247
|
+
|
|
248
|
+
### BARQ010
|
|
249
|
+
|
|
250
|
+
Default level: warning.
|
|
251
|
+
|
|
252
|
+
JSX is passed to a prop that the component (declared in the same file) reads as
|
|
253
|
+
a value: in an attribute, an event handler, a `ref`, or the `each`, `when` or
|
|
254
|
+
`mount` of a flow component. JSX passed as a prop can only be rendered as a
|
|
255
|
+
child, and reading it as a value throws `ScopeMissingError` at run time.
|
|
256
|
+
|
|
257
|
+
Pass a value, or change the component to render the prop as a child:
|
|
258
|
+
|
|
259
|
+
```tsx
|
|
260
|
+
// before
|
|
261
|
+
function Card(props) {
|
|
262
|
+
return <section title={props.heading}>{props.children}</section>;
|
|
263
|
+
}
|
|
264
|
+
<Card heading={<b>Today</b>}>Hello</Card>;
|
|
265
|
+
|
|
266
|
+
// after: pass a value
|
|
267
|
+
<Card heading="Today">Hello</Card>;
|
|
268
|
+
|
|
269
|
+
// or: render the prop as a child
|
|
270
|
+
function Card(props) {
|
|
271
|
+
return (
|
|
272
|
+
<section>
|
|
273
|
+
<h2>{props.heading}</h2>
|
|
274
|
+
{props.children}
|
|
275
|
+
</section>
|
|
276
|
+
);
|
|
277
|
+
}
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### BARQ018
|
|
281
|
+
|
|
282
|
+
Default level: warning.
|
|
283
|
+
|
|
284
|
+
A component chooses what to return (`if`, `switch`, an early `return`, a
|
|
285
|
+
ternary as the whole return value) from a signal, memo, store or changing prop
|
|
286
|
+
that it reads while its body runs. The body runs once, so the page keeps what
|
|
287
|
+
it showed first. Make the choice inside the returned JSX:
|
|
288
|
+
|
|
289
|
+
```tsx
|
|
290
|
+
// before
|
|
291
|
+
function Greeting() {
|
|
292
|
+
if (!user()) return <button onClick={() => setUser("salama")}>Sign in</button>;
|
|
293
|
+
return <p>Hello, {user()}</p>;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
// after
|
|
297
|
+
function Greeting() {
|
|
298
|
+
return (
|
|
299
|
+
<Show when={user()} fallback={<button onClick={() => setUser("salama")}>Sign in</button>}>
|
|
300
|
+
<p>Hello, {user()}</p>
|
|
301
|
+
</Show>
|
|
302
|
+
);
|
|
303
|
+
}
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
For a prop, wrap the choice in a fragment so it is a JSX expression:
|
|
307
|
+
|
|
308
|
+
```tsx
|
|
309
|
+
// before
|
|
310
|
+
function Status(props) {
|
|
311
|
+
return props.online ? <b>online</b> : <i>offline</i>;
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
// after
|
|
315
|
+
function Status(props) {
|
|
316
|
+
return <>{props.online ? <b>online</b> : <i>offline</i>}</>;
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
A value that is read once on purpose says so: `if (!untrack(user)) ...`.
|
|
321
|
+
|
|
322
|
+
### BARQ019
|
|
323
|
+
|
|
324
|
+
Default level: warning.
|
|
325
|
+
|
|
326
|
+
A setter (`createSignal`, `createStore`, `createOptimistic`,
|
|
327
|
+
`createOptimisticStore`) or an `action` is called while a component body, a
|
|
328
|
+
JSX expression, a memo or the first function of an effect runs. Development
|
|
329
|
+
builds throw `REACTIVE_WRITE_IN_OWNED_SCOPE` at that call. Derive the value, or
|
|
330
|
+
write from an event handler, `onSettled`, or the second function of
|
|
331
|
+
`createEffect`.
|
|
332
|
+
|
|
333
|
+
```tsx
|
|
334
|
+
// before
|
|
335
|
+
function Counter() {
|
|
336
|
+
const [count, setCount] = createSignal(0);
|
|
337
|
+
setCount(1);
|
|
338
|
+
return <button onClick={() => setCount(count() + 1)}>{count()}</button>;
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
// after
|
|
342
|
+
function Counter() {
|
|
343
|
+
const [count, setCount] = createSignal(1);
|
|
344
|
+
return <button onClick={() => setCount(count() + 1)}>{count()}</button>;
|
|
345
|
+
}
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
```tsx
|
|
349
|
+
// before
|
|
350
|
+
const sync = createMemo(() => setTotal(price() * 2));
|
|
351
|
+
|
|
352
|
+
// after
|
|
353
|
+
const total = createMemo(() => price() * 2);
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
```tsx
|
|
357
|
+
// a write that follows a change
|
|
358
|
+
createEffect(
|
|
359
|
+
() => price(),
|
|
360
|
+
(value) => {
|
|
361
|
+
setHistory((list) => [...list, value]);
|
|
362
|
+
},
|
|
363
|
+
);
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
### BARQ020
|
|
367
|
+
|
|
368
|
+
Default level: warning.
|
|
369
|
+
|
|
370
|
+
A store is destructured in a component body, so each name holds the value its
|
|
371
|
+
property had when the body ran and never updates. Read the property where it
|
|
372
|
+
is used.
|
|
373
|
+
|
|
374
|
+
```tsx
|
|
375
|
+
// before
|
|
376
|
+
function Badge() {
|
|
377
|
+
const { count, owner } = cart;
|
|
378
|
+
return (
|
|
379
|
+
<p>
|
|
380
|
+
{owner}: {count}
|
|
381
|
+
</p>
|
|
382
|
+
);
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
// after
|
|
386
|
+
function Badge() {
|
|
387
|
+
return (
|
|
388
|
+
<p>
|
|
389
|
+
{cart.owner}: {cart.count}
|
|
390
|
+
</p>
|
|
391
|
+
);
|
|
392
|
+
}
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
Destructuring props is different and is supported: `const { title } = props`
|
|
396
|
+
stays live.
|
|
397
|
+
|
|
398
|
+
### BARQ021
|
|
399
|
+
|
|
400
|
+
Default level: warning.
|
|
401
|
+
|
|
402
|
+
An async function passed to `createMemo`, `createProjection`, the function
|
|
403
|
+
forms of `createSignal` and `createStore`, or the first function of
|
|
404
|
+
`createEffect` reads a signal, memo, store or prop after its first `await`.
|
|
405
|
+
That read is not tracked, so the computation does not run again when it
|
|
406
|
+
changes. Read it before the first `await` and keep it in a local.
|
|
407
|
+
|
|
408
|
+
```tsx
|
|
409
|
+
// before
|
|
410
|
+
const results = createMemo(async () => {
|
|
411
|
+
const response = await fetch("https://example.com/items");
|
|
412
|
+
const items = await response.json();
|
|
413
|
+
return items.filter((item) => item.tag === query());
|
|
414
|
+
});
|
|
415
|
+
|
|
416
|
+
// after
|
|
417
|
+
const results = createMemo(async () => {
|
|
418
|
+
const tag = query();
|
|
419
|
+
const response = await fetch("https://example.com/items");
|
|
420
|
+
const items = await response.json();
|
|
421
|
+
return items.filter((item) => item.tag === tag);
|
|
422
|
+
});
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
### BARQ030
|
|
426
|
+
|
|
427
|
+
Default level: error.
|
|
428
|
+
|
|
429
|
+
A prop is assigned (`=`, `+=`, `++`) through `props.name`, a destructured name,
|
|
430
|
+
or a member of what `omit(props, ...)` returns. Props are read-only: the parent
|
|
431
|
+
owns the value. Ask for the change through a function prop, or keep a signal of
|
|
432
|
+
your own.
|
|
433
|
+
|
|
434
|
+
```tsx
|
|
435
|
+
// before
|
|
436
|
+
function Counter(props: { count: number }) {
|
|
437
|
+
return (
|
|
438
|
+
<button
|
|
439
|
+
onClick={() => {
|
|
440
|
+
props.count = props.count + 1;
|
|
441
|
+
}}
|
|
442
|
+
>
|
|
443
|
+
{props.count}
|
|
444
|
+
</button>
|
|
445
|
+
);
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
// after
|
|
449
|
+
function Counter(props: { count: number; onChange: (next: number) => void }) {
|
|
450
|
+
return <button onClick={() => props.onChange(props.count + 1)}>{props.count}</button>;
|
|
451
|
+
}
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
### BARQ031
|
|
455
|
+
|
|
456
|
+
Default level: error.
|
|
457
|
+
|
|
458
|
+
A props destructuring pattern has a shape that cannot stay reactive: a computed
|
|
459
|
+
key (`{ [key]: value }`), a default inside a nested pattern
|
|
460
|
+
(`{ user: { name = "guest" } }`), or a rest element inside a nested pattern
|
|
461
|
+
(`{ user: { id, ...others } }`). Destructure one level and read the rest where
|
|
462
|
+
it is used.
|
|
463
|
+
|
|
464
|
+
```tsx
|
|
465
|
+
// before
|
|
466
|
+
function Card({ user: { name = "guest" } }: { user: { name?: string } }) {
|
|
467
|
+
return <p>{name}</p>;
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
// after
|
|
471
|
+
function Card({ user }: { user: { name?: string } }) {
|
|
472
|
+
return <p>{user.name ?? "guest"}</p>;
|
|
473
|
+
}
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
One level (names, renames, defaults, a rest element) is always supported, and
|
|
477
|
+
so is a nested pattern with none of the three shapes.
|
|
478
|
+
|
|
479
|
+
## Server functions and routes
|
|
480
|
+
|
|
481
|
+
### BARQ012
|
|
482
|
+
|
|
483
|
+
Default level: error.
|
|
484
|
+
|
|
485
|
+
A module exports a server function (`createServerFn`) together with something
|
|
486
|
+
else, such as a component. The browser build replaces a server-function module
|
|
487
|
+
with request stubs, so it cannot keep any other export. Move the server
|
|
488
|
+
functions into a file that exports nothing else (types are allowed) and import
|
|
489
|
+
them.
|
|
490
|
+
|
|
491
|
+
```tsx
|
|
492
|
+
// todos.server.ts: every export is a server function
|
|
493
|
+
import { createServerFn } from "@barqjs/start";
|
|
494
|
+
|
|
495
|
+
export const saveTodo = createServerFn({ method: "POST" }).handler(async () => {
|
|
496
|
+
return { saved: true };
|
|
497
|
+
});
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
```tsx
|
|
501
|
+
// TodoList.tsx
|
|
502
|
+
import { saveTodo } from "./todos.server.ts";
|
|
503
|
+
|
|
504
|
+
export function TodoList() {
|
|
505
|
+
return <button onClick={() => saveTodo()}>Save</button>;
|
|
506
|
+
}
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
### BARQ013
|
|
510
|
+
|
|
511
|
+
Default level: warning.
|
|
512
|
+
|
|
513
|
+
A `<Link to>` or `<NavLink to>` from `@barqjs/router` has a literal, absolute
|
|
514
|
+
path that matches none of the project's routes, so following it shows the
|
|
515
|
+
not-found page. Correct the path, or add the route file. The route pattern
|
|
516
|
+
itself matches too, with `params`:
|
|
517
|
+
|
|
518
|
+
```tsx
|
|
519
|
+
// before, with routes "/", "/users" and "/users/$id"
|
|
520
|
+
<Link to="/user/7">Profile</Link>
|
|
521
|
+
|
|
522
|
+
// after
|
|
523
|
+
<Link to="/users/7">Profile</Link>
|
|
524
|
+
|
|
525
|
+
// or
|
|
526
|
+
<Link to="/users/$id" params={{ id: "7" }}>
|
|
527
|
+
Profile
|
|
528
|
+
</Link>
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
## Styles (`@barqjs/css`)
|
|
532
|
+
|
|
533
|
+
### BARQ014
|
|
534
|
+
|
|
535
|
+
Default level: error.
|
|
536
|
+
|
|
537
|
+
A `css`, `keyframes` or `globalCss` block is not valid CSS. The message names
|
|
538
|
+
the problem: Sass or Less syntax, `@import`, `@charset` or `@namespace` outside
|
|
539
|
+
`globalCss`, a declaration at the top level of `globalCss` with no selector, or
|
|
540
|
+
an `&` with no parent selector. Write plain CSS.
|
|
541
|
+
|
|
542
|
+
```tsx
|
|
543
|
+
// before
|
|
544
|
+
const card = css`
|
|
545
|
+
$brand: #3b82f6;
|
|
546
|
+
color: $brand;
|
|
547
|
+
`;
|
|
548
|
+
|
|
549
|
+
// after
|
|
550
|
+
const card = css`
|
|
551
|
+
--brand: #3b82f6;
|
|
552
|
+
color: var(--brand);
|
|
553
|
+
`;
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
### BARQ015
|
|
557
|
+
|
|
558
|
+
Default level: note. An error under `strictCss: true`.
|
|
559
|
+
|
|
560
|
+
A `css` block interpolates a value known only at run time, so its CSS is built
|
|
561
|
+
in the browser instead of at build time. Write a custom property in the block
|
|
562
|
+
and set its value on the element.
|
|
563
|
+
|
|
564
|
+
```tsx
|
|
565
|
+
// before
|
|
566
|
+
const panel = (background: string) => css`
|
|
567
|
+
padding: 12px;
|
|
568
|
+
background: ${background};
|
|
569
|
+
`;
|
|
570
|
+
|
|
571
|
+
// after
|
|
572
|
+
const panel = css`
|
|
573
|
+
padding: 12px;
|
|
574
|
+
background: var(--panel-bg);
|
|
575
|
+
`;
|
|
576
|
+
|
|
577
|
+
function Panel(props) {
|
|
578
|
+
return <div class={panel} style={{ "--panel-bg": props.background }} />;
|
|
579
|
+
}
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
### BARQ016
|
|
583
|
+
|
|
584
|
+
Default level: note. An error under `strictCss: true`.
|
|
585
|
+
|
|
586
|
+
An `atoms` call has more than one conditional argument, and the compiler
|
|
587
|
+
compiles one, so the call runs in the browser. Merge the conditions into one
|
|
588
|
+
object, or nest the calls:
|
|
589
|
+
|
|
590
|
+
```tsx
|
|
591
|
+
// before
|
|
592
|
+
atoms({ color: "red" }, active && { color: "blue" }, wide && { padding: 8 });
|
|
593
|
+
|
|
594
|
+
// after
|
|
595
|
+
atoms(atoms({ color: "red" }, active && { color: "blue" }), wide && { padding: 8 });
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
### BARQ017
|
|
599
|
+
|
|
600
|
+
Default level: note. An error under `strictCss: true`.
|
|
601
|
+
|
|
602
|
+
A `@barqjs/css` call (`atoms`, `create`, `defineVars`, `createTheme`,
|
|
603
|
+
`dynamic`) has a value, key or nested object the compiler cannot read in this
|
|
604
|
+
file: an import, a function call, a spread, a parameter. The call runs in the
|
|
605
|
+
browser. Write literals or a `const` declared in the same module. For a value
|
|
606
|
+
that changes, use `var(--name)` and set it through `style`, or a `dynamic`
|
|
607
|
+
group.
|
|
608
|
+
|
|
609
|
+
```tsx
|
|
610
|
+
// before
|
|
611
|
+
import { theme } from "./theme.ts";
|
|
612
|
+
const card = atoms({ color: theme.brand });
|
|
613
|
+
|
|
614
|
+
// after
|
|
615
|
+
const BRAND = "#3b82f6";
|
|
616
|
+
const card = atoms({ color: BRAND });
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
### BARQ032
|
|
620
|
+
|
|
621
|
+
Default level: warning.
|
|
622
|
+
|
|
623
|
+
One `atoms` call (or one `create` group) holds a shorthand barq keeps whole,
|
|
624
|
+
such as `border`, `font`, `flex`, `background` or `transition`, together with
|
|
625
|
+
one of its longhands under the same condition. The two are separate classes, so
|
|
626
|
+
neither replaces the other, and which declaration wins depends on where each
|
|
627
|
+
rule happens to sit in the stylesheet. It can change when another component
|
|
628
|
+
uses either declaration first.
|
|
629
|
+
|
|
630
|
+
Write the shorthand as its longhands, so the later argument replaces exactly
|
|
631
|
+
what it names:
|
|
632
|
+
|
|
633
|
+
```tsx
|
|
634
|
+
// before
|
|
635
|
+
atoms({ border: "1px solid gray" }, invalid && { borderColor: "red" });
|
|
636
|
+
|
|
637
|
+
// after
|
|
638
|
+
atoms(
|
|
639
|
+
{ borderWidth: 1, borderStyle: "solid", borderColor: "gray" },
|
|
640
|
+
invalid && { borderColor: "red" },
|
|
641
|
+
);
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
A shorthand that splits by counting (`margin`, `padding`, `inset`, `gap`,
|
|
645
|
+
`borderRadius`) is not reported: a later `marginTop` replaces one side.
|
|
646
|
+
|
|
647
|
+
### BARQ033
|
|
648
|
+
|
|
649
|
+
Default level: note.
|
|
650
|
+
|
|
651
|
+
One `atoms` call (or one `create` group) sets a property under two conditions
|
|
652
|
+
of one tier that can both match one element, with selectors of one weight, and
|
|
653
|
+
writes them in the order the shared stylesheet reverses. Both classes stay on
|
|
654
|
+
the element and the fixed order decides: no interaction pseudo-class first,
|
|
655
|
+
then `:link`, `:visited`, `:focus-within`, `:hover`, `:focus`, `:focus-visible`,
|
|
656
|
+
`:active`, `:disabled`; ties by the condition's hash. The one written first wins
|
|
657
|
+
where both match.
|
|
658
|
+
|
|
659
|
+
Write the pair in the fixed order, or make one rule the other out:
|
|
660
|
+
|
|
661
|
+
```tsx
|
|
662
|
+
// before
|
|
663
|
+
atoms({ color: { ":hover": "blue", "[data-active]": "red" } });
|
|
664
|
+
|
|
665
|
+
// after
|
|
666
|
+
atoms({ color: { "[data-active]": "red", ":hover": "blue" } });
|
|
667
|
+
// or, so the active colour holds under the pointer
|
|
668
|
+
atoms({ color: { "[data-active]": "red", ":not([data-active]):hover": "blue" } });
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
Not reported: an attribute equal to two values, two different child positions,
|
|
672
|
+
a selector against its `:not()`, two media ranges of one feature that do not
|
|
673
|
+
meet, two selectors of different specificity, one value under both, two
|
|
674
|
+
pseudo-elements, or a pair the same object settles with a condition that is
|
|
675
|
+
both at once. Every reported pair is listed.
|
|
676
|
+
|
|
677
|
+
### BARQ034
|
|
678
|
+
|
|
679
|
+
Default level: error.
|
|
680
|
+
|
|
681
|
+
A component destructures a prop with a string default and writes the name as a
|
|
682
|
+
tag. A tag is called as a component, so `"div"` can never render. An element
|
|
683
|
+
chosen at run time is `dynamic`:
|
|
684
|
+
|
|
685
|
+
```tsx
|
|
686
|
+
// before
|
|
687
|
+
function Box({ as: Tag = "div", ...rest }) {
|
|
688
|
+
return <Tag {...rest} />;
|
|
689
|
+
}
|
|
690
|
+
|
|
691
|
+
// after
|
|
692
|
+
function Box(props) {
|
|
693
|
+
const Tag = dynamic(() => props.as ?? "div");
|
|
694
|
+
return <Tag {...omit(props, "as")} />;
|
|
695
|
+
}
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
## Solid 1.x spellings
|
|
699
|
+
|
|
700
|
+
These still parse, would build, and would misbehave at run time, so they are
|
|
701
|
+
errors.
|
|
702
|
+
|
|
703
|
+
### BARQ022
|
|
704
|
+
|
|
705
|
+
Default level: error.
|
|
706
|
+
|
|
707
|
+
A context is rendered through `.Provider`. A context is its own provider.
|
|
708
|
+
|
|
709
|
+
```tsx
|
|
710
|
+
// before
|
|
711
|
+
<Theme.Provider value="dark">{props.children}</Theme.Provider>
|
|
712
|
+
|
|
713
|
+
// after
|
|
714
|
+
<Theme value="dark">{props.children}</Theme>
|
|
715
|
+
```
|
|
716
|
+
|
|
717
|
+
### BARQ023
|
|
718
|
+
|
|
719
|
+
Default level: error.
|
|
720
|
+
|
|
721
|
+
`classList` is written on an element, where it is an ordinary attribute and
|
|
722
|
+
would be written as `[object Object]`. Pass the map to `class`, which takes a
|
|
723
|
+
string, a map of names to whether each applies, or a list of both.
|
|
724
|
+
|
|
725
|
+
```tsx
|
|
726
|
+
// before
|
|
727
|
+
<div class="card" classList={{ active: active() }} />
|
|
728
|
+
|
|
729
|
+
// after
|
|
730
|
+
<div class={["card", { active: active() }]} />
|
|
731
|
+
```
|
|
732
|
+
|
|
733
|
+
### BARQ024
|
|
734
|
+
|
|
735
|
+
Default level: error.
|
|
736
|
+
|
|
737
|
+
An attribute uses a removed namespace prefix. Replace it by prefix:
|
|
738
|
+
|
|
739
|
+
- `on:x`: `onX={handler}`, or `addEventListener` in a `ref` for a hyphenated
|
|
740
|
+
event name or listener options.
|
|
741
|
+
- `capture:x`, `oncapture:x`: `onXCapture={handler}`.
|
|
742
|
+
- `attr:x`: `x={value}`.
|
|
743
|
+
- `bool:x`: `x={on()}`, where `true` adds the attribute and `false` removes it.
|
|
744
|
+
- `style:x`: a key of the `style` object.
|
|
745
|
+
- `class:x`: a key of the `class` map.
|
|
746
|
+
- `use:x`: `ref={x(options)}`, and `ref={[x(options), y]}` for several.
|
|
747
|
+
|
|
748
|
+
```tsx
|
|
749
|
+
// before
|
|
750
|
+
<input on:input={props.onInput} />
|
|
751
|
+
|
|
752
|
+
// after
|
|
753
|
+
<input onInput={props.onInput} />
|
|
754
|
+
```
|
|
755
|
+
|
|
756
|
+
`prop:` and `bind:` keep their meaning and are not reported.
|
|
757
|
+
|
|
758
|
+
### BARQ025
|
|
759
|
+
|
|
760
|
+
Default level: error.
|
|
761
|
+
|
|
762
|
+
`<Dynamic component={...}>` is rendered. barq has the `dynamic` factory from
|
|
763
|
+
`@barqjs/web` instead. Hoist one to the component body (or to the module when
|
|
764
|
+
the choice reads only module state) and render it with the other props.
|
|
765
|
+
|
|
766
|
+
```tsx
|
|
767
|
+
// before
|
|
768
|
+
import { Dynamic } from "@barqjs/web";
|
|
769
|
+
const Field = (props) => (
|
|
770
|
+
<Dynamic component={props.editing ? Editor : Viewer} value={props.value} />
|
|
771
|
+
);
|
|
772
|
+
|
|
773
|
+
// after
|
|
774
|
+
import { dynamic } from "@barqjs/web";
|
|
775
|
+
const Field = (props) => {
|
|
776
|
+
const Chosen = dynamic(() => (props.editing ? Editor : Viewer));
|
|
777
|
+
return <Chosen value={props.value} />;
|
|
778
|
+
};
|
|
779
|
+
```
|
|
780
|
+
|
|
781
|
+
The source may answer with a tag name (`dynamic(() => "h" + props.level)`), or
|
|
782
|
+
with `null`, `undefined` or `false` to render nothing.
|
|
783
|
+
|
|
784
|
+
## Markup
|
|
785
|
+
|
|
786
|
+
### BARQ026
|
|
787
|
+
|
|
788
|
+
Default level: error.
|
|
789
|
+
|
|
790
|
+
The JSX nests elements in a way the browser's HTML parser rebuilds, so a
|
|
791
|
+
server-rendered page hydrates against a different tree (a
|
|
792
|
+
`HYDRATION_MISMATCH` and a full re-render). The message names the pair:
|
|
793
|
+
|
|
794
|
+
- a block element such as `<div>` inside a `<p>`;
|
|
795
|
+
- a table part outside its parent (`<tr>` directly in `<table>`, `<td>` in a
|
|
796
|
+
`<div>`), or a non-table element inside a `<tr>`;
|
|
797
|
+
- an element that `<select>`, `<optgroup>` or `<option>` does not take;
|
|
798
|
+
- a second `<a>`, `<button>`, `<form>`, `<li>`, `<dd>` or `<dt>` inside an open
|
|
799
|
+
one;
|
|
800
|
+
- `<html>`, `<head>` or `<body>` inside a page.
|
|
801
|
+
|
|
802
|
+
Move the inner element out, change the outer element, or write the wrapper the
|
|
803
|
+
parser expects (`<tbody>` around rows).
|
|
804
|
+
|
|
805
|
+
```tsx
|
|
806
|
+
// before
|
|
807
|
+
<p>
|
|
808
|
+
Your order shipped.
|
|
809
|
+
<div class="details">{props.tracking}</div>
|
|
810
|
+
</p>
|
|
811
|
+
|
|
812
|
+
// after
|
|
813
|
+
<div>
|
|
814
|
+
<p>Your order shipped.</p>
|
|
815
|
+
<div class="details">{props.tracking}</div>
|
|
816
|
+
</div>
|
|
817
|
+
```
|
|
818
|
+
|
|
819
|
+
## Custom renderers
|
|
820
|
+
|
|
821
|
+
### BARQ027
|
|
822
|
+
|
|
823
|
+
Default level: error.
|
|
824
|
+
|
|
825
|
+
A `bind:` attribute or a form `action` function is written on an element that a
|
|
826
|
+
custom renderer builds (`target: "universal"`). Both need a document form
|
|
827
|
+
control. Pass the value as a prop and write it back from the host's own event.
|
|
828
|
+
|
|
829
|
+
```tsx
|
|
830
|
+
// before
|
|
831
|
+
<input bind:value={props.text} />
|
|
832
|
+
|
|
833
|
+
// after
|
|
834
|
+
<input value={props.text} onChange={(next: string) => props.setText(next)} />
|
|
835
|
+
```
|
|
836
|
+
|
|
837
|
+
For `action`, call the function from the host's event:
|
|
838
|
+
`onSubmit={() => save()}`.
|
|
839
|
+
|
|
840
|
+
### BARQ028
|
|
841
|
+
|
|
842
|
+
Default level: error.
|
|
843
|
+
|
|
844
|
+
A module compiled with `target: "universal"` is also asked for `ssr`,
|
|
845
|
+
`hydratable` or `interp`, which describe a document. This is about the build
|
|
846
|
+
options, not a line of source. Remove the document option from that module's
|
|
847
|
+
options, or give the custom renderer's files their own `renderers` entry and
|
|
848
|
+
keep `ssr` for the rest:
|
|
849
|
+
|
|
850
|
+
```ts
|
|
851
|
+
barq({
|
|
852
|
+
ssr: true,
|
|
853
|
+
compiler: {
|
|
854
|
+
renderers: [
|
|
855
|
+
{ include: ["src/scene/**"], target: "universal", moduleSource: "/src/renderer.ts" },
|
|
856
|
+
],
|
|
857
|
+
},
|
|
858
|
+
});
|
|
859
|
+
```
|
|
860
|
+
|
|
861
|
+
### BARQ029
|
|
862
|
+
|
|
863
|
+
Default level: warning.
|
|
864
|
+
|
|
865
|
+
Two installed renderers claim the same intrinsic tag (the message names the tag
|
|
866
|
+
and both packages), so the tag compiles for the document. Claim it in the
|
|
867
|
+
application's own configuration, which wins over what a package declares:
|
|
868
|
+
|
|
869
|
+
```ts
|
|
870
|
+
barq({
|
|
871
|
+
compiler: {
|
|
872
|
+
intrinsics: [{ tags: ["mesh"], target: "universal", moduleSource: "@acme/scene/renderer" }],
|
|
873
|
+
},
|
|
874
|
+
});
|
|
875
|
+
```
|
|
876
|
+
|
|
877
|
+
## What the compiler cannot see
|
|
878
|
+
|
|
879
|
+
The checks report only what one file proves, so silence is not a guarantee:
|
|
880
|
+
|
|
881
|
+
- An accessor imported from another module is not known to be one (`BARQ001`
|
|
882
|
+
to `BARQ003`), and `BARQ010` does not follow a prop into a component declared
|
|
883
|
+
in another file.
|
|
884
|
+
- A write inside a helper function the component body calls is not seen by
|
|
885
|
+
`BARQ019`. The runtime reports it as `REACTIVE_WRITE_IN_OWNED_SCOPE`.
|
|
886
|
+
- `BARQ018` counts a prop only where the same file renders the component with
|
|
887
|
+
a value that changes.
|
|
888
|
+
- `BARQ030` and `BARQ031` apply to components: a function with a capitalised
|
|
889
|
+
name that renders JSX, a default export that does, or a function written
|
|
890
|
+
inline at a route's `component` option.
|