Skip to content

build: phrase 4 and 5 - #3

Merged
abdelkabirouadoukou merged 6 commits into
mainfrom
build-phrase-4-and-5
Jul 26, 2026
Merged

abdelkabirouadoukou merged 6 commits into
mainfrom
build-phrase-4-and-5

Conversation

@abdelkabirouadoukou

@abdelkabirouadoukou abdelkabirouadoukou commented Jul 26, 2026 •

Copy link
Copy Markdown
Member

Summary by CodeRabbit

  • New Features

    • Added working dev, build, and start commands for project development and production workflows.
    • Added production server bundling and Docker deployment support.
    • Added development error pages with readable messages and stack traces.
    • Improved interactive component hydration in generated client bundles.
  • Bug Fixes

    • Added graceful production error responses instead of exposing internal details.
  • Documentation

    • Added deployment guidance covering Bun, Docker, Fly.io, VPS hosting, and required environment settings.

@coderabbitai

coderabbitai Bot commented Jul 26, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@abdelkabirouadoukou, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 18 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 23bcd64e-f045-4c25-b999-e66b6f691e23

📥 Commits

Reviewing files that changed from the base of the PR and between afc1812 and aa2adba.

📒 Files selected for processing (6)
  • Dockerfile
  • packages/cli/src/index.ts
  • packages/core/src/build.test.ts
  • packages/core/src/build.ts
  • packages/core/src/createApp.ts
  • packages/core/src/render.ts
📝 Walkthrough

Walkthrough

The PR implements dev, build, and start CLI commands, bundles Bun server output, validates island hydration artifacts, adds development error overlays, and introduces Docker and deployment documentation.

Changes

Production pipeline

