create-barq 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +72 -2
- package/dist/index.js +201 -0
- package/package.json +46 -4
- package/templates/full-stack/AGENTS.md +51 -0
- package/templates/full-stack/README.md +45 -0
- package/templates/full-stack/_gitignore +7 -0
- package/templates/full-stack/package.json +28 -0
- package/templates/full-stack/src/data/greeting.ts +19 -0
- package/templates/full-stack/src/routes/__root.tsx +77 -0
- package/templates/full-stack/src/routes/about.tsx +33 -0
- package/templates/full-stack/src/routes/api/health.ts +22 -0
- package/templates/full-stack/src/routes/index.tsx +27 -0
- package/templates/full-stack/tsconfig.json +18 -0
- package/templates/full-stack/vite.config.ts +19 -0
- package/templates/minimal/AGENTS.md +48 -0
- package/templates/minimal/README.md +25 -0
- package/templates/minimal/_gitignore +6 -0
- package/templates/minimal/index.html +12 -0
- package/templates/minimal/package.json +23 -0
- package/templates/minimal/src/App.tsx +15 -0
- package/templates/minimal/src/main.tsx +8 -0
- package/templates/minimal/tsconfig.json +17 -0
- package/templates/minimal/vite.config.ts +6 -0
- package/templates/spa/AGENTS.md +52 -0
- package/templates/spa/README.md +36 -0
- package/templates/spa/_gitignore +6 -0
- package/templates/spa/index.html +12 -0
- package/templates/spa/package.json +28 -0
- package/templates/spa/src/data/greeting.ts +19 -0
- package/templates/spa/src/main.tsx +21 -0
- package/templates/spa/src/routes/__root.tsx +29 -0
- package/templates/spa/src/routes/about.tsx +29 -0
- package/templates/spa/src/routes/index.tsx +16 -0
- package/templates/spa/tsconfig.json +18 -0
- package/templates/spa/vite.config.ts +8 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Salama Ashoush
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,73 @@
|
|
|
1
|
-
#
|
|
1
|
+
# create-barq
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Scaffold a barq project: a Vite app with the barq compiler, and, depending on
|
|
4
|
+
the template, file routes, server rendering and server functions.
|
|
5
|
+
|
|
6
|
+
## Usage
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
bun create barq my-app
|
|
10
|
+
npm create barq@latest my-app
|
|
11
|
+
pnpm create barq my-app
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
With no arguments it asks for a directory and a template. With them it asks
|
|
15
|
+
nothing:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
bun create barq my-app --template spa
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
create-barq [directory] [options]
|
|
23
|
+
|
|
24
|
+
-t, --template NAME full-stack | spa | minimal
|
|
25
|
+
--overwrite empty the directory first
|
|
26
|
+
-h, --help show this
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Then install and start the dev server with the package manager that ran it:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
cd my-app
|
|
33
|
+
bun install
|
|
34
|
+
bun run dev
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## The templates
|
|
38
|
+
|
|
39
|
+
- `full-stack`: pages rendered on the server, prerendered where a route says
|
|
40
|
+
so, with file routes, an API route and a server function. Run the build with
|
|
41
|
+
`bun dist/server/serve.js`.
|
|
42
|
+
- `spa`: pages rendered in the browser from your own `index.html`, with file
|
|
43
|
+
routes and a server function. Run the build with `bun dist/server/serve.js`.
|
|
44
|
+
- `minimal`: one `index.html`, the compiler and signals, no router and no
|
|
45
|
+
server. The build is static files for any host.
|
|
46
|
+
|
|
47
|
+
`full-stack` is the default. Each `vite.config.ts` is one call to the plugin
|
|
48
|
+
from `@barqjs/vite`: `barq({ ssr: true, start })`, `barq({ start: true })` and
|
|
49
|
+
`barq()`.
|
|
50
|
+
|
|
51
|
+
Every template is tested before it is published. `test/scaffold.test.ts`
|
|
52
|
+
scaffolds each into a temporary directory, runs its own `vite build` and `tsc`,
|
|
53
|
+
starts the server it produced and fetches from it.
|
|
54
|
+
|
|
55
|
+
## What a scaffolded project does not contain
|
|
56
|
+
|
|
57
|
+
- **No server or client entry.** `src/entry-client.tsx` and
|
|
58
|
+
`src/entry-server.ts` are optional overrides, and the plugin supplies the
|
|
59
|
+
defaults. The `spa` template's `src/main.tsx` is the module `index.html`
|
|
60
|
+
loads, not an entry the plugin looks for.
|
|
61
|
+
- **No `src/routeTree.gen.ts`.** The Vite plugin writes it on the first build
|
|
62
|
+
or dev start. Commit it. It is an ordinary module the project imports by
|
|
63
|
+
path, and it typechecks and reads like one.
|
|
64
|
+
- **No `src/virtual.d.ts`.** The declarations for the build's own modules ship
|
|
65
|
+
inside `@barqjs/router`.
|
|
66
|
+
|
|
67
|
+
## Adding routes
|
|
68
|
+
|
|
69
|
+
A route is a file under `src/routes`. `about.tsx` is `/about`. `posts/$id.tsx`
|
|
70
|
+
is `/posts/:id`. `api/health.ts` is an API route, because it declares `server`
|
|
71
|
+
handlers instead of a component. `__root.tsx` is the layout every page renders
|
|
72
|
+
inside and, for a server-rendered app, the document. The
|
|
73
|
+
[router README](../router/README.md) has the full set of conventions.
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { basename, join, resolve } from "node:path";
|
|
3
|
+
import { createInterface } from "node:readline/promises";
|
|
4
|
+
import { stdin, stdout } from "node:process";
|
|
5
|
+
import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
// src/scaffold.ts
|
|
8
|
+
/**
|
|
9
|
+
* Copying a template into a directory, with nothing interactive in it.
|
|
10
|
+
*
|
|
11
|
+
* Split from the CLI so the gate can scaffold exactly what a person gets —
|
|
12
|
+
* `bun create barq` and the test go through this one function, and a template
|
|
13
|
+
* that only builds because the test set it up differently is a template that
|
|
14
|
+
* does not build.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* npm REWRITES a published `.gitignore` to `.npmignore`, so a template that
|
|
18
|
+
* ships one loses it on install. create-vite carries the same rename for the
|
|
19
|
+
* same reason (`create-vite/src/index.ts`, `renameFiles`).
|
|
20
|
+
*/
|
|
21
|
+
const RENAMED = { _gitignore: ".gitignore" };
|
|
22
|
+
/**
|
|
23
|
+
* `../templates`, from `dist/index.js` and from `src/` alike.
|
|
24
|
+
*
|
|
25
|
+
* Both are one directory below the package root, which is why this is a single
|
|
26
|
+
* expression rather than a build-time constant.
|
|
27
|
+
*/
|
|
28
|
+
const TEMPLATE_ROOT = fileURLToPath(new URL("../templates", import.meta.url));
|
|
29
|
+
function isEmpty(path) {
|
|
30
|
+
if (!existsSync(path)) return true;
|
|
31
|
+
const files = readdirSync(path);
|
|
32
|
+
return files.length === 0 || files.length === 1 && files[0] === ".git";
|
|
33
|
+
}
|
|
34
|
+
/** npm's own rule, so a name this produces is one `npm init` would accept. */
|
|
35
|
+
function isValidPackageName(name) {
|
|
36
|
+
return /^(?:@[a-z\d\-*~][a-z\d\-*._~]*\/)?[a-z\d\-~][a-z\d\-._~]*$/.test(name);
|
|
37
|
+
}
|
|
38
|
+
function toValidPackageName(name) {
|
|
39
|
+
return name.trim().toLowerCase().replace(/\s+/g, "-").replace(/^[._]/, "").replace(/[^a-z\d\-~]+/g, "-");
|
|
40
|
+
}
|
|
41
|
+
function scaffold(options) {
|
|
42
|
+
const source = join(TEMPLATE_ROOT, options.template);
|
|
43
|
+
if (!existsSync(source)) throw new Error(`no template named "${options.template}"`);
|
|
44
|
+
if (options.overwrite === true && existsSync(options.target)) for (const entry of readdirSync(options.target)) {
|
|
45
|
+
if (entry === ".git") continue;
|
|
46
|
+
rmSync(join(options.target, entry), {
|
|
47
|
+
recursive: true,
|
|
48
|
+
force: true
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
else if (!isEmpty(options.target)) throw new Error(`${options.target} is not empty`);
|
|
52
|
+
mkdirSync(options.target, { recursive: true });
|
|
53
|
+
cpSync(source, options.target, { recursive: true });
|
|
54
|
+
for (const [from, to] of Object.entries(RENAMED)) {
|
|
55
|
+
const written = join(options.target, from);
|
|
56
|
+
if (existsSync(written)) renameSync(written, join(options.target, to));
|
|
57
|
+
}
|
|
58
|
+
const manifestPath = join(options.target, "package.json");
|
|
59
|
+
const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
|
|
60
|
+
manifest.name = options.packageName;
|
|
61
|
+
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
|
62
|
+
}
|
|
63
|
+
// src/templates.ts
|
|
64
|
+
const TEMPLATES = [
|
|
65
|
+
{
|
|
66
|
+
name: "full-stack",
|
|
67
|
+
title: "Full-stack",
|
|
68
|
+
description: "Server-rendered pages, API routes, server functions, prerendering.",
|
|
69
|
+
spa: false,
|
|
70
|
+
prerenders: true,
|
|
71
|
+
server: true,
|
|
72
|
+
clientOut: "dist/client"
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
name: "spa",
|
|
76
|
+
title: "SPA",
|
|
77
|
+
description: "Client-rendered routing with server functions. The document is index.html.",
|
|
78
|
+
spa: true,
|
|
79
|
+
prerenders: false,
|
|
80
|
+
server: true,
|
|
81
|
+
clientOut: "dist/client"
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
name: "minimal",
|
|
85
|
+
title: "Minimal",
|
|
86
|
+
description: "The compiler and signals, no router. One page, one mount.",
|
|
87
|
+
spa: true,
|
|
88
|
+
prerenders: false,
|
|
89
|
+
server: false,
|
|
90
|
+
clientOut: "dist"
|
|
91
|
+
}
|
|
92
|
+
];
|
|
93
|
+
const DEFAULT_TEMPLATE = "full-stack";
|
|
94
|
+
function findTemplate(name) {
|
|
95
|
+
return TEMPLATES.find((template) => template.name === name);
|
|
96
|
+
}
|
|
97
|
+
// src/index.ts
|
|
98
|
+
/**
|
|
99
|
+
* `bun create barq my-app` / `npm create barq@latest my-app`.
|
|
100
|
+
*
|
|
101
|
+
* NO DEPENDENCIES. A `create-*` package is downloaded before the project it
|
|
102
|
+
* scaffolds exists, so every dependency is latency a person pays before seeing
|
|
103
|
+
* anything — the argument parsing and the two prompts here are smaller than the
|
|
104
|
+
* libraries that would do them.
|
|
105
|
+
*
|
|
106
|
+
* It scaffolds a project and stops. Route generators (`barq add route /posts/$id`)
|
|
107
|
+
* are the obvious next thing and are deliberately not here: the route tree is
|
|
108
|
+
* already generated by the Vite plugin, so the CLI's only job today is the one
|
|
109
|
+
* a person cannot do by copying a directory.
|
|
110
|
+
*/
|
|
111
|
+
const HELP = `\
|
|
112
|
+
Usage: create-barq [directory] [options]
|
|
113
|
+
|
|
114
|
+
Create a barq project.
|
|
115
|
+
|
|
116
|
+
Options:
|
|
117
|
+
-t, --template NAME ${TEMPLATES.map((t) => t.name).join(" | ")}
|
|
118
|
+
--overwrite empty the directory first
|
|
119
|
+
-h, --help show this
|
|
120
|
+
|
|
121
|
+
Templates:
|
|
122
|
+
${TEMPLATES.map((t) => ` ${t.name.padEnd(12)}${t.description}`).join("\n")}
|
|
123
|
+
`;
|
|
124
|
+
function parse(argv) {
|
|
125
|
+
let directory;
|
|
126
|
+
let template;
|
|
127
|
+
let overwrite = false;
|
|
128
|
+
let help = false;
|
|
129
|
+
for (let i = 0; i < argv.length; i++) {
|
|
130
|
+
const arg = argv[i] ?? "";
|
|
131
|
+
if (arg === "-h" || arg === "--help") help = true;
|
|
132
|
+
else if (arg === "--overwrite") overwrite = true;
|
|
133
|
+
else if (arg === "-t" || arg === "--template") template = argv[++i];
|
|
134
|
+
else if (arg.startsWith("--template=")) template = arg.slice(11);
|
|
135
|
+
else if (arg.startsWith("-")) throw new Error(`unknown option ${arg}`);
|
|
136
|
+
else directory ??= arg;
|
|
137
|
+
}
|
|
138
|
+
return {
|
|
139
|
+
directory,
|
|
140
|
+
template,
|
|
141
|
+
overwrite,
|
|
142
|
+
help
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
/** What ran us, for the "now run" lines. `npm_config_user_agent` is set by all of them. */
|
|
146
|
+
function packageManager() {
|
|
147
|
+
const name = process.env.npm_config_user_agent?.split(" ")[0]?.split("/")[0];
|
|
148
|
+
return name === void 0 || name === "" ? "npm" : name;
|
|
149
|
+
}
|
|
150
|
+
async function main() {
|
|
151
|
+
const args = parse(process.argv.slice(2));
|
|
152
|
+
if (args.help) {
|
|
153
|
+
stdout.write(HELP);
|
|
154
|
+
return;
|
|
155
|
+
}
|
|
156
|
+
const rl = stdin.isTTY ? createInterface({
|
|
157
|
+
input: stdin,
|
|
158
|
+
output: stdout
|
|
159
|
+
}) : null;
|
|
160
|
+
const ask = async (question, fallback) => {
|
|
161
|
+
if (rl === null) return fallback;
|
|
162
|
+
const answer = (await rl.question(`${question} (${fallback}) `)).trim();
|
|
163
|
+
return answer === "" ? fallback : answer;
|
|
164
|
+
};
|
|
165
|
+
try {
|
|
166
|
+
const directory = args.directory ?? await ask("Project directory:", "barq-project");
|
|
167
|
+
const target = resolve(process.cwd(), directory);
|
|
168
|
+
const name = args.template ?? await askTemplate(ask);
|
|
169
|
+
const template = findTemplate(name);
|
|
170
|
+
if (template === void 0) throw new Error(`no template named "${name}". Try one of: ${TEMPLATES.map((t) => t.name).join(", ")}`);
|
|
171
|
+
let overwrite = args.overwrite;
|
|
172
|
+
if (!overwrite && !isEmpty(target)) {
|
|
173
|
+
overwrite = (await ask(`${directory} is not empty. Empty it?`, "no")).toLowerCase().startsWith("y");
|
|
174
|
+
if (!overwrite) throw new Error(`${directory} is not empty`);
|
|
175
|
+
}
|
|
176
|
+
const suggested = toValidPackageName(basename(target));
|
|
177
|
+
const packageName = isValidPackageName(suggested) ? suggested : "barq-project";
|
|
178
|
+
scaffold({
|
|
179
|
+
template: template.name,
|
|
180
|
+
target,
|
|
181
|
+
packageName,
|
|
182
|
+
overwrite
|
|
183
|
+
});
|
|
184
|
+
const pm = packageManager();
|
|
185
|
+
const install = pm === "npm" ? "npm install" : `${pm} install`;
|
|
186
|
+
const dev = pm === "npm" ? "npm run dev" : `${pm} run dev`;
|
|
187
|
+
stdout.write(`\nScaffolded ${template.title} in ${directory}.\n\n cd ${directory}\n ${install}\n ${dev}\n\n`);
|
|
188
|
+
} finally {
|
|
189
|
+
rl?.close();
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
async function askTemplate(ask) {
|
|
193
|
+
stdout.write("\nTemplates:\n");
|
|
194
|
+
for (const template of TEMPLATES) stdout.write(` ${template.name.padEnd(12)}${template.description}\n`);
|
|
195
|
+
return ask("\nTemplate:", DEFAULT_TEMPLATE);
|
|
196
|
+
}
|
|
197
|
+
main().catch((error) => {
|
|
198
|
+
stdout.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
|
|
199
|
+
process.exitCode = 1;
|
|
200
|
+
});
|
|
201
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,48 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-barq",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0-next.1",
|
|
4
|
+
"description": "Scaffold a barq project from the full-stack, SPA or minimal template",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"barq",
|
|
7
|
+
"create",
|
|
8
|
+
"scaffold",
|
|
9
|
+
"starter"
|
|
10
|
+
],
|
|
11
|
+
"homepage": "https://github.com/salamaashoush/barq#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/salamaashoush/barq/issues"
|
|
14
|
+
},
|
|
15
|
+
"license": "MIT",
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/salamaashoush/barq.git",
|
|
19
|
+
"directory": "packages/create-barq"
|
|
20
|
+
},
|
|
21
|
+
"files": [
|
|
22
|
+
"dist",
|
|
23
|
+
"templates"
|
|
24
|
+
],
|
|
25
|
+
"type": "module",
|
|
26
|
+
"sideEffects": true,
|
|
27
|
+
"bin": {
|
|
28
|
+
"create-barq": "./dist/index.js"
|
|
29
|
+
},
|
|
30
|
+
"scripts": {
|
|
31
|
+
"build": "tsdown",
|
|
32
|
+
"dev": "tsdown --watch",
|
|
33
|
+
"typecheck": "tsc --noEmit",
|
|
34
|
+
"test": "bun test"
|
|
35
|
+
},
|
|
36
|
+
"devDependencies": {
|
|
37
|
+
"@types/bun": "^1.4.4",
|
|
38
|
+
"typescript": "^7.0.2",
|
|
39
|
+
"vite": "^8.3.8"
|
|
40
|
+
},
|
|
41
|
+
"engines": {
|
|
42
|
+
"node": "^20.19.0 || >=22.12.0"
|
|
43
|
+
},
|
|
44
|
+
"publishConfig": {
|
|
45
|
+
"access": "public",
|
|
46
|
+
"provenance": true
|
|
47
|
+
}
|
|
48
|
+
}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Working in this project
|
|
2
|
+
|
|
3
|
+
This is a barq application: a JSX framework where a component function runs
|
|
4
|
+
once and only the DOM nodes that read a changed signal update. It is not React
|
|
5
|
+
and not Solid, so read the authoring skill before writing components.
|
|
6
|
+
|
|
7
|
+
## Skills
|
|
8
|
+
|
|
9
|
+
Installed with the packages, under `node_modules`:
|
|
10
|
+
|
|
11
|
+
- `node_modules/@barqjs/core/skills/barq/SKILL.md`: how to write barq (props
|
|
12
|
+
as values, signals, the two-function `createEffect`, stores, control flow,
|
|
13
|
+
async). Read it before writing or reviewing application code.
|
|
14
|
+
- `node_modules/@barqjs/core/skills/diagnostics/SKILL.md`: one section per
|
|
15
|
+
runtime `[CODE]`, with the repair.
|
|
16
|
+
- `node_modules/@barqjs/compiler/skills/compiler-diagnostics/SKILL.md`: one
|
|
17
|
+
section per build-time `BARQ0NN` code, with the repair.
|
|
18
|
+
- `node_modules/@barqjs/diagnostics/skills/agent-loops/SKILL.md`: capturing a
|
|
19
|
+
run as evidence for cost and responsiveness findings. Present when
|
|
20
|
+
`@barqjs/diagnostics` is installed.
|
|
21
|
+
|
|
22
|
+
## Rule
|
|
23
|
+
|
|
24
|
+
When a console or build message carries a `[CODE]` or a `BARQ0NN`, open the
|
|
25
|
+
skill section for that code before changing code. The console entry's `in`
|
|
26
|
+
line is the component path and its `at` line is `file:line:col`. Repair the
|
|
27
|
+
cause; a suppression comment or `untrack` leaves the defect in place.
|
|
28
|
+
|
|
29
|
+
## Commands
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm run dev # the Vite dev server, http://localhost:5173
|
|
33
|
+
npm run build # production build into dist/client and dist/server
|
|
34
|
+
npm run preview # the built server, through vite preview
|
|
35
|
+
npm start # bun dist/server/serve.js
|
|
36
|
+
npm run typecheck # tsc --noEmit
|
|
37
|
+
npm run check # barq check: the compiler's findings, no build needed
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Run `npm run check` and `npm run typecheck` after a change, and `npm run build`
|
|
41
|
+
before calling it done. `npx barq check --json` gives the findings as JSON, and
|
|
42
|
+
`npx barq check --fix` applies the repairs that are one spelling. Diagnostics print
|
|
43
|
+
in the browser console, and server-side ones in the terminal of `npm run dev`.
|
|
44
|
+
|
|
45
|
+
## Layout
|
|
46
|
+
|
|
47
|
+
- `src/routes`: one file per route. `__root.tsx` is the document and the
|
|
48
|
+
layout, and `api/health.ts` is an API route.
|
|
49
|
+
- `src/data/greeting.ts`: a server function. A file that exports server
|
|
50
|
+
functions exports nothing else (`BARQ012`).
|
|
51
|
+
- `src/routeTree.gen.ts`: written by the build. Commit it, do not edit it.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# barq, full-stack
|
|
2
|
+
|
|
3
|
+
Pages rendered on the server and hydrated in the browser, one prerendered at
|
|
4
|
+
build time, an API route and a server function.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
npm install
|
|
8
|
+
npm run dev # http://localhost:5173
|
|
9
|
+
npm run build # dist/client and dist/server
|
|
10
|
+
npm run preview # the built server, through vite preview
|
|
11
|
+
npm start # bun dist/server/serve.js
|
|
12
|
+
npm run typecheck
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## The files
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
src/routes/__root.tsx the document (shellComponent) and the layout
|
|
19
|
+
src/routes/index.tsx / prerendered to a file at build time
|
|
20
|
+
src/routes/about.tsx /about rendered per request, from a loader
|
|
21
|
+
src/routes/api/health.ts /api/health an API route: handlers, no component
|
|
22
|
+
src/data/greeting.ts a server function
|
|
23
|
+
src/routeTree.gen.ts written by the build. Commit it, do not edit it.
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
A file under `src/routes` is a route. `posts/$id.tsx` is `/posts/:id`,
|
|
27
|
+
`posts.tsx` beside a `posts/` directory is that subtree's layout, and a file
|
|
28
|
+
that declares `server: { handlers }` instead of a component is an API route.
|
|
29
|
+
|
|
30
|
+
## Three things worth knowing
|
|
31
|
+
|
|
32
|
+
**`prerender: true` is read at build time.** It is lifted out of the route's
|
|
33
|
+
options by the generator, so it has to be a literal. The build renders `/`,
|
|
34
|
+
follows the links in what it produced, and writes every page it reaches whose
|
|
35
|
+
route asks for one.
|
|
36
|
+
|
|
37
|
+
**A server function is its own endpoint.** `greeting()` looks like a call and is
|
|
38
|
+
an HTTP request to `/_barq/fn/<id>`. A guard on the route that renders it does
|
|
39
|
+
not run when somebody calls it directly, which is why `vite.config.ts` arms
|
|
40
|
+
`verify`: declare `middleware` on a route and the build refuses to ship unless
|
|
41
|
+
every server function that route can reach carries the same middleware.
|
|
42
|
+
|
|
43
|
+
**The document is a route.** `shellComponent` in `__root.tsx` renders `<html>`,
|
|
44
|
+
and `<HeadContent />` and `<Scripts />` place themselves. There is no HTML
|
|
45
|
+
template and no order to get right.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "barq-project",
|
|
3
|
+
"private": true,
|
|
4
|
+
"type": "module",
|
|
5
|
+
"scripts": {
|
|
6
|
+
"dev": "vite",
|
|
7
|
+
"build": "vite build",
|
|
8
|
+
"preview": "vite preview",
|
|
9
|
+
"start": "bun dist/server/serve.js",
|
|
10
|
+
"typecheck": "tsc --noEmit",
|
|
11
|
+
"check": "barq check src"
|
|
12
|
+
},
|
|
13
|
+
"dependencies": {
|
|
14
|
+
"@barqjs/core": "^0.2.0-next.1",
|
|
15
|
+
"@barqjs/css": "^0.2.0-next.1",
|
|
16
|
+
"@barqjs/router": "^0.2.0-next.1",
|
|
17
|
+
"@barqjs/server": "^0.2.0-next.1",
|
|
18
|
+
"@barqjs/start": "^0.2.0-next.1",
|
|
19
|
+
"@barqjs/web": "^0.2.0-next.1"
|
|
20
|
+
},
|
|
21
|
+
"devDependencies": {
|
|
22
|
+
"@barqjs/cli": "^0.2.0-next.1",
|
|
23
|
+
"@barqjs/vite": "^0.2.0-next.1",
|
|
24
|
+
"@types/bun": "^1.4.4",
|
|
25
|
+
"typescript": "^7.0.2",
|
|
26
|
+
"vite": "^8.3.8"
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A server function: one HTTP endpoint, called like a function.
|
|
3
|
+
*
|
|
4
|
+
* The body never reaches the browser. The compiler replaces this module's
|
|
5
|
+
* exports with client stubs that call `/_barq/fn/<id>`, so anything it
|
|
6
|
+
* imports — a database driver, a secret — stays on the server.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { createServerFn } from "@barqjs/start";
|
|
10
|
+
|
|
11
|
+
export interface Greeting {
|
|
12
|
+
readonly message: string;
|
|
13
|
+
readonly at: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export const greeting = createServerFn().handler((): Greeting => ({
|
|
17
|
+
message: "Hello from the server.",
|
|
18
|
+
at: new Date().toISOString(),
|
|
19
|
+
}));
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The root route: the document, and the layout every page renders inside.
|
|
3
|
+
*
|
|
4
|
+
* `__root.tsx` is the root by name, and it is the one route that may declare a
|
|
5
|
+
* `shellComponent`. `<Outlet />` places the matched route.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import type { Child } from "@barqjs/core";
|
|
9
|
+
import { css, globalCss } from "@barqjs/css";
|
|
10
|
+
import { HeadContent, NavLink, Outlet, Scripts, createRootRoute } from "@barqjs/router";
|
|
11
|
+
|
|
12
|
+
// Compiled away. `css` returns a class name and the block becomes a rule in a
|
|
13
|
+
// stylesheet the build emits; nothing of the call survives into the bundle.
|
|
14
|
+
globalCss`
|
|
15
|
+
body { margin: 0; font-family: system-ui, sans-serif; line-height: 1.6 }
|
|
16
|
+
a { color: #2563eb; text-decoration: none }
|
|
17
|
+
a.active { font-weight: 600; text-decoration: underline }
|
|
18
|
+
`;
|
|
19
|
+
|
|
20
|
+
const layout = css`
|
|
21
|
+
max-width: 48rem;
|
|
22
|
+
margin: 0 auto;
|
|
23
|
+
padding: 2rem 1rem;
|
|
24
|
+
|
|
25
|
+
nav {
|
|
26
|
+
display: flex;
|
|
27
|
+
gap: 1rem;
|
|
28
|
+
padding-bottom: 1rem;
|
|
29
|
+
border-bottom: 1px solid #e5e7eb;
|
|
30
|
+
}
|
|
31
|
+
`;
|
|
32
|
+
|
|
33
|
+
// The whole document, and only a root route may declare one. `<HeadContent />`
|
|
34
|
+
// renders every matched route's merged `head` plus the framework's own tags;
|
|
35
|
+
// `<Scripts />` renders the client entry. There is no order to get right.
|
|
36
|
+
const shellComponent = (props: { children: Child }) => (
|
|
37
|
+
<html lang="en">
|
|
38
|
+
<head>
|
|
39
|
+
<meta charset="utf-8" />
|
|
40
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
41
|
+
<HeadContent />
|
|
42
|
+
</head>
|
|
43
|
+
<body>
|
|
44
|
+
<div id="app">{props.children}</div>
|
|
45
|
+
<Scripts />
|
|
46
|
+
</body>
|
|
47
|
+
</html>
|
|
48
|
+
);
|
|
49
|
+
|
|
50
|
+
// Merged with every route below this one, which replaces the identities it
|
|
51
|
+
// names and inherits the rest.
|
|
52
|
+
const head = {
|
|
53
|
+
meta: [
|
|
54
|
+
{ title: "barq" },
|
|
55
|
+
{ name: "description", content: "A barq application." },
|
|
56
|
+
],
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
function Layout() {
|
|
60
|
+
return (
|
|
61
|
+
<div class={layout}>
|
|
62
|
+
<nav>
|
|
63
|
+
<NavLink to="/" activeClass="active">
|
|
64
|
+
Home
|
|
65
|
+
</NavLink>{" "}
|
|
66
|
+
<NavLink to="/about" activeClass="active">
|
|
67
|
+
About
|
|
68
|
+
</NavLink>
|
|
69
|
+
</nav>
|
|
70
|
+
<main>
|
|
71
|
+
<Outlet />
|
|
72
|
+
</main>
|
|
73
|
+
</div>
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export const Route = createRootRoute({ shellComponent, head, component: Layout });
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `/about` — SERVER-RENDERED per request, because its loader calls a server
|
|
3
|
+
* function whose answer changes.
|
|
4
|
+
*
|
|
5
|
+
* Not prerendered, and the contrast with `/` is the point: a page whose content
|
|
6
|
+
* is fixed at build time is a file on disk, and a page whose content is not is a
|
|
7
|
+
* render.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { createFileRoute } from "@barqjs/router";
|
|
11
|
+
|
|
12
|
+
import { type Greeting, greeting } from "../data/greeting.ts";
|
|
13
|
+
|
|
14
|
+
function About() {
|
|
15
|
+
const data = Route.useLoaderData();
|
|
16
|
+
return (
|
|
17
|
+
<section>
|
|
18
|
+
<h1>About</h1>
|
|
19
|
+
<p>{() => data()?.message ?? "…"}</p>
|
|
20
|
+
<p>
|
|
21
|
+
rendered at <code>{() => data()?.at ?? "…"}</code>
|
|
22
|
+
</p>
|
|
23
|
+
</section>
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export const Route = createFileRoute<Greeting>("/about")({
|
|
28
|
+
loader: () => greeting(),
|
|
29
|
+
component: About,
|
|
30
|
+
head: {
|
|
31
|
+
meta: [{ title: "About — barq" }],
|
|
32
|
+
},
|
|
33
|
+
});
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `/api/health` — an API route, which is an ordinary route file that declares
|
|
3
|
+
* handlers instead of a component.
|
|
4
|
+
*
|
|
5
|
+
* There is no second route system and no second directory: this file is scanned
|
|
6
|
+
* and nested by the same generator as every page. The compiler strips `server`
|
|
7
|
+
* from the client build, so nothing here ships to the browser.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { createFileRoute } from "@barqjs/router";
|
|
11
|
+
import { setResponseHeader } from "@barqjs/start";
|
|
12
|
+
|
|
13
|
+
export const Route = createFileRoute("/api/health")({
|
|
14
|
+
server: {
|
|
15
|
+
handlers: {
|
|
16
|
+
GET: () => {
|
|
17
|
+
setResponseHeader("cache-control", "no-store");
|
|
18
|
+
return Response.json({ ok: true });
|
|
19
|
+
},
|
|
20
|
+
},
|
|
21
|
+
},
|
|
22
|
+
});
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `/` — PRERENDERED to a static file at build time, then hydrated.
|
|
3
|
+
*
|
|
4
|
+
* `prerender` is read off the route's OPTIONS by the generator and lands in
|
|
5
|
+
* `routeTree.gen.ts` as a literal, because a build has no runtime to ask.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { createSignal } from "@barqjs/core";
|
|
9
|
+
import { createFileRoute } from "@barqjs/router";
|
|
10
|
+
|
|
11
|
+
function Home() {
|
|
12
|
+
const [count, setCount] = createSignal(0);
|
|
13
|
+
return (
|
|
14
|
+
<section>
|
|
15
|
+
<h1>barq</h1>
|
|
16
|
+
<p>This page was written to disk at build time, and is now interactive.</p>
|
|
17
|
+
<button type="button" onClick={() => setCount((n) => n + 1)}>
|
|
18
|
+
clicked {count} times
|
|
19
|
+
</button>
|
|
20
|
+
</section>
|
|
21
|
+
);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export const Route = createFileRoute("/")({
|
|
25
|
+
prerender: true,
|
|
26
|
+
component: Home,
|
|
27
|
+
});
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"compilerOptions": {
|
|
3
|
+
"target": "ESNext",
|
|
4
|
+
"module": "ESNext",
|
|
5
|
+
"moduleResolution": "Bundler",
|
|
6
|
+
"strict": true,
|
|
7
|
+
"esModuleInterop": true,
|
|
8
|
+
"skipLibCheck": true,
|
|
9
|
+
"noEmit": true,
|
|
10
|
+
"lib": ["ESNext", "DOM", "DOM.Iterable"],
|
|
11
|
+
"types": ["@types/bun"],
|
|
12
|
+
"allowImportingTsExtensions": true,
|
|
13
|
+
"jsx": "react-jsx",
|
|
14
|
+
"jsxImportSource": "@barqjs/web"
|
|
15
|
+
},
|
|
16
|
+
"include": ["src/**/*", "vite.config.ts"],
|
|
17
|
+
"exclude": ["node_modules"]
|
|
18
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import barq from "@barqjs/vite";
|
|
2
|
+
import { defineConfig } from "vite";
|
|
3
|
+
|
|
4
|
+
export default defineConfig({
|
|
5
|
+
plugins: [
|
|
6
|
+
barq({
|
|
7
|
+
ssr: true,
|
|
8
|
+
start: {
|
|
9
|
+
// `/` is the seed. Everything else is found by crawling the links each
|
|
10
|
+
// rendered page produced, and kept only where the route declares
|
|
11
|
+
// `prerender`.
|
|
12
|
+
prerender: { routes: ["/"] },
|
|
13
|
+
// Fails the build when a route reaches a server function that does not
|
|
14
|
+
// carry that route's declared middleware.
|
|
15
|
+
verify: true,
|
|
16
|
+
},
|
|
17
|
+
}),
|
|
18
|
+
],
|
|
19
|
+
});
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Working in this project
|
|
2
|
+
|
|
3
|
+
This is a barq application: a JSX framework where a component function runs
|
|
4
|
+
once and only the DOM nodes that read a changed signal update. It is not React
|
|
5
|
+
and not Solid, so read the authoring skill before writing components.
|
|
6
|
+
|
|
7
|
+
## Skills
|
|
8
|
+
|
|
9
|
+
Installed with the packages, under `node_modules`:
|
|
10
|
+
|
|
11
|
+
- `node_modules/@barqjs/core/skills/barq/SKILL.md`: how to write barq (props
|
|
12
|
+
as values, signals, the two-function `createEffect`, stores, control flow,
|
|
13
|
+
async). Read it before writing or reviewing application code.
|
|
14
|
+
- `node_modules/@barqjs/core/skills/diagnostics/SKILL.md`: one section per
|
|
15
|
+
runtime `[CODE]`, with the repair.
|
|
16
|
+
- `node_modules/@barqjs/compiler/skills/compiler-diagnostics/SKILL.md`: one
|
|
17
|
+
section per build-time `BARQ0NN` code, with the repair.
|
|
18
|
+
- `node_modules/@barqjs/diagnostics/skills/agent-loops/SKILL.md`: capturing a
|
|
19
|
+
run as evidence for cost and responsiveness findings. Present when
|
|
20
|
+
`@barqjs/diagnostics` is installed.
|
|
21
|
+
|
|
22
|
+
## Rule
|
|
23
|
+
|
|
24
|
+
When a console or build message carries a `[CODE]` or a `BARQ0NN`, open the
|
|
25
|
+
skill section for that code before changing code. The console entry's `in`
|
|
26
|
+
line is the component path and its `at` line is `file:line:col`. Repair the
|
|
27
|
+
cause; a suppression comment or `untrack` leaves the defect in place.
|
|
28
|
+
|
|
29
|
+
## Commands
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm run dev # the Vite dev server, http://localhost:5173
|
|
33
|
+
npm run build # production build into dist
|
|
34
|
+
npm run preview # serve the build
|
|
35
|
+
npm run typecheck # tsc --noEmit
|
|
36
|
+
npm run check # barq check: the compiler's findings, no build needed
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Run `npm run check` and `npm run typecheck` after a change, and `npm run build`
|
|
40
|
+
before calling it done. `npx barq check --json` gives the findings as JSON, and
|
|
41
|
+
`npx barq check --fix` applies the repairs that are one spelling. Diagnostics print
|
|
42
|
+
in the browser console and the terminal of `npm run dev`.
|
|
43
|
+
|
|
44
|
+
## Layout
|
|
45
|
+
|
|
46
|
+
- `index.html`: the document.
|
|
47
|
+
- `src/main.tsx`: `render(() => <App />, root)`.
|
|
48
|
+
- `src/App.tsx`: the root component.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# barq, minimal
|
|
2
|
+
|
|
3
|
+
The compiler and signals, and nothing else. No router, no server.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install
|
|
7
|
+
npm run dev # http://localhost:5173
|
|
8
|
+
npm run build # dist
|
|
9
|
+
npm run preview
|
|
10
|
+
npm run typecheck
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
index.html the document
|
|
15
|
+
src/main.tsx render(() => <App />, root)
|
|
16
|
+
src/App.tsx a signal and a button
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`{count}` in JSX is a tracked read rather than a snapshot: the compiler wraps it,
|
|
20
|
+
and only that text node updates when the signal changes. The same wrapping is why
|
|
21
|
+
control-flow props take a plain expression, as in `<Show when={count() > 5}>`,
|
|
22
|
+
rather than a function.
|
|
23
|
+
|
|
24
|
+
Adding `@barqjs/router` and `@barqjs/start` later is not a rewrite, but starting
|
|
25
|
+
from the `full-stack` template is less work than retrofitting.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8" />
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
|
+
<title>barq</title>
|
|
7
|
+
</head>
|
|
8
|
+
<body>
|
|
9
|
+
<div id="app"></div>
|
|
10
|
+
<script type="module" src="/src/main.tsx"></script>
|
|
11
|
+
</body>
|
|
12
|
+
</html>
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "barq-project",
|
|
3
|
+
"private": true,
|
|
4
|
+
"type": "module",
|
|
5
|
+
"scripts": {
|
|
6
|
+
"dev": "vite",
|
|
7
|
+
"build": "vite build",
|
|
8
|
+
"preview": "vite preview",
|
|
9
|
+
"typecheck": "tsc --noEmit",
|
|
10
|
+
"check": "barq check src"
|
|
11
|
+
},
|
|
12
|
+
"dependencies": {
|
|
13
|
+
"@barqjs/core": "^0.2.0-next.1",
|
|
14
|
+
"@barqjs/css": "^0.2.0-next.1",
|
|
15
|
+
"@barqjs/web": "^0.2.0-next.1"
|
|
16
|
+
},
|
|
17
|
+
"devDependencies": {
|
|
18
|
+
"@barqjs/cli": "^0.2.0-next.1",
|
|
19
|
+
"@barqjs/vite": "^0.2.0-next.1",
|
|
20
|
+
"typescript": "^7.0.2",
|
|
21
|
+
"vite": "^8.3.8"
|
|
22
|
+
}
|
|
23
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { createSignal } from "@barqjs/core";
|
|
2
|
+
|
|
3
|
+
export function App() {
|
|
4
|
+
const [count, setCount] = createSignal(0);
|
|
5
|
+
// `{count}` is a tracked read, not a snapshot: the compiler wraps it, so only
|
|
6
|
+
// this text node updates when the signal changes.
|
|
7
|
+
return (
|
|
8
|
+
<main>
|
|
9
|
+
<h1>barq</h1>
|
|
10
|
+
<button type="button" onClick={() => setCount((n) => n + 1)}>
|
|
11
|
+
clicked {count} times
|
|
12
|
+
</button>
|
|
13
|
+
</main>
|
|
14
|
+
);
|
|
15
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"compilerOptions": {
|
|
3
|
+
"target": "ESNext",
|
|
4
|
+
"module": "ESNext",
|
|
5
|
+
"moduleResolution": "Bundler",
|
|
6
|
+
"strict": true,
|
|
7
|
+
"esModuleInterop": true,
|
|
8
|
+
"skipLibCheck": true,
|
|
9
|
+
"noEmit": true,
|
|
10
|
+
"lib": ["ESNext", "DOM", "DOM.Iterable"],
|
|
11
|
+
"allowImportingTsExtensions": true,
|
|
12
|
+
"jsx": "react-jsx",
|
|
13
|
+
"jsxImportSource": "@barqjs/web"
|
|
14
|
+
},
|
|
15
|
+
"include": ["src/**/*", "vite.config.ts"],
|
|
16
|
+
"exclude": ["node_modules"]
|
|
17
|
+
}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Working in this project
|
|
2
|
+
|
|
3
|
+
This is a barq application: a JSX framework where a component function runs
|
|
4
|
+
once and only the DOM nodes that read a changed signal update. It is not React
|
|
5
|
+
and not Solid, so read the authoring skill before writing components.
|
|
6
|
+
|
|
7
|
+
## Skills
|
|
8
|
+
|
|
9
|
+
Installed with the packages, under `node_modules`:
|
|
10
|
+
|
|
11
|
+
- `node_modules/@barqjs/core/skills/barq/SKILL.md`: how to write barq (props
|
|
12
|
+
as values, signals, the two-function `createEffect`, stores, control flow,
|
|
13
|
+
async). Read it before writing or reviewing application code.
|
|
14
|
+
- `node_modules/@barqjs/core/skills/diagnostics/SKILL.md`: one section per
|
|
15
|
+
runtime `[CODE]`, with the repair.
|
|
16
|
+
- `node_modules/@barqjs/compiler/skills/compiler-diagnostics/SKILL.md`: one
|
|
17
|
+
section per build-time `BARQ0NN` code, with the repair.
|
|
18
|
+
- `node_modules/@barqjs/diagnostics/skills/agent-loops/SKILL.md`: capturing a
|
|
19
|
+
run as evidence for cost and responsiveness findings. Present when
|
|
20
|
+
`@barqjs/diagnostics` is installed.
|
|
21
|
+
|
|
22
|
+
## Rule
|
|
23
|
+
|
|
24
|
+
When a console or build message carries a `[CODE]` or a `BARQ0NN`, open the
|
|
25
|
+
skill section for that code before changing code. The console entry's `in`
|
|
26
|
+
line is the component path and its `at` line is `file:line:col`. Repair the
|
|
27
|
+
cause; a suppression comment or `untrack` leaves the defect in place.
|
|
28
|
+
|
|
29
|
+
## Commands
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm run dev # the Vite dev server, http://localhost:5173
|
|
33
|
+
npm run build # production build into dist/client and dist/server
|
|
34
|
+
npm run preview # the built server, through vite preview
|
|
35
|
+
npm start # bun dist/server/serve.js
|
|
36
|
+
npm run typecheck # tsc --noEmit
|
|
37
|
+
npm run check # barq check: the compiler's findings, no build needed
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Run `npm run check` and `npm run typecheck` after a change, and `npm run build`
|
|
41
|
+
before calling it done. `npx barq check --json` gives the findings as JSON, and
|
|
42
|
+
`npx barq check --fix` applies the repairs that are one spelling. Diagnostics print
|
|
43
|
+
in the browser console, and server-side ones in the terminal of `npm run dev`.
|
|
44
|
+
|
|
45
|
+
## Layout
|
|
46
|
+
|
|
47
|
+
- `index.html`: the document.
|
|
48
|
+
- `src/main.tsx`: the client entry.
|
|
49
|
+
- `src/routes`: one file per route. `__root.tsx` is the layout.
|
|
50
|
+
- `src/data/greeting.ts`: a server function. A file that exports server
|
|
51
|
+
functions exports nothing else (`BARQ012`).
|
|
52
|
+
- `src/routeTree.gen.ts`: written by the build. Commit it, do not edit it.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# barq, SPA
|
|
2
|
+
|
|
3
|
+
Routing and rendering happen in the browser. `index.html` is the document, and
|
|
4
|
+
`vite build` bundles it like any other Vite app. Server functions still work:
|
|
5
|
+
they are real HTTP endpoints, and the built server answers them beside the
|
|
6
|
+
static files.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npm install
|
|
10
|
+
npm run dev # http://localhost:5173
|
|
11
|
+
npm run build # dist/client and dist/server
|
|
12
|
+
npm run preview # the built server, through vite preview
|
|
13
|
+
npm start # bun dist/server/serve.js
|
|
14
|
+
npm run typecheck
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## The files
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
index.html the document
|
|
21
|
+
src/main.tsx creates the router and renders it into #app
|
|
22
|
+
src/routes/__root.tsx the layout. No shellComponent: index.html is the document.
|
|
23
|
+
src/routes/index.tsx /
|
|
24
|
+
src/routes/about.tsx /about, whose loader calls a server function
|
|
25
|
+
src/data/greeting.ts that server function
|
|
26
|
+
src/routeTree.gen.ts written by the build. Commit it, do not edit it.
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`src/main.tsx` renders rather than hydrates, and awaits `router.start()` first
|
|
30
|
+
so the first frame draws the page that actually matched. `startClient()` from
|
|
31
|
+
`@barqjs/router/client` is the hydrating twin and belongs to an application
|
|
32
|
+
whose server renders the page.
|
|
33
|
+
|
|
34
|
+
`dist/server/serve.js` answers a path no route claims with `index.html`, so a
|
|
35
|
+
deep link works on a reload. A static host serving `dist/client` needs the same
|
|
36
|
+
fallback configured.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8" />
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
|
+
<title>barq</title>
|
|
7
|
+
</head>
|
|
8
|
+
<body>
|
|
9
|
+
<div id="app"></div>
|
|
10
|
+
<script type="module" src="/src/main.tsx"></script>
|
|
11
|
+
</body>
|
|
12
|
+
</html>
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "barq-project",
|
|
3
|
+
"private": true,
|
|
4
|
+
"type": "module",
|
|
5
|
+
"scripts": {
|
|
6
|
+
"dev": "vite",
|
|
7
|
+
"build": "vite build",
|
|
8
|
+
"preview": "vite preview",
|
|
9
|
+
"start": "bun dist/server/serve.js",
|
|
10
|
+
"typecheck": "tsc --noEmit",
|
|
11
|
+
"check": "barq check src"
|
|
12
|
+
},
|
|
13
|
+
"dependencies": {
|
|
14
|
+
"@barqjs/core": "^0.2.0-next.1",
|
|
15
|
+
"@barqjs/css": "^0.2.0-next.1",
|
|
16
|
+
"@barqjs/router": "^0.2.0-next.1",
|
|
17
|
+
"@barqjs/server": "^0.2.0-next.1",
|
|
18
|
+
"@barqjs/start": "^0.2.0-next.1",
|
|
19
|
+
"@barqjs/web": "^0.2.0-next.1"
|
|
20
|
+
},
|
|
21
|
+
"devDependencies": {
|
|
22
|
+
"@barqjs/cli": "^0.2.0-next.1",
|
|
23
|
+
"@barqjs/vite": "^0.2.0-next.1",
|
|
24
|
+
"@types/bun": "^1.4.4",
|
|
25
|
+
"typescript": "^7.0.2",
|
|
26
|
+
"vite": "^8.3.8"
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A server function: one HTTP endpoint, called like a function.
|
|
3
|
+
*
|
|
4
|
+
* The body never reaches the browser. The compiler replaces this module's
|
|
5
|
+
* exports with client stubs that call `/_barq/fn/<id>`, so anything it
|
|
6
|
+
* imports — a database driver, a secret — stays on the server.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { createServerFn } from "@barqjs/start";
|
|
10
|
+
|
|
11
|
+
export interface Greeting {
|
|
12
|
+
readonly message: string;
|
|
13
|
+
readonly at: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export const greeting = createServerFn().handler((): Greeting => ({
|
|
17
|
+
message: "Hello from the server.",
|
|
18
|
+
at: new Date().toISOString(),
|
|
19
|
+
}));
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The client boot. There is no server render, so this RENDERS rather than
|
|
3
|
+
* hydrates — `startClient()` from `@barqjs/router/client` is the hydrating
|
|
4
|
+
* twin, and it belongs to an application that server-renders its pages.
|
|
5
|
+
*
|
|
6
|
+
* `await router.start()` before the first render: the chain has to be decided
|
|
7
|
+
* before anything reads it, or the first frame renders a page nobody matched.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { render } from "@barqjs/web";
|
|
11
|
+
import { RouterProvider, browserHistory, createRouter } from "@barqjs/router";
|
|
12
|
+
|
|
13
|
+
import { routeTree } from "./routeTree.gen.ts";
|
|
14
|
+
|
|
15
|
+
const router = createRouter({ routeTree, history: browserHistory() });
|
|
16
|
+
await router.start();
|
|
17
|
+
|
|
18
|
+
const root = document.getElementById("app");
|
|
19
|
+
if (root === null) throw new Error("no #app in index.html");
|
|
20
|
+
|
|
21
|
+
render(() => <RouterProvider state={router} />, root);
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The root route: the layout every page renders inside.
|
|
3
|
+
*
|
|
4
|
+
* NO `shellComponent` and no `<HeadContent />`: `index.html` is the document
|
|
5
|
+
* here, and it is served as a file. Those belong to an application whose server
|
|
6
|
+
* renders the page.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { NavLink, Outlet, createRootRoute } from "@barqjs/router";
|
|
10
|
+
|
|
11
|
+
function Layout() {
|
|
12
|
+
return (
|
|
13
|
+
<div>
|
|
14
|
+
<nav>
|
|
15
|
+
<NavLink to="/" activeClass="active">
|
|
16
|
+
Home
|
|
17
|
+
</NavLink>{" "}
|
|
18
|
+
<NavLink to="/about" activeClass="active">
|
|
19
|
+
About
|
|
20
|
+
</NavLink>
|
|
21
|
+
</nav>
|
|
22
|
+
<main>
|
|
23
|
+
<Outlet />
|
|
24
|
+
</main>
|
|
25
|
+
</div>
|
|
26
|
+
);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export const Route = createRootRoute({ component: Layout });
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The loader calls a SERVER function, which in an SPA is a real HTTP round trip
|
|
3
|
+
* to `/_barq/fn/<id>`. Nothing about the call site says so, which is the point.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { Loading } from "@barqjs/core";
|
|
7
|
+
import { createFileRoute } from "@barqjs/router";
|
|
8
|
+
|
|
9
|
+
import { type Greeting, greeting } from "../data/greeting.ts";
|
|
10
|
+
|
|
11
|
+
function About() {
|
|
12
|
+
const data = Route.useLoaderData();
|
|
13
|
+
return (
|
|
14
|
+
<section>
|
|
15
|
+
<h1>About</h1>
|
|
16
|
+
<Loading fallback={<p>loading…</p>}>
|
|
17
|
+
<p>{() => data()?.message}</p>
|
|
18
|
+
<p>
|
|
19
|
+
answered at <code>{() => data()?.at}</code>
|
|
20
|
+
</p>
|
|
21
|
+
</Loading>
|
|
22
|
+
</section>
|
|
23
|
+
);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export const Route = createFileRoute<Greeting>("/about")({
|
|
27
|
+
loader: () => greeting(),
|
|
28
|
+
component: About,
|
|
29
|
+
});
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { createSignal } from "@barqjs/core";
|
|
2
|
+
import { createFileRoute } from "@barqjs/router";
|
|
3
|
+
|
|
4
|
+
function Home() {
|
|
5
|
+
const [count, setCount] = createSignal(0);
|
|
6
|
+
return (
|
|
7
|
+
<section>
|
|
8
|
+
<h1>barq</h1>
|
|
9
|
+
<button type="button" onClick={() => setCount((n) => n + 1)}>
|
|
10
|
+
clicked {count} times
|
|
11
|
+
</button>
|
|
12
|
+
</section>
|
|
13
|
+
);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export const Route = createFileRoute("/")({ component: Home });
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"compilerOptions": {
|
|
3
|
+
"target": "ESNext",
|
|
4
|
+
"module": "ESNext",
|
|
5
|
+
"moduleResolution": "Bundler",
|
|
6
|
+
"strict": true,
|
|
7
|
+
"esModuleInterop": true,
|
|
8
|
+
"skipLibCheck": true,
|
|
9
|
+
"noEmit": true,
|
|
10
|
+
"lib": ["ESNext", "DOM", "DOM.Iterable"],
|
|
11
|
+
"types": ["@types/bun"],
|
|
12
|
+
"allowImportingTsExtensions": true,
|
|
13
|
+
"jsx": "react-jsx",
|
|
14
|
+
"jsxImportSource": "@barqjs/web"
|
|
15
|
+
},
|
|
16
|
+
"include": ["src/**/*", "vite.config.ts"],
|
|
17
|
+
"exclude": ["node_modules"]
|
|
18
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import barq from "@barqjs/vite";
|
|
2
|
+
import { defineConfig } from "vite";
|
|
3
|
+
|
|
4
|
+
export default defineConfig({
|
|
5
|
+
// No `ssr`: `index.html` is the document and the router renders into it in
|
|
6
|
+
// the browser. `start` keeps the server functions and the API routes.
|
|
7
|
+
plugins: [barq({ start: true })],
|
|
8
|
+
});
|