medusa-store/thoughts/shared/research/2026-01-05-claude-md-research.md

date, researcher, git_commit, branch, repository, topic, tags, status, last_updated, last_updated_by

date	researcher	git_commit	branch	repository	topic	tags	status	last_updated	last_updated_by
2026-01-05T07:06:33Z	Claude	43305a562c	develop	medusa-core	CLAUDE.md File Creation Research	research codebase claude-md documentation conventions	complete	2026-01-05	Claude

Research: CLAUDE.md File Creation for Medusa Core

Date: 2026-01-05T07:06:33Z Researcher: Claude Git Commit: 43305a562c 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:

# 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:

# 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.