doc: misc improvements

[ymc9]

Fixes #513

Summary by CodeRabbit

• New Features

  • Added new CLI format command to format ZModel schema files.
  • Expanded API client documentation with lifecycle, authentication, plugin management, and query builder methods.

• Documentation

  • Updated Quick Start guide with improved component examples.
  • Enhanced API reference documentation with comprehensive method descriptions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
zenstack-new-site	Ready	Preview	Comment	Nov 19, 2025 4:32am

[coderabbitai]

Walkthrough

The changes introduce a new PackageDlx React component for displaying multi-package-manager dlx commands with tabbed interfaces, update documentation to use this component in the quick-start guide, expand the ClientContract API reference with detailed lifecycle, authentication, and query builder method documentation, add a new CLI format command reference, and apply minor metadata updates.

Changes

Cohort / File(s)	Summary
New Package Manager Component versioned_docs/version-3.x/_components/PackageDlx.tsx	New React component that renders a tabbed interface for multiple package managers (npm, yarn, pnpm, bun), constructing and displaying dlx commands by substituting a package placeholder, conditionally appending scripts and arguments, and displaying results in code blocks.
Documentation Examples Update versioned_docs/version-3.x/orm/quick-start.md	Updated initialization example to use the new PackageDlx component instead of PackageExec, and updated imports to remove file extensions and add PackageDlx import.
Documentation Metadata & Reference versioned_docs/version-3.x/orm/query-builder.md, versioned_docs/version-3.x/reference/api.md	Minor capitalization fix in query-builder metadata. Expanded API reference to document ClientContract\<Schema\> interface and ZenStackClient\<Schema\> class with detailed public methods including lifecycle ($connect, $disconnect), authentication ($setAuth, $auth), plugin management ($use, $unuse, $unuseAll), and query builder access ($qb, $qbRaw).
CLI Command Documentation versioned_docs/version-3.x/reference/cli.md	Added documentation for new format CLI command to format ZModel schema files.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• PackageDlx component: Straightforward React component with simple prop-based command construction; verify correct package manager commands and placeholder replacement logic.
• quick-start.md integration: Verify props passed to PackageDlx match component interface and produce expected output.
• api.md documentation: Verify documented methods accurately reflect the ClientContract interface and ZenStackClient implementation.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The pull request includes changes beyond the primary objective: updating api.md with ClientContract documentation and query-builder.md with front matter changes are not directly related to fixing the pnpx issue.	Scope the PR to focus on issue #513 fixes only; move api.md and query-builder.md changes to a separate pull request for documentation improvements.
Title check	❓ Inconclusive	The title 'doc: misc improvements' is too vague and generic; it uses non-descriptive terms that don't convey meaningful information about the specific changes.	Use a more specific title like 'doc: add PackageDlx component for explicit package manager invocation' to clearly describe the main change.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The pull request successfully addresses issue #513 by introducing PackageDlx component that explicitly specifies the executable and updating quick-start.md to use the new component, resolving the multiple-binaries ambiguity.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/dlx

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f3172f4 and 0021e0e.

📒 Files selected for processing (5)

• versioned_docs/version-3.x/_components/PackageDlx.tsx (1 hunks)
• versioned_docs/version-3.x/orm/query-builder.md (1 hunks)
• versioned_docs/version-3.x/orm/quick-start.md (2 hunks)
• versioned_docs/version-3.x/reference/api.md (2 hunks)
• versioned_docs/version-3.x/reference/cli.md (1 hunks)

🧰 Additional context used

🪛 LanguageTool

versioned_docs/version-3.x/reference/api.md

[style] ~119-~119: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...tract; ``` #### $unuseAll() Read more in the [Plugins documentation](../...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~130-~130: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...lientContract; ``` #### $qb Read more in the [Query Builder API document...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~141-~141: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...: ToKysely; ``` #### $qbRaw Read more in the [Query Builder API document...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (14)

versioned_docs/version-3.x/orm/query-builder.md (1)

3-3: LGTM!

The capitalization update improves consistency with the heading on Line 9.

versioned_docs/version-3.x/reference/cli.md (2)

29-29: LGTM!

The format command is properly added to the commands list with consistent formatting.

---

249-262: LGTM!

The format command documentation follows the established pattern and is complete.

versioned_docs/version-3.x/reference/api.md (6)

11-17: LGTM!

The separation of interface (ClientContract<Schema>) and implementation (ZenStackClient<Schema>) clarifies the API surface.

---

56-59: LGTM!

Good cross-reference to the detailed query API documentation, avoiding duplication.

---

60-76: LGTM!

Lifecycle methods are clearly documented with appropriate TypeScript signatures.

---

78-94: LGTM!

Authentication API is clearly documented with appropriate method and getter signatures.

---

96-127: LGTM!

Plugin management methods are well documented with appropriate cross-references to the Plugins documentation. The repeated "Read more in..." pattern flagged by static analysis is intentional and appropriate for cross-referencing related documentation sections.

---

129-149: LGTM!

Query builder properties are well documented, with a clear distinction between the enhanced ($qb) and raw ($qbRaw) query builders.

versioned_docs/version-3.x/orm/quick-start.md (2)

8-10: LGTM!

Import statements correctly updated to add PackageDlx and standardize by removing file extensions.

---

34-34: LGTM!

The switch to PackageDlx directly addresses issue #513 by providing the correct pnpm dlx command format with an explicit executable, avoiding the multiple binaries error.

versioned_docs/version-3.x/_components/PackageDlx.tsx (3)

1-9: LGTM!

Imports and Props interface are correctly defined.

---

18-30: LGTM!

The command construction logic correctly handles both placeholder-based commands (pnpm) and direct package managers (npx, bunx). The renaming of package to pkg in destructuring avoids the reserved keyword issue.

---

11-16: No actionable issues found.

Verification of the command generation reveals that the original concern was unfounded. The empirical test shows that npx @zenstackhq/cli@next init correctly executes the zen binary with init as a subcommand, working as expected despite not explicitly including the script name. The npm command produces identical results to the pnpm approach, and yarn uses the same npm logic. The current implementation generates correct commands for all tested package managers.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[herberthobregon]

maybe the short way es pnpx --package=%package

[ymc9]

I don't know why but it doesn't seem to work ...

[herberthobregon]

You must run pnpx --package=@zenstackhq/cli@next zenstack init, using zenstack not zen

For future readers, you must include --package=@zenstackhq/cli otherwise it will think you need to install zenstacks package (v2).