Layer / File(s) Summary
Core server and island bundling
packages/core/src/build.ts, packages/core/src/build.test.ts
The build now bundles server/index.ts for Bun, updates island hydration fallback generation, and tests emitted hydration assets.
CLI project commands
packages/cli/src/*, packages/cli/package.json, packages/cli/tsconfig.json
The CLI discovers project configuration, generates development server scaffolding, invokes @x/core builds, and starts dist/server/index.js.
Development error responses
packages/core/src/error-overlay.ts, packages/core/src/createApp.ts, packages/core/src/index.ts
Core route and API errors render an escaped HTML overlay in development and generic 500 responses in production.
Deployment packaging and documentation
Dockerfile, DEPLOY.md, TASKS.md
Adds a multistage Bun image and documents production builds, Docker, Fly.io, VPS, environment variables, and output architecture.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant XCLI as x CLI
  participant XCore as `@x/core`
  participant Bun
  participant Server as dist/server/index.js
  Developer->>XCLI: Run x build
  XCLI->>XCore: Call build with project options
  XCore->>Bun: Bundle generated server entry
  Bun-->>XCore: Produce server/index.js
  Developer->>XCLI: Run x start
  XCLI->>Server: Start production bundle
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title is too vague and does not describe the actual changes in the build, CLI, Docker, and deployment workflow. Rename it to a concise summary of the main change, such as adding production build, CLI, and deployment support.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch build-phrase-4-and-5

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

🧹 Nitpick comments (4)
packages/core/src/createApp.ts (1)

154-163: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

API routes get an HTML overlay body.

An HTML document as the error body for a JSON endpoint breaks fetch/res.json() callers in dev. Consider negotiating on Accept and returning JSON (message + stack) for non-HTML clients.

♻️ Suggested content negotiation
             } catch (err) {
               console.error("[x] API handler error:", err);
               if (options.development) {
+                if (!(req.headers.get("accept") ?? "").includes("text/html")) {
+                  return Response.json(
+                    {
+                      error: err instanceof Error ? err.message : "Unknown error",
+                      stack: err instanceof Error ? err.stack : undefined,
+                    },
+                    { status: 500 },
+                  );
+                }
                 return new Response(renderErrorOverlay(err), {
                   status: 500,
                   headers: { "Content-Type": "text/html; charset=utf-8" },
                 });
               }
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/createApp.ts` around lines 154 - 163, Update the API
handler catch block in createApp so development errors negotiate the response
using the request’s Accept header: retain renderErrorOverlay(err) for clients
accepting HTML, but return a JSON body containing the error message and stack
for non-HTML clients while preserving the 500 status.
packages/core/src/error-overlay.ts (2)

10-11: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Non-Error throws lose all detail.

Anything thrown that isn't an Error (string, object, rejected value) renders as a bare "Unknown error" with no stack, which is the least useful case to debug.

🔧 Preserve the thrown value
-  const message = error instanceof Error ? error.message : "Unknown error";
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : (() => {
+            try {
+              return JSON.stringify(error) ?? String(error);
+            } catch {
+              return String(error);
+            }
+          })();
   const stack = error instanceof Error ? (error.stack ?? "") : "";
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/error-overlay.ts` around lines 10 - 11, Update the error
message and stack derivation in the error-overlay handling to preserve useful
details for non-Error thrown values, including strings and objects, instead of
always using “Unknown error” and an empty stack. Keep the existing
Error-specific message and stack behavior unchanged, and serialize or otherwise
safely represent the original thrown value for the fallback path.

1-7: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate escapeHtml helper.

packages/core/src/content.ts already exports an escapeHtml (re-exported from index.ts line 30). Reuse it instead of a second local copy so escaping rules stay consistent across renderers.

Note on the static analysis hint: all interpolations here land in element text nodes, so the missing ' escape isn't exploitable — a sanitizer dependency isn't warranted.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/error-overlay.ts` around lines 1 - 7, Remove the local
escapeHtml helper from error-overlay.ts and import and reuse the existing
exported escapeHtml from content.ts. Update all references in the error overlay
to use that shared helper, preserving the current text-node escaping behavior
without adding a sanitizer dependency.

Source: Linters/SAST tools

DEPLOY.md (1)

113-113: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Declare the architecture diagram fence as text.

Use ```text to satisfy MD040.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@DEPLOY.md` at line 113, Update the architecture diagram code fence in
DEPLOY.md to use the text language identifier, changing the opening fence to
```text so it satisfies MD040 while preserving the diagram content.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Dockerfile`:
- Around line 12-17: Update the production Dockerfile stage to copy the runtime
artifacts with ownership assigned to the unprivileged bun user, then add a USER
directive selecting bun before the existing CMD. Keep the current runtime files,
exposed port, and startup command unchanged.
- Line 10: Replace the Dockerfile build step invoking `bun x build` with the
repository’s local CLI command targeting `packages/cli/src/index.ts build`,
ensuring it produces output in `/app/dist` for the production stage to copy.

In `@packages/cli/src/index.ts`:
- Around line 30-34: Update the config-derived path construction in the project
configuration loading logic so an omitted contentDir remains optional when the
default <project>/content directory does not exist. Validate the fallback
directory before assigning it, preserving the existing behavior for explicitly
configured contentDir values and matching the no-config branch used by
development and build flows.
- Line 121: Update generateServerFile and the generated server.ts path so
Bun.serve uses the configured opts.port value instead of only app. Ensure the
port returned by detectOptions is applied consistently in both generated server
entry points.

In `@packages/core/src/build.ts`:
- Around line 160-165: Update the server bundling failure branch in the build
flow to throw an error after logging bundleResult.stderr, preventing the build
from reaching completion and ensuring the CLI/CI exits non-zero when
bundleResult.success is false.
- Around line 187-196: Update packages/core/src/build.ts:187-196 to emit the Bun
build directly to bundlePath with an explicit <entryId>.js filename, verify that
the real bundle exists, and only use the fallback when the build or artifact
validation fails; publish the exact <entryId>.js URL. Update
packages/core/src/build.test.ts:159-169 to assert that the exact artifact is
produced and contains hydrateRoot code. Update TASKS.md:124-127 to reflect this
completed hydration-bundle validation work.
- Around line 152-165: The build flow around buildServerEntry and the
Bun.spawnSync bundling step must produce a runnable dist/server/index.js, not
only route exports. Add the production server bootstrap to the generated
entrypoint, including createApp and Bun.serve behavior, or reuse the existing
dev-server bootstrap for both build and start; preserve the current route
exports while ensuring x start and the Docker CMD keep the process running.

In `@packages/core/src/createApp.ts`:
- Around line 230-235: Update renderStreamingPage and the mode === "server" path
in createApp so errors occurring after the shell flush are propagated through
the configured error boundary/error response instead of only being logged.
Ensure the stream pump handles rejected rendering and does not return a client
Response until the stream reaches controller.close() or an explicit error state,
preserving the route-level catch behavior for the resulting error response.

---

Nitpick comments:
In `@DEPLOY.md`:
- Line 113: Update the architecture diagram code fence in DEPLOY.md to use the
text language identifier, changing the opening fence to ```text so it satisfies
MD040 while preserving the diagram content.

In `@packages/core/src/createApp.ts`:
- Around line 154-163: Update the API handler catch block in createApp so
development errors negotiate the response using the request’s Accept header:
retain renderErrorOverlay(err) for clients accepting HTML, but return a JSON
body containing the error message and stack for non-HTML clients while
preserving the 500 status.

In `@packages/core/src/error-overlay.ts`:
- Around line 10-11: Update the error message and stack derivation in the
error-overlay handling to preserve useful details for non-Error thrown values,
including strings and objects, instead of always using “Unknown error” and an
empty stack. Keep the existing Error-specific message and stack behavior
unchanged, and serialize or otherwise safely represent the original thrown value
for the fallback path.
- Around line 1-7: Remove the local escapeHtml helper from error-overlay.ts and
import and reuse the existing exported escapeHtml from content.ts. Update all
references in the error overlay to use that shared helper, preserving the
current text-node escaping behavior without adding a sanitizer dependency.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 73a24d38-6041-4e37-812f-d5ff84980127

📥 Commits

Reviewing files that changed from the base of the PR and between e986381 and afc1812.

📒 Files selected for processing (11)
  • DEPLOY.md
  • Dockerfile
  • TASKS.md
  • packages/cli/package.json
  • packages/cli/src/index.ts
  • packages/cli/tsconfig.json
  • packages/core/src/build.test.ts
  • packages/core/src/build.ts
  • packages/core/src/createApp.ts
  • packages/core/src/error-overlay.ts
  • packages/core/src/index.ts

Comment thread Dockerfile Resolved
Comment thread Dockerfile Resolved
Comment thread packages/cli/src/index.ts Resolved
Comment thread packages/cli/src/index.ts Resolved
Comment thread packages/core/src/build.ts Resolved
Comment thread packages/core/src/build.ts Resolved
Comment thread packages/core/src/build.ts Outdated
Comment on lines 187 to 196
const result = Bun.spawnSync(["bun", "build", "--target=browser", "--outdir", outdir, entryPath]);

if (result.success) {
return [`/_islands/${entryId}/${entryId}.js`];
}

console.error(` [error] island bundle failed for ${routeFilePath}:`);
console.error(result.stderr.toString());
writeFileSync(bundlePath, generateFallbackHydration(islandNames), "utf-8");
return [`/_islands/${entryId}/${entryId}.js`];

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

According to Bun’s official bundler documentation, what output filename is produced for bun build hydrate.tsx --outdir , and how does --outfile affect that filename?

💡 Result:

According to Bun's official documentation, when running bun build hydrate.tsx --outdir <directory>, Bun generates a bundle from the entry point and writes it to the specified output directory [1]. By default, the output file takes the same base name as the entry point file (e.g., hydrate.js if the entry point is hydrate.tsx) [1]. The --outfile flag is used to specify a custom filename for the build output [2][3]. If you provide --outfile <filename>, Bun will use that path for the output file instead of the default filename [4][5]. It is important to note the following behaviors regarding these flags: 1. Conflict: Using both --outdir and --outfile together can lead to unexpected behavior; historically, in many cases, the --outfile flag has been ignored in favor of the default naming within the --outdir [5]. 2. Executables: When using the --compile flag to create a standalone executable, --outfile is specifically required to set the name of the resulting binary, and --outdir is not supported for that purpose [6][7]. 3. API vs CLI: In the Bun.build() JavaScript API, outdir is used for general bundling to define the output directory [1][8]. For standalone executables, outfile must be defined within the compile configuration object [6][9].

Citations:


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== candidate files =="
fd -a 'build\.(ts|test\.ts)$|TASKS\.md$' . | sed 's#^\./##'

echo
echo "== build.ts relevant section =="
if [ -f packages/core/src/build.ts ]; then
  nl -ba packages/core/src/build.ts | sed -n '140,220p'
fi

echo
echo "== build.test.ts relevant section =="
if [ -f packages/core/src/build.test.ts ]; then
  nl -ba packages/core/src/build.test.ts | sed -n '130,185p'
fi

echo
echo "== task text matches =="
grep -n "island hydration|hydrateRoot|bundleRouteIslands" TASKS.md packages/core/src/build.ts packages/core/src/build.test.ts || true

Repository: abdelkabirouadoukou/x

Length of output: 380


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== read build.ts =="
awk 'NR>=140 && NR<=220 {printf "%6d  %s\n", NR, $0}' packages/core/src/build.ts

echo
echo "== read build.test.ts =="
awk 'NR>=130 && NR<=185 {printf "%6d  %s\n", NR, $0}' packages/core/src/build.test.ts

echo
echo "== task text matches =="
grep -n "island hydration|hydrateRoot|bundleRouteIslands" TASKS.md packages/core/src/build.ts packages/core/src/build.test.ts || true

echo
echo "== inspect surrounding bundleRouteIslands definitions/usages =="
rg -n "bundleRouteIslands|function .*hydrate|hydrate.tsx|outfile|bundlePath|_islands" packages/core/src/build.ts packages/core/src/build.test.ts

Repository: abdelkabirouadoukou/x

Length of output: 6590


Publish and validate the exact hydration bundle. With --outdir, Bun keeps the entry basename (hydrate.tsx → hydrate.js), but the implementation always checks for entryId.js; successful island builds therefore publish a missing script URL and fallback bundler errors write a non-hydrating shim. Emit to bundlePath with an explicit output filename, fail when the real bundle does not produce it, and update the test to assert that exact <entryId>.js artifact contains hydrateRoot code.

📍 Affects 3 files
  • packages/core/src/build.ts#L187-L196 (this comment)
  • packages/core/src/build.test.ts#L159-L169
  • TASKS.md#L124-L127
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/build.ts` around lines 187 - 196, Update
packages/core/src/build.ts:187-196 to emit the Bun build directly to bundlePath
with an explicit <entryId>.js filename, verify that the real bundle exists, and
only use the fallback when the build or artifact validation fails; publish the
exact <entryId>.js URL. Update packages/core/src/build.test.ts:159-169 to assert
that the exact artifact is produced and contains hydrateRoot code. Update
TASKS.md:124-127 to reflect this completed hydration-bundle validation work.

Comment thread packages/core/src/createApp.ts Resolved
@abdelkabirouadoukou
abdelkabirouadoukou merged commit e776129 into main Jul 26, 2026
2 checks passed
@abdelkabirouadoukou
abdelkabirouadoukou deleted the build-phrase-4-and-5 branch August 1, 2026 04:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant