docs: add standalone mode documentation to CLAUDE.md #393
Conversation
Document how tegg runs without Egg.js using the standalone package, including initialization flow, context management via AsyncLocalStorage, inner objects mechanism, and usage examples. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughAdds comprehensive documentation for tegg's standalone runtime mode, covering module initialization, lifecycle management, context handling via AsyncLocalStorage, inner object integration, and practical usage examples with configuration patterns for standalone and plugin-based operation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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. Comment |
Summary of ChangesHello @killagu, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation by adding a detailed guide for the Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds comprehensive documentation for the standalone mode of tegg. The new documentation in CLAUDE.md covers the architecture, initialization flow, context management, and usage of the @eggjs/tegg-standalone package. The content is well-structured and detailed. I've provided a couple of minor suggestions to improve the clarity and consistency of the code examples and text.
| myService: MyService; | ||
|
|
||
| async main(): Promise<string> { | ||
| return await this.myService.doSomething(); |
There was a problem hiding this comment.
In an async function, you can directly return a promise without await-ing it. The function will automatically adopt the state of the returned promise. Removing the redundant await makes the code slightly more concise and is a good practice to demonstrate in documentation.
| return await this.myService.doSomething(); | |
| return this.myService.doSomething(); |
| - Use `@Inject()` for dependencies | ||
| - Use lifecycle hooks (`init()`, `destroy()`) instead of Egg.js lifecycle | ||
| - Provide factories that accept configuration via injection |
There was a problem hiding this comment.
For consistency and improved readability, it's good practice to end each item in a list with a period, especially when they function as complete sentences or imperative clauses.
| - Use `@Inject()` for dependencies | |
| - Use lifecycle hooks (`init()`, `destroy()`) instead of Egg.js lifecycle | |
| - Provide factories that accept configuration via injection | |
| - Use `@Inject()` for dependencies. | |
| - Use lifecycle hooks (`init()`, `destroy()`) instead of Egg.js lifecycle. | |
| - Provide factories that accept configuration via injection. |
![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
🤖 Fix all issues with AI agents
In @CLAUDE.md:
- Line 882: Update the incorrect imports that use the hyphenated package name
'@eggjs/tegg-standalone' to the correct subpath '@eggjs/tegg/standalone' in all
standalone-mode examples; specifically replace occurrences that import symbols
like "main" (and any other imports) from '@eggjs/tegg-standalone' so they import
from '@eggjs/tegg/standalone' instead.
🧹 Nitpick comments (2)
CLAUDE.md (2)
744-754: Add language specifier to code block.The code block showing the directory structure should have a language specifier for proper syntax highlighting and consistency with other code blocks in the document.
📝 Proposed fix
-``` +```text ├── src/ │ ├── Runner.ts # Main orchestrator: loads modules, manages lifecycle
772-802: Add language specifier to initialization flow code block.The initialization flow pseudo-code block should have a language specifier for consistency.
📝 Proposed fix
-``` +```text 1. new Runner(cwd, options) ├── Read module references from cwd
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CLAUDE.md
🧰 Additional context used
🧠 Learnings (11)
📓 Common learnings
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.408Z
Learning: Use 'eggjs/tegg/helper' for internal APIs like ModuleConfigUtil, LoaderFactory, and EggObjectLifeCycleContext in advanced usage scenarios
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.407Z
Learning: Applies to core/tegg/index.ts : Re-export core decorator, runtime, and type functionality from the main 'eggjs/tegg' package index.ts
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.408Z
Learning: Create new tegg framework features in the order: core/types → core/*-decorator → core/*-runtime → core/tegg → plugin/*
📚 Learning: 2026-01-10T12:35:11.407Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.407Z
Learning: Applies to core/tegg/index.ts : Re-export core decorator, runtime, and type functionality from the main 'eggjs/tegg' package index.ts
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.408Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.408Z
Learning: Use 'eggjs/tegg/helper' for internal APIs like ModuleConfigUtil, LoaderFactory, and EggObjectLifeCycleContext in advanced usage scenarios
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.408Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.408Z
Learning: Create subpath exports in 'eggjs/tegg' for optional features (aop, orm, dal, schedule, transaction, ajv, helper, standalone)
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.407Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.407Z
Learning: Applies to plugin/**/*.test.{ts,js} : Use 'egg-mock' with 'app.mockModuleContextScope()' for testing plugin modules in isolation
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.408Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.408Z
Learning: Always import decorators, enums, and public APIs from 'eggjs/tegg' in application code
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.407Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.407Z
Learning: Applies to plugin/**/*.{ts,tsx} : Framework internal code in plugin packages should import types from 'eggjs/tegg-types' and decorators from 'eggjs/core-decorator'
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.408Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.408Z
Learning: Plugin packages must include 'eggPlugin' and 'eggModule' configuration in package.json
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.408Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.408Z
Learning: Create new tegg framework features in the order: core/types → core/*-decorator → core/*-runtime → core/tegg → plugin/*
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.407Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.407Z
Learning: Applies to plugin/*/app.ts : Register prototype lifecycle hooks in plugin 'app.ts' using 'app.eggPrototypeLifecycleUtil.registerLifecycle()'
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-10T12:35:11.407Z
Learnt from: CR
Repo: eggjs/tegg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-10T12:35:11.407Z
Learning: Applies to core/**/*.{ts,tsx} : Framework internal code in core packages should import types from 'eggjs/tegg-types' and decorators from 'eggjs/core-decorator'
Applied to files:
CLAUDE.md
🪛 LanguageTool
CLAUDE.md
[grammar] ~742-~742: Ensure spelling is correct
Context: ...orks without Egg.js. This enables using tegg's dependency injection in CLI tools, back...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
CLAUDE.md
744-744: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
772-772: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ 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). (7)
- GitHub Check: Runner-ubuntu (20)
- GitHub Check: Runner-ubuntu (16)
- GitHub Check: Runner-macos (16)
- GitHub Check: Analyze (javascript)
- GitHub Check: Runner-ubuntu (18)
- GitHub Check: Runner-macos (20)
- GitHub Check: Runner-macos (18)
🔇 Additional comments (3)
CLAUDE.md (3)
804-853: Well-documented context management and inner objects mechanism.The explanation of AsyncLocalStorage-based context management and inner objects pattern is clear, technically accurate, and provides practical examples that will help developers understand how standalone mode differs from Egg.js mode.
891-891: Verify import path consistency.Line 891 imports from
'@eggjs/tegg-standalone', but this should likely be'@eggjs/tegg/standalone'based on the subpath pattern used elsewhere in the documentation (line 121) and other examples in this section.
954-976: Clear guidance for standalone-compatible plugins.The documentation provides clear, actionable guidance for creating plugins that work in both Egg.js and standalone modes. The distinction between
eggPluginandeggModuleis well-explained, and the best practices align well with the framework's dependency injection philosophy.
| } | ||
|
|
||
| // Run it | ||
| import { main } from '@eggjs/tegg-standalone'; |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check the main tegg package.json for exports configuration
find . -path "*/core/tegg/package.json" -o -path "*/tegg/package.json" | head -5 | xargs cat 2>/dev/null | grep -A 30 '"exports"' | head -40Repository: eggjs/tegg
Length of output: 36
🏁 Script executed:
#!/bin/bash
# Also check if there's a standalone package directory
find . -type d -name "standalone" | grep -v node_modulesRepository: eggjs/tegg
Length of output: 90
🏁 Script executed:
#!/bin/bash
# Check CLAUDE.md content around lines 882 and other import examples
sed -n '875,895p' CLAUDE.md
echo "---"
sed -n '855,870p' CLAUDE.md
echo "---"
sed -n '920,950p' CLAUDE.mdRepository: eggjs/tegg
Length of output: 1643
🏁 Script executed:
#!/bin/bash
# Search for package.json files and check their exports
find . -name "package.json" -type f | grep -E "(core/tegg|root)" | head -10 | xargs cat | grep -B5 -A50 '"exports"' | head -100Repository: eggjs/tegg
Length of output: 36
🏁 Script executed:
#!/bin/bash
# Try looking at the root package.json specifically
cat package.json | grep -A 50 '"exports"'Repository: eggjs/tegg
Length of output: 36
🏁 Script executed:
#!/bin/bash
# Check if there's a package.json in the standalone directory
if [ -f "./standalone/package.json" ]; then
cat ./standalone/package.json | head -20
fiRepository: eggjs/tegg
Length of output: 36
🏁 Script executed:
#!/bin/bash
# List root directory and common package locations
ls -la | head -20Repository: eggjs/tegg
Length of output: 1231
🏁 Script executed:
#!/bin/bash
# Find all package.json files
find . -name "package.json" -type f 2>/dev/null | head -20Repository: eggjs/tegg
Length of output: 1239
🏁 Script executed:
#!/bin/bash
# Check the standalone package.json if it exists
cat ./standalone/package.json 2>/dev/null || echo "File not found"Repository: eggjs/tegg
Length of output: 68
🏁 Script executed:
#!/bin/bash
# Search for actual imports in the codebase to see which pattern is used
rg '@eggjs/tegg-standalone|@eggjs/tegg/standalone' --type ts --type tsx -c | head -20Repository: eggjs/tegg
Length of output: 81
🏁 Script executed:
#!/bin/bash
# Find where standalone is located
find core plugin -type d -name "*standalone*" 2>/dev/nullRepository: eggjs/tegg
Length of output: 79
🏁 Script executed:
#!/bin/bash
# Check if standalone is a core package
ls -la core/ | grep standaloneRepository: eggjs/tegg
Length of output: 123
🏁 Script executed:
#!/bin/bash
# Look at CLAUDE.md line 121 area to see the subpaths list
sed -n '115,135p' CLAUDE.mdRepository: eggjs/tegg
Length of output: 606
🏁 Script executed:
#!/bin/bash
# Search for actual imports of both patterns in .ts files
rg '@eggjs/tegg-standalone|@eggjs/tegg/standalone' --type ts -A 2 | head -50Repository: eggjs/tegg
Length of output: 3676
🏁 Script executed:
#!/bin/bash
# Find all instances of both import patterns in CLAUDE.md
echo "=== Imports with SLASH (correct) ==="
rg '@eggjs/tegg/standalone' CLAUDE.md -n
echo ""
echo "=== Imports with HYPHEN (incorrect) ==="
rg '@eggjs/tegg-standalone' CLAUDE.md -nRepository: eggjs/tegg
Length of output: 496
🏁 Script executed:
#!/bin/bash
# Show the context around the examples to understand the scope
sed -n '850,860p' CLAUDE.md
echo "---"
sed -n '878,895p' CLAUDE.md
echo "---"
sed -n '918,932p' CLAUDE.md
echo "---"
sed -n '940,955p' CLAUDE.mdRepository: eggjs/tegg
Length of output: 1540
Fix import paths in standalone mode examples.
Lines 882, 891, 923, and 945 incorrectly import from '@eggjs/tegg-standalone' (with hyphen). The correct subpath format is '@eggjs/tegg/standalone' (with slash), which aligns with the documented subpaths list and the correct example at line 861. Update all four examples to use the slash format.
🤖 Prompt for AI Agents
In @CLAUDE.md at line 882, Update the incorrect imports that use the hyphenated
package name '@eggjs/tegg-standalone' to the correct subpath
'@eggjs/tegg/standalone' in all standalone-mode examples; specifically replace
occurrences that import symbols like "main" (and any other imports) from
'@eggjs/tegg-standalone' so they import from '@eggjs/tegg/standalone' instead.
Document how tegg runs without Egg.js using the standalone package, including initialization flow, context management via AsyncLocalStorage, inner objects mechanism, and usage examples.
Checklist
npm testpassesAffected core subsystem(s)
Description of change
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.