@@ -9,6 +9,7 @@ React on Rails is a Ruby gem and NPM package that seamlessly integrates React co
99## Essential Development Commands
1010
1111### Setup
12+
1213``` bash
1314# Initial setup for gem development
1415bundle && yarn
@@ -21,6 +22,7 @@ bundle exec lefthook install
2122```
2223
2324### Testing
25+
2426``` bash
2527# All tests (excluding examples) - recommended for local development
2628rake all_but_examples
@@ -41,6 +43,7 @@ VERBOSE=true rake react_on_rails:doctor # Detailed output
4143```
4244
4345### Linting & Formatting (CRITICAL BEFORE EVERY COMMIT)
46+
4447``` bash
4548# Auto-fix all violations (RECOMMENDED workflow)
4649rake autofix # Runs eslint --fix, prettier --write, and rubocop -A
@@ -56,6 +59,7 @@ yarn start format.listDifferent
5659```
5760
5861### Building
62+
5963``` bash
6064# Build NPM package (TypeScript → JavaScript)
6165yarn run build # One-time build
@@ -66,6 +70,7 @@ yarn run type-check
6670```
6771
6872### Development Server (Dummy App)
73+
6974``` bash
7075cd spec/dummy
7176
@@ -79,6 +84,7 @@ bin/dev prod # Production-like environment
7984```
8085
8186### Local Testing with Yalc
87+
8288``` bash
8389# In react_on_rails directory
8490yarn run build
@@ -113,6 +119,7 @@ yarn # Update dependencies
113119This project maintains two distinct but integrated packages:
114120
115121#### Ruby Gem (` lib/ ` )
122+
116123- ** Purpose:** Rails integration and server-side rendering
117124- ** Key Components:**
118125 - ` helper.rb ` - Rails view helpers (` react_component ` , etc.)
@@ -123,6 +130,7 @@ This project maintains two distinct but integrated packages:
123130 - Generators in ` lib/generators/react_on_rails/ `
124131
125132#### NPM Package (` node_package/src/ ` )
133+
126134- ** Purpose:** Client-side React integration
127135- ** Key Components:**
128136 - ` ReactOnRails.ts ` - Main entry point for client-side functionality
@@ -148,35 +156,41 @@ This project maintains two distinct but integrated packages:
148156### Key Architectural Patterns
149157
150158#### Server-Side Rendering
159+
151160- Uses isolated Node.js processes via ` connection_pool `
152161- Separate server bundles can be configured for SSR-specific code
153162- React Server Components (RSC) support in Pro version
154163
155164#### Auto-Bundling
165+
156166- File-system-based automatic bundle generation
157167- Components in designated directories are auto-discovered
158168- Eliminates manual ` javascript_pack_tags ` configuration
159169- See ` packs_generator.rb ` for implementation
160170
161171#### Component Registration
172+
162173- Manual: ` ReactOnRails.register({ ComponentName }) ` in pack files
163174- Auto: Components auto-registered via ` auto_load_bundle: true ` option
164175
165176## Testing & Examples
166177
167178### Dummy App (` spec/dummy/ ` )
179+
168180- Full Rails app for integration testing
169181- Examples of various React on Rails features
170182- Uses Shakapacker for webpack configuration
171183- Includes SSR, Redux, React Router examples
172184
173185### Generated Examples (` gen-examples/ ` )
186+
174187- Created via ` rake shakapacker_examples:gen_all `
175188- Ignored by git
176189- Used for comprehensive generator testing
177190- Should be excluded from IDE to prevent slowdown
178191
179192### Important Test Patterns
193+
180194- Use ` yalc ` for local package testing, not ` npm link `
181195- Always run ` yalc push ` after changes to see updates in test apps
182196- Test both with/without Shakapacker pre-installed
@@ -185,6 +199,7 @@ This project maintains two distinct but integrated packages:
185199## Common Development Workflows
186200
187201### Making Code Changes
202+
1882031 . Make changes to Ruby or TypeScript code
1892042 . For NPM changes: ` yarn run build ` or ` yarn run build-watch `
1902053 . For Yalc testing: ` yalc push `
@@ -193,13 +208,15 @@ This project maintains two distinct but integrated packages:
1932086 . Commit changes
194209
195210### Fixing Bugs
211+
1962121 . Create failing test that reproduces issue
1972132 . Implement minimal fix
1982143 . Ensure all tests pass
1992154 . Run linting: ` bundle exec rubocop ` and ` yarn run lint `
2002165 . Update documentation if needed
201217
202218### Adding Features
219+
2032201 . Plan implementation (use TODO list for complex tasks)
2042212 . Write tests first (TDD)
2052223 . Implement feature
@@ -208,6 +225,7 @@ This project maintains two distinct but integrated packages:
2082256 . Update relevant documentation
209226
210227### Testing Generator Changes
228+
211229``` bash
212230# Create test Rails app
213231rails new test-app --skip-javascript
@@ -233,11 +251,13 @@ bin/dev
233251** Prettier is the SOLE authority for non-Ruby files. RuboCop is the SOLE authority for Ruby files.**
234252
235253### Standard Workflow
254+
2362551 . Make code changes
2372562 . Run ` rake autofix `
2382573 . Commit
239258
240259### Merge Conflict Resolution
260+
2412611 . Resolve logical conflicts only (don't manually format)
2422622 . ` git add . `
2432633 . ` rake autofix `
@@ -249,18 +269,22 @@ bin/dev
249269## RuboCop Common Issues
250270
251271### Trailing Whitespace
272+
252273Remove all trailing whitespace from lines
253274
254275### Line Length (120 chars max)
276+
255277Break long lines into multiple lines using proper indentation
256278
257279### Named Subjects (RSpec)
280+
258281``` ruby
259282# Good
260283subject(:method_result ) { instance.method_name(arg) }
261284```
262285
263286### Security/Eval Violations
287+
264288``` ruby
265289# rubocop:disable Security/Eval
266290# ... code with eval
@@ -270,6 +294,7 @@ subject(:method_result) { instance.method_name(arg) }
270294## IDE Configuration
271295
272296** Exclude these directories to prevent IDE slowdowns:**
297+
273298- ` /coverage ` , ` /tmp ` , ` /gen-examples `
274299- ` /node_package/lib ` , ` /node_modules `
275300- ` /spec/dummy/app/assets/webpack `
@@ -279,16 +304,19 @@ subject(:method_result) { instance.method_name(arg) }
279304## Important Constraints
280305
281306### Package Manager
307+
282308- ** ONLY use Yarn Classic (1.x)** - never use npm
283309- Package manager enforced via ` packageManager ` field in package.json
284310
285311### Dependencies
312+
286313- Shakapacker >= 6.0 required (v16+ drops Webpacker support)
287314- Ruby >= 3.0
288315- Node.js >= 18 (tested: 18-22)
289316- Rails >= 5.2
290317
291318### Pro Features
319+
292320- React Server Components (RSC)
293321- Streaming SSR
294322- Loadable Components
@@ -298,30 +326,35 @@ subject(:method_result) { instance.method_name(arg) }
298326## Troubleshooting
299327
300328### React Components Not Rendering
329+
301330- Ensure yalc setup is complete
302331- Run ` yalc push ` after changes
303332- Check browser console for errors
304333- Verify component is registered correctly
305334
306335### Generator Issues
336+
307337- Run ` rake react_on_rails:doctor `
308338- Check Shakapacker is properly installed
309339- Ensure package.json exists
310340- Test with ` bin/dev kill ` to stop conflicting processes
311341
312342### Test Failures
343+
313344- Run tests from correct directory (project root vs spec/dummy)
314345- Check that ` bundle install ` and ` yarn install ` are current
315346- Verify git hooks are installed: ` bundle exec lefthook install `
316347
317348### Linting Failures
349+
318350- ** Always run ` bundle exec rubocop ` before pushing**
319351- Use ` rake autofix ` to fix most issues automatically
320352- Check ` .rubocop.yml ` for project-specific rules
321353
322354## Monorepo Merger (In Progress)
323355
324356The project is merging ` react_on_rails ` and ` react_on_rails_pro ` into a unified monorepo. During this transition:
357+
325358- Continue contributing to current structure
326359- License compliance is critical (no Pro code in MIT areas)
327360- See ` docs/MONOREPO_MERGER_PLAN_REF.md ` for details
0 commit comments