Comprehensive documentation improvements #89
Conversation
- Reorder sections to start simple then show schema power - Change from "Type-Safe by Default" to "Schema-Driven Type Safety" - Use simple hello example instead of pathParams - Remove redundant sections (What You Get, Learn More) - Focus on core value: schema-driven type safety
- Change from manual setup to CLI-first workflow (npm create kori-app) - Restructure into 7 clear sections: Setup, Basic API, Request & Response, Hooks, Plugins, Validation, OpenAPI - Add type-safety emphasis throughout with helpful comments - Fix API consistency (queryParams(), setHeader(), etc.) - Unify method chaining patterns and export statements - Simplify OpenAPI section by removing optional pluginMetadata - Add practical examples with environment extensions and logging
|
WalkthroughThis update revises and streamlines Kori's documentation. It removes the configuration guide and all related sidebar and cross-reference links, restructures the "Getting Started" and "What is Kori?" guides for clarity and conciseness, and simplifies documentation writing rules. New sections for hooks and plugins are added, and code examples are modernized throughout. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Docs Sidebar
participant Guides
participant Examples
User->>Docs Sidebar: Browse navigation
Docs Sidebar-->>User: No "Configuration" link
User->>Guides: Read "Getting Started", "What is Kori?", "Plugins"
Guides-->>User: Streamlined, modernized content (no configuration guide)
User->>Examples: View REST API example
Examples-->>User: No reference to configuration guide
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Pull Request Overview
Remove the outdated configuration guide documentation that contained inaccurate information about createKori options and update references throughout the documentation to maintain consistency.
- Delete the entire configuration.md file containing inaccurate createKori API information
- Update navigation links to remove configuration references
- Revise getting-started.md with simplified, accurate examples
- Refresh what-is-kori.md with cleaner messaging and correct code patterns
Reviewed Changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/en/guide/configuration.md | Complete removal of outdated configuration documentation |
| docs/.vitepress/config.js | Remove configuration navigation links from both English and Japanese sections |
| docs/en/guide/getting-started.md | Major rewrite with simplified examples and accurate API usage |
| docs/en/guide/what-is-kori.md | Streamlined content with cleaner messaging and correct code examples |
| docs/en/guide/plugins.md | Update "Next Steps" link to point to getting-started instead of configuration |
| docs/en/examples/rest-api.md | Remove reference to database configuration guide |
| .cursor/rules/docs.mdc | Simplified documentation writing guidelines |
Comments suppressed due to low confidence (2)
docs/en/guide/getting-started.md:123
- The import 'zod/v4' appears to reference a non-existent version. Zod uses semantic versioning and v4 is not a valid import path. This should likely be 'zod' without the version specifier.
import { createKoriZodRequestValidator } from '@korix/zod-validator';
docs/en/guide/getting-started.md:167
- The import 'zod/v4' appears to reference a non-existent version. Zod uses semantic versioning and v4 is not a valid import path. This should likely be 'zod' without the version specifier.
import { z } from 'zod';
|
|
||
| ```bash | ||
| npm install @korix/kori @korix/nodejs-adapter | ||
| npm create kori-app my-api # 🚧 Coming Soon! |
There was a problem hiding this comment.
[nitpick] The comment '🚧 Coming Soon!' indicates this command doesn't work yet, but the section is titled 'Quick Setup (Coming Soon!)' which already conveys this. Consider removing the inline comment to avoid redundancy.
| npm create kori-app my-api # 🚧 Coming Soon! | |
| npm create kori-app my-api |
bufferings
changed the title
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Bugbot free trial expires on July 29, 2025
Learn more in the Cursor dashboard.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/en/guide/what-is-kori.md (1)
22-34: Minor nit: missing import comment forzFor completeness, consider adding a comment or line showing
import { z } from 'zod';before usingz.object(...)so newcomers don’t wonder wherezcame from.docs/en/guide/getting-started.md (1)
204-204: Nit: single exclamation point is enoughThree exclamation marks trigger style-check warnings. One is plenty: “documentation!”
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.cursor/rules/docs.mdc(1 hunks)docs/.vitepress/config.js(0 hunks)docs/en/examples/rest-api.md(0 hunks)docs/en/guide/configuration.md(0 hunks)docs/en/guide/getting-started.md(2 hunks)docs/en/guide/plugins.md(1 hunks)docs/en/guide/what-is-kori.md(1 hunks)
💤 Files with no reviewable changes (3)
- docs/en/examples/rest-api.md
- docs/.vitepress/config.js
- docs/en/guide/configuration.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{md,mdc,MD,MDX,README,README.md,README.mdc}
📄 CodeRabbit Inference Engine (.cursor/rules/coding.mdc)
Documentation files (.md, .mdc, README) may use non-ASCII characters freely
Files:
docs/en/guide/plugins.mddocs/en/guide/what-is-kori.mddocs/en/guide/getting-started.md
🪛 LanguageTool
docs/en/guide/getting-started.md
[style] ~204-~204: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 721 characters long)
Context: ...3000/docs` for interactive documentation!
(EN_EXCESSIVE_EXCLAMATION)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Cursor Bugbot
🔇 Additional comments (6)
.cursor/rules/docs.mdc (2)
3-3:.mdcfiles are now outside the rule’s scope – intentional?By dropping the
**/*.mdcpattern fromglobs, these writing rules will no longer apply to Markdown-Component (.mdc) files—even to this very file. If the intent was only to exclude generated docs, consider keeping**/*.mdcor adding a more specific exclusion pattern to avoid silently bypassing style enforcement for legitimate.mdcdocs.
9-31: LGTM – clearer, less dogmatic wordingThe softened language and condensed bullet lists improve readability while preserving the “source-code-first” principle.
docs/en/guide/plugins.md (1)
575-577: Link update looks correctThe “Next Steps” bullet now targets
/en/guide/getting-started, which exists in this PR and eliminates the dead link to the removed configuration guide.docs/en/guide/what-is-kori.md (1)
3-6: Nice, engaging introductionThe narrative opener and succinct value proposition read well and fit the new style guide.
docs/en/guide/getting-started.md (2)
121-135: Package names may be placeholders—double-check before publishing
@korix/zod-schemaand@korix/zod-validatorare referenced for the first time. Verify these packages (and their exact names) exist on npm, or readers will hit install errors.
175-182: Chained.applyPlugin()reads well – consider line wrapVery readable; no issues.
| import { createKori } from '@korix/kori'; | ||
|
|
||
| const app = createKori() | ||
| .onInit(async (ctx) => { | ||
| // Runs once when application starts | ||
| app.log().info('Application starting...'); | ||
| return ctx.withEnv({ applicationStartTime: new Date() }); | ||
| }) |
There was a problem hiding this comment.
onInit callback argument likely mislabeled
onInit previously receives the environment object, not a request/response context. Returning ctx.withEnv() therefore looks unsupported. Either:
- Rename the parameter to
envand return an extended env object, or - Confirm the API now exposes
withEnvon the init argument and update other docs for consistency.
- .onInit(async (ctx) => {
+ .onInit(async (env) => {
app.log().info('Application starting...');
- return ctx.withEnv({ applicationStartTime: new Date() });
+ return { ...env, applicationStartTime: new Date() };
})📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| import { createKori } from '@korix/kori'; | |
| const app = createKori() | |
| .onInit(async (ctx) => { | |
| // Runs once when application starts | |
| app.log().info('Application starting...'); | |
| return ctx.withEnv({ applicationStartTime: new Date() }); | |
| }) | |
| import { createKori } from '@korix/kori'; | |
| const app = createKori() | |
| .onInit(async (env) => { | |
| // Runs once when application starts | |
| app.log().info('Application starting...'); | |
| return { ...env, applicationStartTime: new Date() }; | |
| }) |
🤖 Prompt for AI Agents
In docs/en/guide/getting-started.md around lines 64 to 71, the onInit callback
argument is incorrectly named ctx and used as if it supports withEnv, but it
actually receives the environment object. Rename the parameter from ctx to env
and return an extended environment object by returning env.withEnv(...) if
supported, or adjust the code to correctly extend the environment according to
the current API. Also, ensure the naming and usage align with the official API
and update related documentation for consistency.
Comprehensive Documentation Improvements
This PR includes several focused improvements to enhance documentation quality, accuracy, and user experience.
Key Changes
🚀 Getting Started Guide Refactoring (
ef8c246)npm create kori-appworkflowqueryParams(),setHeader(), etc.) to match actual implementation📖 What is Kori Page Enhancement (
4c0615f)🎌 Japanese Content Improvements
05fa579)23077fb)🧹 Maintenance & Accuracy
249575e)docs/en/guide/configuration.mddue to implementation inconsistencies (9a911df)Technical Accuracy Improvements
createKoriFiles Changed
docs/en/guide/getting-started.md- Major refactoring with CLI-first approachdocs/en/guide/what-is-kori.md- Enhanced value proposition and simplified structuredocs/en/guide/configuration.md- Removed (implementation inconsistencies)docs/.vitepress/config.js- Updated navigation sidebardocs/en/examples/rest-api.md- Fixed broken linksdocs/en/guide/plugins.md- Updated cross-references.cursor/rules/docs.mdc- Simplified documentation rulesThese changes align with our documentation engineering principles: implementation accuracy, user-centered design, and maintaining Kori's distinctive features while providing a smooth learning path for new developers.
Summary by CodeRabbit