191 lines
5.2 KiB
Markdown
191 lines
5.2 KiB
Markdown
---
|
|
date: 2026-01-05T07:06:33Z
|
|
researcher: Claude
|
|
git_commit: 43305a562cfba914654da056b0a7e03c40849678
|
|
branch: develop
|
|
repository: medusa-core
|
|
topic: "CLAUDE.md File Creation Research"
|
|
tags: [research, codebase, claude-md, documentation, conventions]
|
|
status: complete
|
|
last_updated: 2026-01-05
|
|
last_updated_by: Claude
|
|
---
|
|
|
|
# Research: CLAUDE.md File Creation for Medusa Core
|
|
|
|
**Date**: 2026-01-05T07:06:33Z
|
|
**Researcher**: Claude
|
|
**Git Commit**: 43305a562cfba914654da056b0a7e03c40849678
|
|
**Branch**: develop
|
|
**Repository**: medusa-core
|
|
|
|
## Research Question
|
|
|
|
Research the Medusa Core codebase to gather information needed to create a CLAUDE.md file following Claude Code best practices. The file should be concise and focused.
|
|
|
|
## Summary
|
|
|
|
This research documents the Medusa Core monorepo structure, build system, testing conventions, and code style to enable creation of an effective CLAUDE.md file. Key findings:
|
|
|
|
- **Monorepo**: Yarn 3 workspaces with Turbo orchestration
|
|
- **Stack**: Node.js 20+, TypeScript 5.6.2, Express, MikroORM/PostgreSQL
|
|
- **30+ modules**: Product, Order, Cart, Payment, Fulfillment, etc.
|
|
- **Admin**: React 18 dashboard with Vite
|
|
- **Testing**: Jest for backend, Vitest for frontend
|
|
|
|
## Detailed Findings
|
|
|
|
### 1. Codebase Structure
|
|
|
|
**Monorepo Organization:**
|
|
```
|
|
/packages/
|
|
├── medusa/ # Main Medusa package
|
|
├── core/ # Core framework packages
|
|
│ ├── framework/ # Core runtime
|
|
│ ├── types/ # TypeScript definitions
|
|
│ ├── utils/ # Utilities
|
|
│ ├── workflows-sdk/ # Workflow composition
|
|
│ ├── core-flows/ # Predefined workflows
|
|
│ └── modules-sdk/ # Module development
|
|
├── modules/ # 30+ commerce modules
|
|
│ ├── product/, order/, cart/, payment/...
|
|
│ └── providers/ # 15+ provider implementations
|
|
├── admin/ # Dashboard packages
|
|
│ └── dashboard/ # React admin UI
|
|
├── cli/ # CLI tools
|
|
└── design-system/ # UI components
|
|
/integration-tests/ # Full-stack tests
|
|
/www/ # Documentation site
|
|
```
|
|
|
|
**Key Directories:**
|
|
- `packages/core/framework/` - Core runtime, HTTP, database
|
|
- `packages/medusa/src/api/` - API routes
|
|
- `packages/modules/` - Commerce feature modules
|
|
- `packages/admin/dashboard/` - Admin React app
|
|
|
|
### 2. Build System & Commands
|
|
|
|
**Package Manager**: Yarn 3.2.1 with node-modules linker
|
|
|
|
**Essential Commands:**
|
|
```bash
|
|
# Install dependencies
|
|
yarn install
|
|
|
|
# Build all packages
|
|
yarn build
|
|
|
|
# Build specific package
|
|
yarn workspace @medusajs/medusa build
|
|
|
|
# Watch mode (in package directory)
|
|
yarn watch
|
|
|
|
# Lint
|
|
yarn lint
|
|
|
|
# Format
|
|
yarn prettier --write <files>
|
|
```
|
|
|
|
**Testing Commands:**
|
|
```bash
|
|
# All unit tests
|
|
yarn test
|
|
|
|
# Package integration tests
|
|
yarn test:integration:packages
|
|
|
|
# HTTP integration tests
|
|
yarn test:integration:http
|
|
|
|
# API integration tests
|
|
yarn test:integration:api
|
|
|
|
# Module integration tests
|
|
yarn test:integration:modules
|
|
```
|
|
|
|
### 3. Testing Conventions
|
|
|
|
**Frameworks:**
|
|
- Jest 29.7.0 (backend/core)
|
|
- Vitest 3.0.5 (admin/frontend)
|
|
|
|
**Test Locations:**
|
|
- Unit tests: `__tests__/` directories alongside source
|
|
- Module integration tests: `packages/*/integration-tests/__tests__/`
|
|
- HTTP integration tests: `integration-tests/http/__tests__/`
|
|
|
|
**Test Runners:**
|
|
- `medusaIntegrationTestRunner` - HTTP integration tests
|
|
- `moduleIntegrationTestRunner` - Module integration tests
|
|
- Both from `@medusajs/test-utils`
|
|
|
|
**Patterns:**
|
|
- File extension: `.spec.ts` or `.test.ts`
|
|
- Unit test structure: `describe/it` blocks
|
|
- Integration tests: Use custom test runners with DB setup
|
|
|
|
### 4. Code Style Conventions
|
|
|
|
**Formatting (Prettier):**
|
|
- No semicolons
|
|
- Double quotes
|
|
- 2 space indentation
|
|
- ES5 trailing commas
|
|
- Always use parens in arrow functions
|
|
|
|
**TypeScript:**
|
|
- Target: ES2021
|
|
- Module: Node16
|
|
- Strict null checks enabled
|
|
- Decorators enabled (experimental)
|
|
|
|
**Naming Conventions:**
|
|
- Files: kebab-case (`define-config.ts`)
|
|
- Types/Interfaces/Classes: PascalCase
|
|
- Functions/Variables: camelCase
|
|
- Constants: SCREAMING_SNAKE_CASE
|
|
- DB fields: snake_case
|
|
|
|
**Import Organization:**
|
|
1. @medusajs/framework imports (grouped by subpath)
|
|
2. External npm packages
|
|
3. Node.js built-ins
|
|
4. Relative local imports
|
|
|
|
**Export Patterns:**
|
|
- Barrel exports via `export * from`
|
|
- Named re-exports for specific items
|
|
|
|
## Code References
|
|
|
|
- Root package.json: `package.json`
|
|
- ESLint config: `.eslintrc.js`
|
|
- Prettier config: `.prettierrc`
|
|
- TypeScript base: `_tsconfig.base.json`
|
|
- Turbo config: `turbo.json`
|
|
- Contributing guide: `CONTRIBUTING.md`
|
|
- Jest config: `jest.config.js`
|
|
- Yarn config: `.yarnrc.yml`
|
|
|
|
## Recommended CLAUDE.md Structure
|
|
|
|
Based on research, the CLAUDE.md should include:
|
|
|
|
1. **Project Overview** - Brief description of Medusa as commerce platform
|
|
2. **Quick Commands** - Build, test, lint commands
|
|
3. **Code Style** - Key formatting/naming conventions
|
|
4. **Architecture Notes** - Module system, workflows, admin
|
|
5. **Testing** - How to run tests, test patterns
|
|
6. **Key Directories** - Where to find important code
|
|
|
|
Keep each section to 3-5 bullet points maximum for conciseness.
|
|
|
|
## Open Questions
|
|
|
|
None - sufficient information gathered for CLAUDE.md creation.
|