create-guren-app 1.20.1 → 1.20.3

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/dist/cli.js CHANGED
@@ -1474,6 +1474,46 @@ async function applyTokenTransforms(destination, files, tokens) {
1474
1474
  if (updated !== content) await writeFile(path, updated, "utf8");
1475
1475
  }
1476
1476
  }
1477
+ const DATABASE_LABELS = {
1478
+ sqlite: "SQLite",
1479
+ postgres: "PostgreSQL",
1480
+ mysql: "MySQL"
1481
+ };
1482
+ const README_BLOCK = /^<!-- (\/?)guren:([a-z-]+) -->$/u;
1483
+ const README_BLOCK_LIKE = /<!--\s*\/?guren:/u;
1484
+ /**
1485
+ * Keeps or drops each `<!-- guren:<name> -->` … `<!-- /guren:<name> -->` line
1486
+ * block of a template README, so one README covers every rendering mode and
1487
+ * driver. A malformed, unknown, nested or unclosed marker throws.
1488
+ */
1489
+ function renderReadmeBlocks(content, blocks) {
1490
+ const kept = [];
1491
+ let open = null;
1492
+ for (const line of content.split("\n")) {
1493
+ const marker = README_BLOCK.exec(line);
1494
+ if (!marker) {
1495
+ if (README_BLOCK_LIKE.test(line)) throw new Error(`README line "${line}" looks like a block marker but is not one; write \`<!-- guren:<name> -->\` on its own line.`);
1496
+ if (open === null || blocks[open]) kept.push(line);
1497
+ continue;
1498
+ }
1499
+ const [, closing, name] = marker;
1500
+ if (!Object.hasOwn(blocks, name)) throw new Error(`README marker "${line}" names no known block (${Object.keys(blocks).join(", ")}).`);
1501
+ if (closing ? open !== name : open !== null) throw new Error(`README marker "${line}" does not match the open block (${open ?? "none"}).`);
1502
+ open = closing ? null : name;
1503
+ }
1504
+ if (open !== null) throw new Error(`README block "${open}" is never closed.`);
1505
+ return kept.join("\n");
1506
+ }
1507
+ async function renderReadme(destination, renderingMode, database) {
1508
+ const path = join(destination, "README.md");
1509
+ const content = await readFile(path, "utf8");
1510
+ const container = usesDatabaseContainer(database);
1511
+ await writeFile(path, renderReadmeBlocks(content, {
1512
+ ssr: renderingMode === "ssr",
1513
+ container,
1514
+ "no-container": !container
1515
+ }), "utf8");
1516
+ }
1477
1517
  async function scaffoldEnvFiles(destination) {
1478
1518
  const envExamplePath = join(destination, ".env.example");
1479
1519
  const envPath = join(destination, ".env");
@@ -1684,11 +1724,13 @@ async function scaffoldAppBlueprint(options) {
1684
1724
  const tokenMap = /* @__PURE__ */ new Map([
1685
1725
  ["guren-app-placeholder", packageName],
1686
1726
  ["__APP_TITLE__", appTitle],
1687
- ["__APP_NAME__", appName]
1727
+ ["__APP_NAME__", appName],
1728
+ ["__DATABASE_LABEL__", DATABASE_LABELS[options.database]]
1688
1729
  ]);
1689
1730
  await assertBlueprintLayersExist(blueprint, options.renderingMode);
1690
1731
  for (const layer of listBlueprintTemplates(blueprint, options.renderingMode)) await copyLayer(layer, options.destination);
1691
1732
  await applyTokenTransforms(options.destination, blueprint.transformFiles, tokenMap);
1733
+ await renderReadme(options.destination, options.renderingMode, options.database);
1692
1734
  await scaffoldEnvFiles(options.destination);
1693
1735
  await applyDatabaseConfig(options.destination, options.database);
1694
1736
  await blueprint.postScaffold?.(context);
@@ -1930,6 +1972,25 @@ async function installDependencies(cwd) {
1930
1972
  return false;
1931
1973
  }
1932
1974
  }
1975
+ /**
1976
+ * The shipped `.guren/*.gen.ts` match the bare template only: `add auth` and
1977
+ * `add prototype` add pages and routes they do not list, and both the initial
1978
+ * commit and a boot before `bun run dev` read them. Under `--no-install` no
1979
+ * generator runs, so the shipped files still hold.
1980
+ */
1981
+ async function runCodegen(cwd) {
1982
+ consola.start("Generating route and page types...");
1983
+ const { spawnSync } = await import("node:child_process");
1984
+ if (spawnSync("bun", ["run", "codegen"], {
1985
+ cwd,
1986
+ stdio: "inherit"
1987
+ }).status !== 0) {
1988
+ consola.warn("`bun run codegen` failed (see the output above), so .guren/ may not match the app. Run it inside the app once that is fixed.");
1989
+ return false;
1990
+ }
1991
+ consola.success("Generated route and page types");
1992
+ return true;
1993
+ }
1933
1994
  runMain(defineCommand({
1934
1995
  meta: {
1935
1996
  name: "create-guren-app",
@@ -2050,6 +2111,9 @@ runMain(defineCommand({
2050
2111
  }
2051
2112
  if (!authInstalled) consola.warn(installed ? "Authentication scaffolding failed (see the output above). Run `bunx guren add auth` inside the app once that is fixed." : "Authentication was not scaffolded automatically. Run `bunx guren add auth` inside the app after installing dependencies.");
2052
2113
  }
2114
+ const authFailed = includeAuth && !authInstalled;
2115
+ if (installed && authFailed) consola.info("Skipping codegen until authentication is scaffolded; run `bun run codegen` after `bunx guren add auth`.");
2116
+ const codegenRan = installed && !authFailed && await runCodegen(targetDir);
2053
2117
  if (shouldInitGit) reportGitInit(targetDir);
2054
2118
  const relativeTarget = relative(g$1.cwd(), targetDir) || ".";
2055
2119
  consola.success(`Scaffolded a new Guren app (${blueprint.name}/${renderingMode.toUpperCase()}/${database}) in ${relativeTarget}`);
@@ -2066,8 +2130,8 @@ runMain(defineCommand({
2066
2130
  consola.log(` bunx guren add resource ${example.name} --fields "${example.fields}"`);
2067
2131
  }
2068
2132
  consola.log("");
2069
- consola.info("Generate types and set up database:");
2070
- consola.log(" bun run codegen");
2133
+ consola.info(codegenRan ? "Set up the database:" : "Generate types and set up database:");
2134
+ if (!codegenRan) consola.log(" bun run codegen");
2071
2135
  consola.log(" bun run db:make");
2072
2136
  consola.log(" bun run db:migrate");
2073
2137
  consola.log(" bun run db:seed");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-guren-app",
3
- "version": "1.20.1",
3
+ "version": "1.20.3",
4
4
  "description": "Scaffold a Guren app: a Bun-first fullstack TypeScript framework with Laravel-style conventions, Inertia.js + React, Drizzle ORM, and an agent harness for Claude Code and other coding agents.",
5
5
  "keywords": [
6
6
  "guren",
@@ -1,16 +1,25 @@
1
1
  # __APP_NAME__
2
2
 
3
- API-only application built with [Guren](https://github.com/user/guren).
3
+ API-only application built with [Guren](https://guren.dev).
4
4
 
5
5
  ## Getting Started
6
6
 
7
7
  ```bash
8
8
  bun install
9
- bun run db:migrate
9
+ <!-- guren:container -->
10
+ bun run db:up # start the __DATABASE_LABEL__ container
11
+ <!-- /guren:container -->
12
+ bun run db:make # generate a migration from db/schema.ts
13
+ bun run db:migrate # apply it
10
14
  bun run dev
11
15
  ```
12
16
 
13
- If you scaffolded with PostgreSQL or MySQL, this project also has a `docker-compose.yml` and `bun run db:up` / `bun run db:down` to start and stop the database container. Start it before `bun run db:migrate`.
17
+ <!-- guren:container -->
18
+ __DATABASE_LABEL__ runs in the container `docker-compose.yml` defines, and `DATABASE_URL` in `.env` points at it. `bun run db:down` stops it.
19
+ <!-- /guren:container -->
20
+ <!-- guren:no-container -->
21
+ No Docker and no database server: SQLite keeps the database in the file `DATABASE_URL` names in `.env`.
22
+ <!-- /guren:no-container -->
14
23
 
15
24
  ## API Endpoints
16
25
 
@@ -5,7 +5,7 @@
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "dev": "bun run codegen && GUREN_MCP=1 GUREN_DOCS=1 bun run dev:server",
8
- "dev:server": "bun --hot bin/serve.ts",
8
+ "dev:server": "NODE_ENV=development bun --hot bin/serve.ts",
9
9
  "start": "NODE_ENV=production bun bin/serve.ts",
10
10
  "console": "bun bin/console.ts",
11
11
  "codegen": "bunx guren codegen --routes routes/api.ts --force",
@@ -21,13 +21,14 @@
21
21
  "test": "bun test"
22
22
  },
23
23
  "dependencies": {
24
- "@guren/cli": "^2.34.0",
25
- "@guren/core": "^1.25.0",
24
+ "@guren/cli": "^2.35.1",
25
+ "@guren/core": "^1.26.0",
26
26
  "@guren/orm": "^2.15.0",
27
- "drizzle-orm": "1.0.0-rc.4"
27
+ "drizzle-orm": "1.0.0-rc.4",
28
+ "zod": "^4.5.0"
28
29
  },
29
30
  "devDependencies": {
30
- "@guren/testing": "^1.14.2",
31
+ "@guren/testing": "^1.14.3",
31
32
  "bun-types": "^1.3.1",
32
33
  "drizzle-kit": "1.0.0-rc.4",
33
34
  "oxlint": "~1.81.0",
@@ -7,18 +7,25 @@ and a seeded demo account, ready to run.
7
7
 
8
8
  ```bash
9
9
  bun install
10
+ <!-- guren:container -->
11
+ bun run db:up # start the __DATABASE_LABEL__ container
12
+ <!-- /guren:container -->
10
13
  bun run db:make # generate the first migration from db/schema.ts
11
14
  bun run db:migrate
12
15
  bun run db:seed # demo@example.com / secret, plus two sample posts
13
16
  bun run dev
14
17
  ```
15
18
 
19
+ <!-- guren:container -->
20
+ __DATABASE_LABEL__ runs in the container `docker-compose.yml` defines, and `DATABASE_URL` in `.env` points at it. `bun run db:down` stops it.
21
+ <!-- /guren:container -->
22
+ <!-- guren:no-container -->
23
+ No Docker and no database server: SQLite keeps the database in the file `DATABASE_URL` names in `.env`.
24
+ <!-- /guren:no-container -->
25
+
16
26
  Visit `http://localhost:3333`, then sign in as `demo@example.com` with the
17
27
  password `secret` and publish a post from `/posts/create`.
18
28
 
19
- If you scaffolded with PostgreSQL or MySQL, run `bun run db:up` first to start
20
- the database container.
21
-
22
29
  ## What's Included
23
30
 
24
31
  - `/` — landing page with the latest posts
@@ -70,6 +77,31 @@ bunx guren add broadcasting # realtime channels
70
77
  bunx guren add schedule # task scheduling
71
78
  ```
72
79
 
80
+ <!-- guren:ssr -->
81
+ ## Server-Side Rendering
82
+
83
+ Pages render on the server through Inertia SSR. During development the Bun server reads `resources/js/ssr.tsx` directly. Production builds use the SSR bundle and manifest Vite generates, which `src/main.ts` wires up through `autoConfigureInertiaAssets`.
84
+
85
+ `bun run build` runs `vite build` for the client and `vite build --ssr` for the server bundle, so the first request is answered with pre-rendered HTML. `bun run preview` then starts the same Bun server in production mode against those manifests.
86
+
87
+ ### Deploy to Vercel
88
+
89
+ Vercel support is an opt-in plugin for SSR apps:
90
+
91
+ ```bash
92
+ bunx guren plugin @guren/plugin-vercel
93
+ bun add @guren/plugin-vercel
94
+ bun run vercel:build
95
+ ```
96
+
97
+ Then deploy with Vercel's prebuilt flow:
98
+
99
+ ```bash
100
+ vercel build
101
+ vercel deploy --prebuilt
102
+ ```
103
+
104
+ <!-- /guren:ssr -->
73
105
  ## Favicon
74
106
 
75
107
  `public/favicon.svg` ships as a placeholder and is linked from `src/app.ts` via
@@ -89,6 +121,10 @@ deployments (AWS Lambda, for example) serve them from a CDN instead.
89
121
  | `bun run build` | Build for production |
90
122
  | `bun run preview` | Start the built app with the Bun production server |
91
123
  | `bun run start` | Start the app in production mode (`NODE_ENV=production`); what a deployment runs |
124
+ <!-- guren:container -->
125
+ | `bun run db:up` | Start the __DATABASE_LABEL__ container |
126
+ | `bun run db:down` | Stop the __DATABASE_LABEL__ container |
127
+ <!-- /guren:container -->
92
128
  | `bun run db:make` | Generate a migration from `db/schema.ts` |
93
129
  | `bun run db:migrate` | Run database migrations |
94
130
  | `bun run db:seed` | Seed the database |
@@ -32,7 +32,7 @@ export default function Login({ email = '', errors = {} }: Props) {
32
32
  <Alert tone="danger" className="mt-4">{errors.message}</Alert>
33
33
  )}
34
34
 
35
- <form className="mt-6 space-y-4" onSubmit={form.handleSubmit}>
35
+ <form method="post" action={loginStoreForm.path} className="mt-6 space-y-4" onSubmit={form.handleSubmit}>
36
36
  <Field form={form} name="email" />
37
37
  <Field form={form} name="password" as="password" />
38
38
  <Field form={form} name="remember" label="Remember me" />
@@ -43,7 +43,7 @@ export default function Login({ email = '', errors = {} }: Props) {
43
43
 
44
44
  <p className="mt-6 text-center text-sm text-g-text-2">
45
45
  Don&apos;t have an account?{' '}
46
- <Link href="/register" className="text-g-accent-text transition hover:underline">
46
+ <Link href="/register" className="text-g-accent-text underline underline-offset-2 transition hover:no-underline">
47
47
  Sign up
48
48
  </Link>
49
49
  </p>
@@ -30,7 +30,7 @@ export default function Register({ errors = {} }: Props) {
30
30
  <Alert tone="danger" className="mt-4">{errors.message}</Alert>
31
31
  )}
32
32
 
33
- <form className="mt-6 space-y-4" onSubmit={form.handleSubmit}>
33
+ <form method="post" action={registerStoreForm.path} className="mt-6 space-y-4" onSubmit={form.handleSubmit}>
34
34
  <Field form={form} name="name" />
35
35
  <Field form={form} name="email" />
36
36
  <Field form={form} name="password" as="password" />
@@ -42,7 +42,7 @@ export default function Register({ errors = {} }: Props) {
42
42
 
43
43
  <p className="mt-6 text-center text-sm text-g-text-2">
44
44
  Already have an account?{' '}
45
- <Link href="/login" className="text-g-accent-text transition hover:underline">
45
+ <Link href="/login" className="text-g-accent-text underline underline-offset-2 transition hover:no-underline">
46
46
  Sign in
47
47
  </Link>
48
48
  </p>
@@ -1,3 +1,4 @@
1
+ import { Head } from '@inertiajs/react'
1
2
  import Layout from '../../components/Layout.js'
2
3
  import { Alert } from '@/resources/js/components/ui/Alert'
3
4
 
@@ -8,6 +9,7 @@ interface Props {
8
9
  export default function Dashboard({ user }: Props) {
9
10
  return (
10
11
  <Layout>
12
+ <Head title="Dashboard" />
11
13
  <section className="space-y-6">
12
14
  <header>
13
15
  <h1 className="flex items-center gap-3 text-3xl font-bold text-g-heading">
@@ -2,6 +2,9 @@ import { Head, useForm } from '@inertiajs/react'
2
2
  import { useId } from 'react'
3
3
  import type { ApiRoutes } from '@/.guren/api-client.gen'
4
4
  import { route } from '@/.guren/routes.gen'
5
+ import { Input } from '@/resources/js/components/ui/Input'
6
+ import { Label } from '@/resources/js/components/ui/Label'
7
+ import { Textarea } from '@/resources/js/components/ui/Textarea'
5
8
  import Layout from '../../components/Layout.js'
6
9
 
7
10
  type PostFormData = ApiRoutes['posts.store']['body']
@@ -10,9 +13,6 @@ interface Props {
10
13
  post: PostFormData & { id: number }
11
14
  }
12
15
 
13
- const fieldClass =
14
- 'mt-1 w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none placeholder:text-g-muted focus:border-transparent focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent'
15
-
16
16
  export default function EditPost({ post }: Props) {
17
17
  const form = useForm<PostFormData>({
18
18
  title: post.title,
@@ -34,6 +34,8 @@ export default function EditPost({ post }: Props) {
34
34
  </h1>
35
35
 
36
36
  <form
37
+ method="post"
38
+ action={route('posts.update', { id: post.id })}
37
39
  className="space-y-4"
38
40
  onSubmit={(event) => {
39
41
  event.preventDefault()
@@ -41,43 +43,37 @@ export default function EditPost({ post }: Props) {
41
43
  }}
42
44
  >
43
45
  <div>
44
- <label htmlFor={titleId} className="block text-sm font-bold text-g-heading">
45
- Title
46
- </label>
47
- <input
46
+ <Label htmlFor={titleId}>Title</Label>
47
+ <Input
48
48
  id={titleId}
49
49
  type="text"
50
50
  value={form.data.title}
51
51
  onChange={(event) => form.setData('title', event.target.value)}
52
- className={fieldClass}
52
+ className="mt-1"
53
53
  />
54
54
  {form.errors.title ? <p className="mt-1 text-sm text-g-danger">{form.errors.title}</p> : null}
55
55
  </div>
56
56
 
57
57
  <div>
58
- <label htmlFor={excerptId} className="block text-sm font-bold text-g-heading">
59
- Excerpt
60
- </label>
61
- <input
58
+ <Label htmlFor={excerptId}>Excerpt</Label>
59
+ <Input
62
60
  id={excerptId}
63
61
  type="text"
64
62
  value={form.data.excerpt}
65
63
  onChange={(event) => form.setData('excerpt', event.target.value)}
66
- className={fieldClass}
64
+ className="mt-1"
67
65
  />
68
66
  {form.errors.excerpt ? <p className="mt-1 text-sm text-g-danger">{form.errors.excerpt}</p> : null}
69
67
  </div>
70
68
 
71
69
  <div>
72
- <label htmlFor={bodyId} className="block text-sm font-bold text-g-heading">
73
- Body
74
- </label>
75
- <textarea
70
+ <Label htmlFor={bodyId}>Body</Label>
71
+ <Textarea
76
72
  id={bodyId}
77
73
  rows={10}
78
74
  value={form.data.body}
79
75
  onChange={(event) => form.setData('body', event.target.value)}
80
- className={fieldClass}
76
+ className="mt-1"
81
77
  />
82
78
  {form.errors.body ? <p className="mt-1 text-sm text-g-danger">{form.errors.body}</p> : null}
83
79
  </div>
@@ -4,6 +4,7 @@ import type { PaginatedPageProps } from '@guren/core'
4
4
  import type { PostResourceData } from '@/app/Http/Resources/PostResource'
5
5
  import { route } from '@/.guren/routes.gen'
6
6
  import { createApiClient, type ApiRoutes } from '@/.guren/api-client.gen'
7
+ import { Input } from '@/resources/js/components/ui/Input'
7
8
  import Layout from '../../components/Layout.js'
8
9
 
9
10
  interface Props extends PaginatedPageProps<PostResourceData> {}
@@ -61,12 +62,11 @@ export default function PostsIndex({ data, pagination }: Props) {
61
62
  </h1>
62
63
 
63
64
  <form className="flex gap-2" onSubmit={search}>
64
- <input
65
+ <Input
65
66
  type="search"
66
67
  value={keywords}
67
68
  onChange={(event) => setKeywords(event.target.value)}
68
69
  placeholder="Search posts…"
69
- className="w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none placeholder:text-g-muted focus:border-transparent focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent"
70
70
  />
71
71
  <button
72
72
  type="submit"
@@ -2,13 +2,13 @@ import { Head, useForm } from '@inertiajs/react'
2
2
  import { useId } from 'react'
3
3
  import type { ApiRoutes } from '@/.guren/api-client.gen'
4
4
  import { route } from '@/.guren/routes.gen'
5
+ import { Input } from '@/resources/js/components/ui/Input'
6
+ import { Label } from '@/resources/js/components/ui/Label'
7
+ import { Textarea } from '@/resources/js/components/ui/Textarea'
5
8
  import Layout from '../../components/Layout.js'
6
9
 
7
10
  type PostFormData = ApiRoutes['posts.store']['body']
8
11
 
9
- const fieldClass =
10
- 'mt-1 w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none placeholder:text-g-muted focus:border-transparent focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent'
11
-
12
12
  export default function NewPost() {
13
13
  const form = useForm<PostFormData>({ title: '', excerpt: '', body: '' })
14
14
 
@@ -26,6 +26,8 @@ export default function NewPost() {
26
26
  </h1>
27
27
 
28
28
  <form
29
+ method="post"
30
+ action={route('posts.store')}
29
31
  className="space-y-4"
30
32
  onSubmit={(event) => {
31
33
  event.preventDefault()
@@ -33,43 +35,37 @@ export default function NewPost() {
33
35
  }}
34
36
  >
35
37
  <div>
36
- <label htmlFor={titleId} className="block text-sm font-bold text-g-heading">
37
- Title
38
- </label>
39
- <input
38
+ <Label htmlFor={titleId}>Title</Label>
39
+ <Input
40
40
  id={titleId}
41
41
  type="text"
42
42
  value={form.data.title}
43
43
  onChange={(event) => form.setData('title', event.target.value)}
44
- className={fieldClass}
44
+ className="mt-1"
45
45
  />
46
46
  {form.errors.title ? <p className="mt-1 text-sm text-g-danger">{form.errors.title}</p> : null}
47
47
  </div>
48
48
 
49
49
  <div>
50
- <label htmlFor={excerptId} className="block text-sm font-bold text-g-heading">
51
- Excerpt
52
- </label>
53
- <input
50
+ <Label htmlFor={excerptId}>Excerpt</Label>
51
+ <Input
54
52
  id={excerptId}
55
53
  type="text"
56
54
  value={form.data.excerpt}
57
55
  onChange={(event) => form.setData('excerpt', event.target.value)}
58
- className={fieldClass}
56
+ className="mt-1"
59
57
  />
60
58
  {form.errors.excerpt ? <p className="mt-1 text-sm text-g-danger">{form.errors.excerpt}</p> : null}
61
59
  </div>
62
60
 
63
61
  <div>
64
- <label htmlFor={bodyId} className="block text-sm font-bold text-g-heading">
65
- Body
66
- </label>
67
- <textarea
62
+ <Label htmlFor={bodyId}>Body</Label>
63
+ <Textarea
68
64
  id={bodyId}
69
65
  rows={10}
70
66
  value={form.data.body}
71
67
  onChange={(event) => form.setData('body', event.target.value)}
72
- className={fieldClass}
68
+ className="mt-1"
73
69
  />
74
70
  {form.errors.body ? <p className="mt-1 text-sm text-g-danger">{form.errors.body}</p> : null}
75
71
  </div>
@@ -32,7 +32,7 @@ export default function ProfileEdit({ profile, status }: Props) {
32
32
  <Alert>{status}</Alert>
33
33
  ) : null}
34
34
 
35
- <form className="space-y-4" onSubmit={form.handleSubmit}>
35
+ <form method="post" action={profileUpdateForm.path} className="space-y-4" onSubmit={form.handleSubmit}>
36
36
  <Field form={form} name="name" />
37
37
  <Field form={form} name="email" />
38
38
  <Field form={form} name="password" as="password" label="New password" />
@@ -20,8 +20,11 @@ export const { getDatabase, migrateDatabase, closeDatabase, configureOrm, seedDa
20
20
  export type AppSeederContext = MySqlSeederContext
21
21
 
22
22
  /**
23
- * Seeding is one-shot provisioning, not part of booting: production boots
24
- * repeatedly on serverless cold starts, and a bundle has no resolver for the
25
- * raw db/seeders/*.ts files. Run `bunx guren db:seed` explicitly instead.
23
+ * Seeding on boot is a local convenience, allowed by name: `bun run dev` sets
24
+ * NODE_ENV=development and `bun test` sets test. Anything else, an unset NODE_ENV
25
+ * included, never seeds, since seeders write demo accounts and production boots
26
+ * repeatedly on serverless cold starts. Run `bunx guren db:seed` explicitly there.
26
27
  */
27
- export default defineDatabaseConfig(database, { seedOnBoot: process.env.NODE_ENV !== 'production' })
28
+ export default defineDatabaseConfig(database, {
29
+ seedOnBoot: process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test',
30
+ })
@@ -20,8 +20,11 @@ export const { getDatabase, migrateDatabase, closeDatabase, configureOrm, seedDa
20
20
  export type AppSeederContext = PostgresSeederContext
21
21
 
22
22
  /**
23
- * Seeding is one-shot provisioning, not part of booting: production boots
24
- * repeatedly on serverless cold starts, and a bundle has no resolver for the
25
- * raw db/seeders/*.ts files. Run `bunx guren db:seed` explicitly instead.
23
+ * Seeding on boot is a local convenience, allowed by name: `bun run dev` sets
24
+ * NODE_ENV=development and `bun test` sets test. Anything else, an unset NODE_ENV
25
+ * included, never seeds, since seeders write demo accounts and production boots
26
+ * repeatedly on serverless cold starts. Run `bunx guren db:seed` explicitly there.
26
27
  */
27
- export default defineDatabaseConfig(database, { seedOnBoot: process.env.NODE_ENV !== 'production' })
28
+ export default defineDatabaseConfig(database, {
29
+ seedOnBoot: process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test',
30
+ })
@@ -27,8 +27,11 @@ export const { getDatabase, migrateDatabase, closeDatabase, configureOrm, seedDa
27
27
  export type AppSeederContext = SqliteSeederContext
28
28
 
29
29
  /**
30
- * Seeding is one-shot provisioning, not part of booting: production boots
31
- * repeatedly on serverless cold starts, and a bundle has no resolver for the
32
- * raw db/seeders/*.ts files. Run `bunx guren db:seed` explicitly instead.
30
+ * Seeding on boot is a local convenience, allowed by name: `bun run dev` sets
31
+ * NODE_ENV=development and `bun test` sets test. Anything else, an unset NODE_ENV
32
+ * included, never seeds, since seeders write demo accounts and production boots
33
+ * repeatedly on serverless cold starts. Run `bunx guren db:seed` explicitly there.
33
34
  */
34
- export default defineDatabaseConfig(database, { seedOnBoot: process.env.NODE_ENV !== 'production' })
35
+ export default defineDatabaseConfig(database, {
36
+ seedOnBoot: process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test',
37
+ })
@@ -6,10 +6,20 @@ A fullstack TypeScript application built with [Guren](https://guren.dev).
6
6
 
7
7
  ```bash
8
8
  bun install
9
+ <!-- guren:container -->
10
+ bun run db:up # start the __DATABASE_LABEL__ container
11
+ <!-- /guren:container -->
12
+ bun run db:make # generate a migration from db/schema.ts
13
+ bun run db:migrate # apply it
9
14
  bun run dev
10
15
  ```
11
16
 
12
- That's it. No Docker, no database setup — SQLite is ready out of the box.
17
+ <!-- guren:container -->
18
+ __DATABASE_LABEL__ runs in the container `docker-compose.yml` defines, and `DATABASE_URL` in `.env` points at it. `bun run db:down` stops it.
19
+ <!-- /guren:container -->
20
+ <!-- guren:no-container -->
21
+ No Docker and no database server: SQLite keeps the database in the file `DATABASE_URL` names in `.env`.
22
+ <!-- /guren:no-container -->
13
23
 
14
24
  Visit `http://localhost:3333` to see your app running.
15
25
 
@@ -30,13 +40,52 @@ bunx guren add schedule # task scheduling
30
40
 
31
41
  ## Project Structure
32
42
 
33
- - `routes/web.ts` — route definitions
43
+ - `routes/web.ts` — route definitions, a registrar `src/app.ts` passes to `createApp({ routes })`
34
44
  - `app/Http/Controllers/` — request handlers
35
45
  - `app/Models/` — ORM models
36
46
  - `resources/js/pages/` — React pages (rendered via Inertia.js)
37
47
  - `config/database.ts` — database configuration
38
48
  - `db/schema.ts` — Drizzle table definitions
39
49
 
50
+ ## Database
51
+
52
+ This app uses __DATABASE_LABEL__. `config/database.ts` creates the connection, and `DATABASE_URL` in `.env` selects the database.
53
+
54
+ To switch to another driver:
55
+
56
+ 1. Scaffold a reference app with `bunx create-guren-app ../reference --db <driver> --no-install`, and copy its `config/database.ts` and `drizzle.config.ts` over yours. Rewrite `db/schema.ts` in that dialect, following the reference's `users` table.
57
+ 2. Add the client: `bun add postgres` for PostgreSQL, `bun add mysql2` for MySQL. SQLite needs none.
58
+ 3. Set `DATABASE_URL` in `.env` in the new driver's form: a connection string such as `postgres://user:pass@localhost:5432/app` or `mysql://user:pass@localhost:3306/app`, or a file path such as `./data/guren.db` for SQLite.
59
+ 4. Empty `db/migrations/` and run `bun run db:make`, since a migration is written in one dialect's SQL.
60
+ 5. For PostgreSQL or MySQL, start a server that `DATABASE_URL` reaches. The reference app's `docker-compose.yml` runs one; an app gets that file only when it is created with PostgreSQL or MySQL.
61
+
62
+ See the [database guide](https://guren.dev/docs/guides/database) for details.
63
+
64
+ <!-- guren:ssr -->
65
+ ## Server-Side Rendering
66
+
67
+ Pages render on the server through Inertia SSR. During development the Bun server reads `resources/js/ssr.tsx` directly. Production builds use the SSR bundle and manifest Vite generates, which `src/main.ts` wires up through `autoConfigureInertiaAssets`.
68
+
69
+ `bun run build` runs `vite build` for the client and `vite build --ssr` for the server bundle, so the first request is answered with pre-rendered HTML. `bun run preview` then starts the same Bun server in production mode against those manifests.
70
+
71
+ ### Deploy to Vercel
72
+
73
+ Vercel support is an opt-in plugin for SSR apps:
74
+
75
+ ```bash
76
+ bunx guren plugin @guren/plugin-vercel
77
+ bun add @guren/plugin-vercel
78
+ bun run vercel:build
79
+ ```
80
+
81
+ Then deploy with Vercel's prebuilt flow:
82
+
83
+ ```bash
84
+ vercel build
85
+ vercel deploy --prebuilt
86
+ ```
87
+
88
+ <!-- /guren:ssr -->
40
89
  ## Favicon
41
90
 
42
91
  `public/favicon.svg` ships as a placeholder and is linked from `src/app.ts` via
@@ -56,20 +105,13 @@ deployments (AWS Lambda, for example) serve them from a CDN instead.
56
105
  | `bun run build` | Build for production |
57
106
  | `bun run preview` | Start the built app with the Bun production server |
58
107
  | `bun run start` | Start the app in production mode (`NODE_ENV=production`); what a deployment runs |
108
+ <!-- guren:container -->
109
+ | `bun run db:up` | Start the __DATABASE_LABEL__ container |
110
+ | `bun run db:down` | Stop the __DATABASE_LABEL__ container |
111
+ <!-- /guren:container -->
112
+ | `bun run db:make` | Generate a migration from `db/schema.ts` |
59
113
  | `bun run db:migrate` | Run database migrations |
60
114
  | `bun run db:seed` | Seed the database |
61
115
  | `bun run codegen` | Regenerate route/page types |
62
116
 
63
- If you scaffolded with PostgreSQL or MySQL, this project also has a `docker-compose.yml` and `bun run db:up` / `bun run db:down` to start and stop the database container. Start it before `bun run db:migrate`.
64
-
65
117
  Run `bun run build` before `bun run preview` so the production server can read the generated manifests from `public/assets`.
66
-
67
- ## Switching to PostgreSQL
68
-
69
- Update `config/database.ts` to use `createPostgresDatabase` and set `DATABASE_URL`:
70
-
71
- ```bash
72
- DATABASE_URL=postgres://user:pass@localhost:5432/myapp
73
- ```
74
-
75
- See the [database guide](https://guren.dev/docs/guides/database) for details.
@@ -6,7 +6,7 @@
6
6
  "scripts": {
7
7
  "codegen": "bunx guren codegen --force",
8
8
  "dev": "bun run codegen && GUREN_MCP=1 GUREN_DOCS=1 bun run dev:server",
9
- "dev:server": "bun --hot bin/serve.ts",
9
+ "dev:server": "NODE_ENV=development bun --hot bin/serve.ts",
10
10
  "console": "bun bin/console.ts",
11
11
  "typecheck": "tsc --noEmit",
12
12
  "lint": "bunx oxlint",
@@ -22,8 +22,8 @@
22
22
  "db:seed": "bunx guren db:seed"
23
23
  },
24
24
  "dependencies": {
25
- "@guren/cli": "^2.34.0",
26
- "@guren/core": "^1.25.0",
25
+ "@guren/cli": "^2.35.1",
26
+ "@guren/core": "^1.26.0",
27
27
  "@guren/inertia-client": "^1.3.0",
28
28
  "@guren/orm": "^2.15.0",
29
29
  "@inertiajs/react": "^3.6.1",
@@ -33,7 +33,7 @@
33
33
  "zod": "^4.5.0"
34
34
  },
35
35
  "devDependencies": {
36
- "@guren/testing": "^1.14.2",
36
+ "@guren/testing": "^1.14.3",
37
37
  "@tailwindcss/vite": "^4.2.2",
38
38
  "@types/react": "^19.0.0",
39
39
  "@types/react-dom": "^19.0.0",
@@ -29,7 +29,7 @@
29
29
  --g-heading: #111827;
30
30
  --g-text: #1f2937;
31
31
  --g-text-2: #4b5563;
32
- --g-muted: #9ca3af;
32
+ --g-muted: #6b7280; /* 4.67:1 on --g-raised, the lowest of the three surfaces (AA is 4.5) */
33
33
 
34
34
  /* text printed on the ink surface */
35
35
  --g-on-ink: #fff5f5;
@@ -73,8 +73,8 @@
73
73
 
74
74
  --g-heading: #e0def4;
75
75
  --g-text: #e0def4;
76
- --g-text-2: #908caa;
77
- --g-muted: #6e6a86;
76
+ --g-text-2: #aeabc9; /* 1.51:1 over --g-muted, as light's text-2 is 1.56:1 over its muted */
77
+ --g-muted: #8d89a7; /* 4.52:1 on --g-raised; rose-pine's #6e6a86 is 2.94:1 */
78
78
 
79
79
  /* fills stay crimson in both themes; accent TEXT moves to rose —
80
80
  crimson measures 4.42:1 on this ground */
@@ -1,8 +1,8 @@
1
- // guren-ui: Input v1. `guren upgrade` replaces this file only while it is unedited.
1
+ // guren-ui: Input v2. `guren upgrade` replaces this file only while it is unedited.
2
2
  import type { InputHTMLAttributes } from 'react'
3
3
 
4
4
  export const INPUT_CLASS =
5
- 'w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none placeholder:text-g-muted focus:border-transparent focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent aria-invalid:border-g-danger-chip'
5
+ 'w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none placeholder:text-g-muted focus:outline-solid focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent aria-invalid:border-g-danger-chip'
6
6
 
7
7
  /** `aria-invalid` turns the border to the danger tone. */
8
8
  export function Input({ className, ...props }: InputHTMLAttributes<HTMLInputElement>) {
@@ -1,8 +1,8 @@
1
- // guren-ui: Select v1. `guren upgrade` replaces this file only while it is unedited.
1
+ // guren-ui: Select v2. `guren upgrade` replaces this file only while it is unedited.
2
2
  import type { SelectHTMLAttributes } from 'react'
3
3
 
4
4
  const SELECT_CLASS =
5
- 'w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none focus:border-transparent focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent aria-invalid:border-g-danger-chip'
5
+ 'w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none focus:outline-solid focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent aria-invalid:border-g-danger-chip'
6
6
 
7
7
  export interface SelectOption {
8
8
  value: string
@@ -1,8 +1,8 @@
1
- // guren-ui: Textarea v1. `guren upgrade` replaces this file only while it is unedited.
1
+ // guren-ui: Textarea v2. `guren upgrade` replaces this file only while it is unedited.
2
2
  import type { TextareaHTMLAttributes } from 'react'
3
3
 
4
4
  const TEXTAREA_CLASS =
5
- 'w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none placeholder:text-g-muted focus:border-transparent focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent aria-invalid:border-g-danger-chip'
5
+ 'w-full rounded-g-ctl border border-g-line-strong bg-g-panel px-3 py-2 text-g-text transition outline-none placeholder:text-g-muted focus:outline-solid focus:outline-2 focus:-outline-offset-1 focus:outline-g-accent aria-invalid:border-g-danger-chip'
6
6
 
7
7
  /** `aria-invalid` turns the border to the danger tone. */
8
8
  export function Textarea({ className, ...props }: TextareaHTMLAttributes<HTMLTextAreaElement>) {
@@ -1,52 +0,0 @@
1
- # __APP_TITLE__
2
-
3
- Welcome to your new Guren application. This template ships with Inertia server-side rendering enabled out of the box.
4
-
5
- ## Getting Started
6
-
7
- 1. Install dependencies with `bun install`.
8
- 2. Copy `.env.example` to `.env` and update any required values.
9
- 3. Generate route and page manifests with `bun run codegen`.
10
- 4. Start the development servers with `bun run dev` (runs Bun and Vite together).
11
-
12
- During development the Bun server reads `resources/js/ssr.tsx` directly. Production builds rely on the Vite-generated SSR bundle and manifest, which are wired automatically by `src/main.ts` through `autoConfigureInertiaAssets`.
13
-
14
- The default setup expects a PostgreSQL database. You can change the connection string in `config/database.ts` or set the `DATABASE_URL` environment variable before running the server.
15
-
16
- Routes are registered through `routes/web.ts`, which exports a registrar consumed by `src/app.ts` via `createApp({ routes, providers })`.
17
-
18
- ## Available Scripts
19
-
20
- - `bun run dev` - start the Bun API server alongside the Vite dev server.
21
- - `bun run build` - build both the client and SSR bundles with Vite.
22
- - `bun run preview` - serve the built app through the Bun production server locally.
23
- - `bun run start` - start the app in production mode (`NODE_ENV=production`); what a deployment runs.
24
- - `bun run codegen` - regenerate route declarations, route helpers, and page manifests.
25
- - `bun run db:make` - scaffold a new SQL migration from your schema using drizzle-kit.
26
- - `bun run db:migrate` - apply database migrations.
27
- - `bun run db:seed` - execute seeders.
28
-
29
- ### Production Builds
30
-
31
- Run `bun run build` before deploying. This script internally executes `bunx vite build` and `bunx vite build --ssr` so the Bun server can stream pre-rendered HTML during the first request. After building, `bun run preview` starts the same Bun server in production mode against the generated manifests instead of using Vite's static preview server.
32
-
33
- ### Deploy To Vercel
34
-
35
- Vercel support is available as an official opt-in plugin for SSR apps:
36
-
37
- ```bash
38
- bunx guren plugin @guren/plugin-vercel
39
- bun add @guren/plugin-vercel
40
- bun run vercel:build
41
- ```
42
-
43
- After that, deploy with Vercel's prebuilt flow:
44
-
45
- ```bash
46
- vercel build
47
- vercel deploy --prebuilt
48
- ```
49
-
50
- Tailwind CSS is ready to use out of the box. Edit `resources/css/app.css` or add utilities to your components and the dev server will pick them up automatically.
51
-
52
- Happy hacking!