Skip to content

Commit ee3c772

Browse files
codemonkey800claude
codemonkey800
and
claude
authored
feat: added frontend CLAUDE.md (#1867)
* added frontend CLAUDE.md * format CLAUDE.md with prettier * create-pr command * docs: add create-commits command and update create-pr documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7d44e7f commit ee3c772

File tree

3 files changed

+380
-0
lines changed

3 files changed

+380
-0
lines changed

‎frontend/.claude/commands/create-commits.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Create Commits Command
2+
3+
This command automates the creation of logical, well-structured commits with intelligent grouping by function and descriptive messages, including code quality validation and proper branch management.
4+
5+
## Command Usage
6+
7+
- `create-commits` - Basic usage with current branch
8+
- `create-commits --base develop` - Create commits with custom base branch reference
9+
10+
### Flag Details
11+
12+
- `--base <branch-name>` - Specify the base branch for reference (default: main)
13+
- Useful when working with feature branches or dependent branches
14+
- Helps determine which changes are new since branching from base
15+
16+
## Workflow
17+
18+
### 1. Branch Management
19+
20+
- Check current branch name using `git branch --show-current`
21+
- Determine base branch (default: `main`, or value from `--base` flag)
22+
- Validate base branch exists: `git show-ref --verify refs/heads/<base-branch>` or `git ls-remote --heads origin <base-branch>`
23+
- If current branch is same as base branch:
24+
- Analyze staged and unstaged changes to determine scope
25+
- Create new branch with format: `<scope>/auto-<timestamp>-<short-description>`
26+
- Example: `feat/auto-20250625-dataset-metadata-updates`
27+
- If current branch is different from base branch:
28+
- Use existing branch for commit creation
29+
- Verify branch is not behind remote base branch: `git merge-base --is-ancestor origin/<base-branch> HEAD`
30+
31+
### 2. Pre-Commit Validation
32+
33+
Execute the following commands in sequence and stop if any fail:
34+
35+
- Run `pnpm lint` to check for linting issues
36+
- If linting fails, run `pnpm lint:fix` to auto-fix issues
37+
- Run `pnpm data-portal type-check` to verify TypeScript types
38+
- If type check fails, report specific errors and require manual fixes before proceeding
39+
40+
### 3. Change Analysis and Commit Splitting
41+
42+
Analyze all staged and unstaged changes to intelligently group them:
43+
44+
#### File Grouping Logic:
45+
46+
- **UI Components**: Group `*.tsx` files in `/components/` together
47+
- **GraphQL Operations**: Group `*.server.ts` files in `/graphql/` together
48+
- **Type Definitions**: Group `__generated_v2__/**/*.ts` files together
49+
- **Translations**: Group `translation.json` changes separately
50+
- **Configuration**: Group config files (`*.config.*`, `package.json`, etc.) together
51+
- **Tests**: Group test files (`*.test.*`, `*.spec.*`) together
52+
- **Documentation**: Group `*.md` files together
53+
54+
#### Commit Creation Strategy:
55+
56+
1. **Single Logical Changes**: Each commit should represent one cohesive change
57+
2. **Component-Based Grouping**: Changes to a component and its related files go together
58+
3. **Feature Boundaries**: Don't mix different features in the same commit
59+
4. **Dependency Order**: Commit dependencies (types, GraphQL) before dependents (components)
60+
61+
### 4. Commit Message Generation
62+
63+
For each commit group, generate messages using this format: `<scope>: <description>`
64+
65+
#### Scope Selection Rules:
66+
67+
- `feat`: New features, components, or major functionality additions
68+
- `fix`: Bug fixes, error corrections, or issue resolutions
69+
- `refactor`: Code restructuring without functional changes
70+
- `style`: CSS, styling, or visual updates
71+
- `docs`: Documentation updates or README changes
72+
- `test`: Adding or updating tests
73+
- `chore`: Maintenance, dependencies, or tooling updates
74+
- `perf`: Performance improvements
75+
- `build`: Build system or deployment changes
76+
- `ci`: Continuous integration configuration
77+
78+
#### Description Guidelines:
79+
80+
- Use present tense ("add" not "added")
81+
- Keep under 50 characters for the title
82+
- Be specific about what changed
83+
- Examples:
84+
- `feat: add dataset metadata display table`
85+
- `fix: resolve GraphQL type generation errors`
86+
- `refactor: extract reusable metadata components`
87+
88+
### 5. Commit Execution
89+
90+
For each commit group:
91+
92+
1. Stage only the files belonging to that group using `git add <files>`
93+
2. Create commit with generated message
94+
3. Verify commit was created successfully
95+
4. Continue to next group
96+
97+
## Error Handling
98+
99+
### Lint Failures:
100+
101+
- Attempt auto-fix with `pnpm lint:fix`
102+
- If still failing, list specific errors and pause for manual resolution
103+
104+
### Type Check Failures:
105+
106+
- Display TypeScript errors clearly
107+
- Require manual fixes before proceeding
108+
- Suggest running `pnpm data-portal build:codegen` if GraphQL types are stale
109+
110+
### Git Conflicts:
111+
112+
- If branch is behind base branch, suggest rebasing first: `git rebase origin/<base-branch>`
113+
- If conflicts exist, pause and request manual resolution
114+
115+
### Base Branch Validation:
116+
117+
- If specified base branch doesn't exist locally or remotely, list available branches and exit
118+
- If current branch is the same as base branch, require creation of new branch first
119+
- If base branch is not accessible, suggest fetching: `git fetch origin <base-branch>`
120+
121+
### Empty Changes:
122+
123+
- If no staged or unstaged changes exist, inform user and exit gracefully
124+
125+
## Success Confirmation
126+
127+
After successful commit creation:
128+
129+
1. Display summary of commits created with messages
130+
2. Show branch status and commit count
131+
3. Confirm all validation checks passed
132+
133+
## Advanced Features
134+
135+
### Commit Message Enhancement:
136+
137+
- Analyze file diffs to understand the nature of changes
138+
- Include relevant component names or feature areas
139+
140+
### Quality Gates:
141+
142+
- Ensure all commits have proper conventional format
143+
- Verify no sensitive information is being committed
144+
- Check that commit messages are descriptive and meaningful
145+
146+
### Base Branch Validation Requirements:
147+
148+
1. **Branch Existence Check**: Verify base branch exists using `git show-ref --verify refs/heads/<base-branch>` (local) or `git ls-remote --heads origin <base-branch>` (remote)
149+
2. **Branch Accessibility**: Ensure base branch is up-to-date with remote: `git fetch origin <base-branch>`
150+
3. **Self-Reference Prevention**: Prevent creating commits when current branch equals base branch without creating new branch first
151+
4. **Branch Relationship Validation**: Check if current branch has diverged from base branch using `git merge-base <base-branch> HEAD`
152+
153+
## Workflow Summary
154+
155+
1. **Validate Environment**: Check branch status and base branch
156+
2. **Quality Validation**: Run linting and type checking
157+
3. **Analyze Changes**: Group files logically by function and feature
158+
4. **Generate Messages**: Create descriptive conventional commit messages
159+
5. **Execute Commits**: Create commits in logical order with proper staging
160+
6. **Confirm Success**: Validate all commits were created successfully

‎frontend/.claude/commands/create-pr.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Create Pull Request Command
2+
3+
This command automates the creation of pull requests from existing commits. It should be used after running `/create-commits` to create logical commits.
4+
5+
## Command Usage
6+
7+
- `create-pr` - Basic usage with current branch (merges to main)
8+
- `create-pr --draft` - Create PR in draft mode
9+
- `create-pr --issue 123` - Link PR to issue #123
10+
- `create-pr --base develop` - Create PR with custom base branch
11+
- `create-pr --draft --issue 123` - Combine draft and issue flags
12+
- `create-pr --base feature-abc --draft --issue 123` - Full example with all flags
13+
14+
### Flag Details
15+
16+
- `--base <branch-name>` - Specify the base branch to merge into (default: main)
17+
- Useful for creating PRs against feature branches or when working with dependent branches
18+
- Helps create cleaner diffs by avoiding commits from unrelated features
19+
- `--draft` - Create PR in draft mode
20+
- `--issue <number>` - Link PR to issue number
21+
22+
## Prerequisites
23+
24+
This command expects that `/create-commits` has been run first to create logical commits. The workflow will:
25+
26+
1. Verify that the current branch has commits to push
27+
2. Check if commits exist that haven't been pushed to remote
28+
3. Proceed with PR creation if commits are available
29+
30+
## Workflow
31+
32+
### 1. Branch and Commit Validation
33+
34+
- Check current branch name using `git branch --show-current`
35+
- Determine base branch (default: `main`, or value from `--base` flag)
36+
- Validate base branch exists: `git show-ref --verify refs/heads/<base-branch>` or `git ls-remote --heads origin <base-branch>`
37+
- Verify current branch is different from base branch
38+
- Check for unpushed commits using `git log origin/<current-branch>..HEAD` or `git rev-list --count @{u}..HEAD`
39+
- If no unpushed commits exist, inform user and exit
40+
41+
### 2. Branch Push and PR Creation
42+
43+
- Check if branch exists on remote: `git ls-remote --heads origin <branch-name>`
44+
- If branch doesn't exist on remote OR has unpushed commits, push: `git push -u origin <branch-name>`
45+
- Analyze existing commit messages to determine primary scope and generate PR title
46+
- Create PR body with:
47+
- **Summary**: Brief overview of changes made (derived from commit messages)
48+
- **Changes**: Bullet list of major modifications (from commit history)
49+
- **Testing**: Instructions for testing the changes
50+
- **Issue Link**: If `--issue` flag provided, add "Closes #<number>"
51+
52+
#### PR Title Generation:
53+
54+
- Analyze commit messages from `git log <base-branch>..HEAD --oneline`
55+
- Extract primary scope from most recent or most significant commit
56+
- Use format: `<primary-scope>: <concise-description>`
57+
- Example: `feat: add dataset metadata display functionality`
58+
59+
#### PR Creation Command:
60+
61+
```bash
62+
gh pr create \
63+
--title "<scope>: <title>" \
64+
--body "<generated-body>" \
65+
$(if draft flag: --draft) \
66+
--head <branch-name> \
67+
--base <base-branch>
68+
```
69+
70+
Where `<base-branch>` is determined by:
71+
- Value from `--base` flag if provided
72+
- Default to `main` if no `--base` flag specified
73+
74+
## Error Handling
75+
76+
### No Commits to Push:
77+
78+
- If current branch has no unpushed commits, inform user to run `/create-commits` first
79+
- Exit gracefully with instructions
80+
81+
### Git Conflicts:
82+
83+
- If branch is behind base branch, suggest rebasing first: `git rebase origin/<base-branch>`
84+
- If conflicts exist, pause and request manual resolution
85+
86+
### Base Branch Validation:
87+
88+
- If specified base branch doesn't exist locally or remotely, list available branches and exit
89+
- If current branch is the same as base branch, inform user they need to create commits on a feature branch first
90+
- If base branch is not accessible, suggest fetching: `git fetch origin <base-branch>`
91+
92+
### Push Failures:
93+
94+
- If push fails due to authentication issues, provide GitHub CLI setup instructions
95+
- If push is rejected due to branch protection rules, inform user and suggest draft PR creation
96+
97+
## Success Confirmation
98+
99+
After successful PR creation:
100+
101+
1. Display PR URL
102+
2. Show commit summary with messages (from git log)
103+
3. Confirm if created as draft (if applicable)
104+
4. Show linked issue number (if applicable)
105+
5. Display instructions for next steps (review process, testing, etc.)
106+
107+
## Advanced Features
108+
109+
### PR Body Generation:
110+
111+
- Parse commit messages to extract meaningful summary
112+
- Group related commits to describe feature scope
113+
- Include testing instructions based on changed files
114+
115+
### Base Branch Validation Requirements:
116+
117+
1. **Branch Existence Check**: Verify base branch exists using `git show-ref --verify refs/heads/<base-branch>` (local) or `git ls-remote --heads origin <base-branch>` (remote)
118+
2. **Branch Accessibility**: Ensure base branch is up-to-date with remote: `git fetch origin <base-branch>`
119+
3. **Self-Reference Prevention**: Prevent creating PR where current branch equals base branch
120+
4. **Branch Relationship Validation**: Check if current branch has diverged from base branch using `git merge-base <base-branch> HEAD`
121+
122+
## Workflow Summary
123+
124+
1. **Validate Prerequisites**: Ensure commits exist and branch is ready for PR
125+
2. **Push Branch**: Push to origin only if necessary (new branch or unpushed commits)
126+
3. **Generate PR Content**: Create title and body from existing commit history
127+
4. **Create PR**: Use GitHub CLI to create pull request with proper flags
128+
5. **Confirm Success**: Display PR details and next steps

‎frontend/CLAUDE.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Development Commands
6+
7+
### Setup
8+
9+
- Use pnpm for package management (required, enforced by preinstall script)
10+
- Install dependencies: `pnpm install`
11+
- Node.js version defined in `.nvmrc` (use `nvm use`)
12+
13+
### Core Development
14+
15+
- Start dev server: `pnpm dev` (runs data-portal dev server with codegen and hot reload)
16+
- Build all packages: `pnpm build`
17+
- Clean builds: `pnpm clean`
18+
19+
### Data Portal Package Commands
20+
21+
Run these from the data-portal package or use `pnpm data-portal <command>`:
22+
23+
- Dev server: `pnpm data-portal dev`
24+
- Production build: `pnpm data-portal build`
25+
- Generate GraphQL types: `pnpm data-portal build:codegen`
26+
- Watch GraphQL codegen: `pnpm data-portal dev:codegen`
27+
28+
### Testing & Quality
29+
30+
- Run tests: `pnpm test` (Jest with coverage)
31+
- Watch tests: `pnpm data-portal test:watch`
32+
- E2E tests: `pnpm data-portal e2e` (Playwright)
33+
- E2E debug mode: `pnpm data-portal e2e:debug`
34+
- Lint all: `pnpm lint`
35+
- Fix linting: `pnpm lint:fix`
36+
- Type check: `pnpm data-portal type-check`
37+
38+
## Architecture Overview
39+
40+
### Monorepo Structure
41+
42+
- **packages/data-portal**: Main CryoET Data Portal web application (Remix + React)
43+
- **packages/eslint-config**: Shared ESLint configuration
44+
- **packages/eslint-plugin**: Custom ESLint rules
45+
46+
### Technology Stack
47+
48+
- **Framework**: Remix (React-based full-stack framework)
49+
- **Styling**: Tailwind CSS + CSS Modules + Material-UI + Emotion
50+
- **GraphQL**: Apollo Client with code generation
51+
- **State Management**: Jotai (atomic state management)
52+
- **Testing**: Jest (unit) + Playwright (E2E)
53+
- **Internationalization**: i18next/react-i18next
54+
55+
### GraphQL Integration
56+
57+
- Uses Apollo Client with server-side rendering support
58+
- GraphQL schema codegen generates types in `app/__generated_v2__/`
59+
- Queries are colocated with components/routes in `app/graphql/`
60+
- Schema URL: configured via `API_URL_V2` environment variable
61+
62+
### File Organization
63+
64+
- **app/routes/**: Remix route components and loaders
65+
- **app/components/**: Reusable React components
66+
- **app/graphql/**: GraphQL queries and fragments
67+
- **app/hooks/**: Custom React hooks
68+
- **app/utils/**: Utility functions and helpers
69+
- **app/constants/**: Application constants
70+
- **app/types/**: TypeScript type definitions
71+
- **e2e/**: Playwright end-to-end tests
72+
73+
### Key Patterns
74+
75+
- Route-based data loading with Remix loaders
76+
- Component-driven architecture with shared design system (@czi-sds/components)
77+
- GraphQL queries use typed document nodes with fragment masking disabled
78+
- Internationalization keys follow hierarchical structure in translation.json
79+
- CSS Modules for component-specific styles, Tailwind for utilities
80+
81+
### Development Workflow
82+
83+
1. GraphQL codegen runs automatically during dev and must complete before other processes
84+
2. Hot reload enabled for both client and server code
85+
3. TypeScript compilation happens via ts-node for server, Remix handles client compilation
86+
4. CSS Modules type definitions generated automatically via typed-css-modules
87+
88+
### Environment Configuration
89+
90+
- Environment variables injected via root loader for client-side access
91+
- Supports multiple environments (dev, staging, prod) via ENV variable
92+
- Plausible analytics integration with environment-specific domains

0 commit comments

Comments
 (0)