create-barq 0.0.0-stage → 0.2.0-next.0

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 (33) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +72 -2
  3. package/dist/index.js +204 -0
  4. package/package.json +46 -4
  5. package/templates/full-stack/README.md +45 -0
  6. package/templates/full-stack/_gitignore +7 -0
  7. package/templates/full-stack/package.json +26 -0
  8. package/templates/full-stack/src/data/greeting.ts +19 -0
  9. package/templates/full-stack/src/routes/__root.tsx +77 -0
  10. package/templates/full-stack/src/routes/about.tsx +33 -0
  11. package/templates/full-stack/src/routes/api/health.ts +22 -0
  12. package/templates/full-stack/src/routes/index.tsx +27 -0
  13. package/templates/full-stack/tsconfig.json +18 -0
  14. package/templates/full-stack/vite.config.ts +19 -0
  15. package/templates/minimal/README.md +25 -0
  16. package/templates/minimal/_gitignore +6 -0
  17. package/templates/minimal/index.html +12 -0
  18. package/templates/minimal/package.json +21 -0
  19. package/templates/minimal/src/App.tsx +15 -0
  20. package/templates/minimal/src/main.tsx +8 -0
  21. package/templates/minimal/tsconfig.json +17 -0
  22. package/templates/minimal/vite.config.ts +6 -0
  23. package/templates/spa/README.md +36 -0
  24. package/templates/spa/_gitignore +6 -0
  25. package/templates/spa/index.html +12 -0
  26. package/templates/spa/package.json +26 -0
  27. package/templates/spa/src/data/greeting.ts +19 -0
  28. package/templates/spa/src/main.tsx +21 -0
  29. package/templates/spa/src/routes/__root.tsx +29 -0
  30. package/templates/spa/src/routes/about.tsx +29 -0
  31. package/templates/spa/src/routes/index.tsx +16 -0
  32. package/templates/spa/tsconfig.json +18 -0
  33. 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
- # Temporary Holding Version
1
+ # create-barq
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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,204 @@
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
+ //#region 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
+ //#endregion
64
+ //#region src/templates.ts
65
+ const TEMPLATES = [
66
+ {
67
+ name: "full-stack",
68
+ title: "Full-stack",
69
+ description: "Server-rendered pages, API routes, server functions, prerendering.",
70
+ spa: false,
71
+ prerenders: true,
72
+ server: true,
73
+ clientOut: "dist/client"
74
+ },
75
+ {
76
+ name: "spa",
77
+ title: "SPA",
78
+ description: "Client-rendered routing with server functions. The document is index.html.",
79
+ spa: true,
80
+ prerenders: false,
81
+ server: true,
82
+ clientOut: "dist/client"
83
+ },
84
+ {
85
+ name: "minimal",
86
+ title: "Minimal",
87
+ description: "The compiler and signals, no router. One page, one mount.",
88
+ spa: true,
89
+ prerenders: false,
90
+ server: false,
91
+ clientOut: "dist"
92
+ }
93
+ ];
94
+ const DEFAULT_TEMPLATE = "full-stack";
95
+ function findTemplate(name) {
96
+ return TEMPLATES.find((template) => template.name === name);
97
+ }
98
+ //#endregion
99
+ //#region src/index.ts
100
+ /**
101
+ * `bun create barq my-app` / `npm create barq@latest my-app`.
102
+ *
103
+ * NO DEPENDENCIES. A `create-*` package is downloaded before the project it
104
+ * scaffolds exists, so every dependency is latency a person pays before seeing
105
+ * anything — the argument parsing and the two prompts here are smaller than the
106
+ * libraries that would do them.
107
+ *
108
+ * It scaffolds a project and stops. Route generators (`barq add route /posts/$id`)
109
+ * are the obvious next thing and are deliberately not here: the route tree is
110
+ * already generated by the Vite plugin, so the CLI's only job today is the one
111
+ * a person cannot do by copying a directory.
112
+ */
113
+ const HELP = `\
114
+ Usage: create-barq [directory] [options]
115
+
116
+ Create a barq project.
117
+
118
+ Options:
119
+ -t, --template NAME ${TEMPLATES.map((t) => t.name).join(" | ")}
120
+ --overwrite empty the directory first
121
+ -h, --help show this
122
+
123
+ Templates:
124
+ ${TEMPLATES.map((t) => ` ${t.name.padEnd(12)}${t.description}`).join("\n")}
125
+ `;
126
+ function parse(argv) {
127
+ let directory;
128
+ let template;
129
+ let overwrite = false;
130
+ let help = false;
131
+ for (let i = 0; i < argv.length; i++) {
132
+ const arg = argv[i] ?? "";
133
+ if (arg === "-h" || arg === "--help") help = true;
134
+ else if (arg === "--overwrite") overwrite = true;
135
+ else if (arg === "-t" || arg === "--template") template = argv[++i];
136
+ else if (arg.startsWith("--template=")) template = arg.slice(11);
137
+ else if (arg.startsWith("-")) throw new Error(`unknown option ${arg}`);
138
+ else directory ??= arg;
139
+ }
140
+ return {
141
+ directory,
142
+ template,
143
+ overwrite,
144
+ help
145
+ };
146
+ }
147
+ /** What ran us, for the "now run" lines. `npm_config_user_agent` is set by all of them. */
148
+ function packageManager() {
149
+ const name = process.env.npm_config_user_agent?.split(" ")[0]?.split("/")[0];
150
+ return name === void 0 || name === "" ? "npm" : name;
151
+ }
152
+ async function main() {
153
+ const args = parse(process.argv.slice(2));
154
+ if (args.help) {
155
+ stdout.write(HELP);
156
+ return;
157
+ }
158
+ const rl = stdin.isTTY ? createInterface({
159
+ input: stdin,
160
+ output: stdout
161
+ }) : null;
162
+ const ask = async (question, fallback) => {
163
+ if (rl === null) return fallback;
164
+ const answer = (await rl.question(`${question} (${fallback}) `)).trim();
165
+ return answer === "" ? fallback : answer;
166
+ };
167
+ try {
168
+ const directory = args.directory ?? await ask("Project directory:", "barq-project");
169
+ const target = resolve(process.cwd(), directory);
170
+ const name = args.template ?? await askTemplate(ask);
171
+ const template = findTemplate(name);
172
+ if (template === void 0) throw new Error(`no template named "${name}". Try one of: ${TEMPLATES.map((t) => t.name).join(", ")}`);
173
+ let overwrite = args.overwrite;
174
+ if (!overwrite && !isEmpty(target)) {
175
+ overwrite = (await ask(`${directory} is not empty. Empty it?`, "no")).toLowerCase().startsWith("y");
176
+ if (!overwrite) throw new Error(`${directory} is not empty`);
177
+ }
178
+ const suggested = toValidPackageName(basename(target));
179
+ const packageName = isValidPackageName(suggested) ? suggested : "barq-project";
180
+ scaffold({
181
+ template: template.name,
182
+ target,
183
+ packageName,
184
+ overwrite
185
+ });
186
+ const pm = packageManager();
187
+ const install = pm === "npm" ? "npm install" : `${pm} install`;
188
+ const dev = pm === "npm" ? "npm run dev" : `${pm} run dev`;
189
+ stdout.write(`\nScaffolded ${template.title} in ${directory}.\n\n cd ${directory}\n ${install}\n ${dev}\n\n`);
190
+ } finally {
191
+ rl?.close();
192
+ }
193
+ }
194
+ async function askTemplate(ask) {
195
+ stdout.write("\nTemplates:\n");
196
+ for (const template of TEMPLATES) stdout.write(` ${template.name.padEnd(12)}${template.description}\n`);
197
+ return ask("\nTemplate:", DEFAULT_TEMPLATE);
198
+ }
199
+ main().catch((error) => {
200
+ stdout.write(`\n${error instanceof Error ? error.message : String(error)}\n`);
201
+ process.exitCode = 1;
202
+ });
203
+ //#endregion
204
+ export {};
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "create-barq",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0-next.0",
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.3",
38
+ "typescript": "^7.0.2",
39
+ "vite": "^8.3.4"
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,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,7 @@
1
+ node_modules/
2
+ dist/
3
+ .barq/
4
+ *.tsbuildinfo
5
+ .env
6
+ .env.*.local
7
+ .DS_Store
@@ -0,0 +1,26 @@
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
+ },
12
+ "dependencies": {
13
+ "@barqjs/core": "^0.2.0-next.0",
14
+ "@barqjs/css": "^0.2.0-next.0",
15
+ "@barqjs/router": "^0.2.0-next.0",
16
+ "@barqjs/server": "^0.2.0-next.0",
17
+ "@barqjs/start": "^0.2.0-next.0",
18
+ "@barqjs/web": "^0.2.0-next.0"
19
+ },
20
+ "devDependencies": {
21
+ "@barqjs/vite": "^0.2.0-next.0",
22
+ "@types/bun": "^1.4.3",
23
+ "typescript": "^7.0.2",
24
+ "vite": "^8.3.4"
25
+ }
26
+ }
@@ -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,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,6 @@
1
+ node_modules/
2
+ dist/
3
+ *.tsbuildinfo
4
+ .env
5
+ .env.*.local
6
+ .DS_Store
@@ -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,21 @@
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
+ },
11
+ "dependencies": {
12
+ "@barqjs/core": "^0.2.0-next.0",
13
+ "@barqjs/css": "^0.2.0-next.0",
14
+ "@barqjs/web": "^0.2.0-next.0"
15
+ },
16
+ "devDependencies": {
17
+ "@barqjs/vite": "^0.2.0-next.0",
18
+ "typescript": "^7.0.2",
19
+ "vite": "^8.3.4"
20
+ }
21
+ }
@@ -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,8 @@
1
+ import { render } from "@barqjs/web";
2
+
3
+ import { App } from "./App.tsx";
4
+
5
+ const root = document.getElementById("app");
6
+ if (root === null) throw new Error("no #app in index.html");
7
+
8
+ render(() => <App />, root);
@@ -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,6 @@
1
+ import barq from "@barqjs/vite";
2
+ import { defineConfig } from "vite";
3
+
4
+ export default defineConfig({
5
+ plugins: [barq()],
6
+ });
@@ -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,6 @@
1
+ node_modules/
2
+ dist/
3
+ *.tsbuildinfo
4
+ .env
5
+ .env.*.local
6
+ .DS_Store
@@ -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,26 @@
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
+ },
12
+ "dependencies": {
13
+ "@barqjs/core": "^0.2.0-next.0",
14
+ "@barqjs/css": "^0.2.0-next.0",
15
+ "@barqjs/router": "^0.2.0-next.0",
16
+ "@barqjs/server": "^0.2.0-next.0",
17
+ "@barqjs/start": "^0.2.0-next.0",
18
+ "@barqjs/web": "^0.2.0-next.0"
19
+ },
20
+ "devDependencies": {
21
+ "@barqjs/vite": "^0.2.0-next.0",
22
+ "@types/bun": "^1.4.3",
23
+ "typescript": "^7.0.2",
24
+ "vite": "^8.3.4"
25
+ }
26
+ }
@@ -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
+ });