Update preinstall script to enable use as a Git dependency

CHANGELOG.md

@@ -29,6 +29,10 @@ Changes since the last non-beta release.
 
 - **Improved Error Messages**: Error messages for version mismatches and package configuration issues now include package-manager-specific installation commands (npm, yarn, pnpm, bun). [PR #1881](https://github.com/shakacode/react_on_rails/pull/1881) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 
+#### Bug Fixes
+
+- **Use as Git dependency**: All packages can now be installed as Git dependencies. This is useful for development and testing purposes. See [CONTRIBUTING.md](./CONTRIBUTING.md#git-dependencies) for documentation. [PR #1873](https://github.com/shakacode/react_on_rails/pull/1873) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
+
 #### Breaking Changes
 
 - **React on Rails Core Package**: Several Pro-only methods have been removed from the core package and are now exclusively available in the `react-on-rails-pro` package. If you're using any of the following methods, you'll need to migrate to React on Rails Pro:
@@ -1777,7 +1781,7 @@ such as:
 
 - Fix several generator-related issues.
 
-[Unreleased]: https://github.com/shakacode/react_on_rails/compare/16.1.1...master
+[unreleased]: https://github.com/shakacode/react_on_rails/compare/16.1.1...master
 [16.1.1]: https://github.com/shakacode/react_on_rails/compare/16.1.0...16.1.1
 [16.1.0]: https://github.com/shakacode/react_on_rails/compare/16.0.0...16.1.0
 [16.0.0]: https://github.com/shakacode/react_on_rails/compare/14.2.0...16.0.0

CONTRIBUTING.md

@@ -49,59 +49,68 @@ It's critical to configure your IDE/editor to ignore certain directories. Otherw
 - /spec/dummy/tmp
 - /spec/react_on_rails/dummy-for-generators
 
-# Configuring your test app to use your local fork
+# Example apps
 
-You can test the `react-on-rails` gem using your own external test app or the gem's internal `spec/dummy` app. The `spec/dummy` app is an example of the various setup techniques you can use with the gem.
+The [`spec/dummy` app](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy) is an example of the various setup techniques you can use with the gem.
 
-```text
-├── test_app
-|    └── client
-└── react_on_rails
-    └── spec
-        └── dummy
-```
+There are also two such apps for React on Rails Pro: [one using the Node renderer](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy) and [one using ExecJS](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/execjs-compatible-dummy).
+
+When you add a new feature, consider adding an example demonstrating it to the example apps.
+
+# Testing your changes in an external application
+
+You may also want to test your React on Rails changes with your own application.
+There are three main ways to do it: using local dependencies, Git dependencies, or tarballs.
+
+## Local version
 
-## Testing the Ruby Gem
+### Ruby
 
-If you want to test the ruby parts of the gem with an application before you release a new version of the gem, you can specify the path to your local version via your test app's Gemfile:
+To make your Rails app use a local version of our gems, use
 
 ```ruby
-gem "react_on_rails", path: "../path-to-react-on-rails"
+gem "react_on_rails", path: "<React on Rails root>"
 ```
 
-Note that you will need to bundle install after making this change, but also that **you will need to restart your Rails application if you make any changes to the gem**.
+and/or
 
-## Testing the Node package for React on Rails via Yalc
+```ruby
+gem "react_on_rails_pro", path: "<React on Rails root>/react_on_rails_pro"
+```
+
+Note that you will need to run `bundle install` after making this change, but also that **you will need to restart your Rails application if you make any changes to the gem**.
 
-In addition to testing the Ruby parts out, you can also test the Node package parts of the gem with an external application. First, be **sure** to build the NPM package:
+### JS
+
+First, be **sure** to build the NPM package:
 
 ```sh
-cd react_on_rails/
+cd <React on Rails root>
 yarn
 
 # Update the lib directory with babel compiled files
 yarn run build-watch
 ```
 
-You need to do this once:
+You need to do this once to make sure your app depends on our package:
 
-```
-# Will send the updates to other folders
+```shell
+cd <React on Rails root>/packages/react-on-rails
 yalc publish
-cd spec/dummy
+cd <your project root>
 yalc add react-on-rails
 ```
 
 The workflow is:
 
 1. Make changes to the node package.
-2. **CRITICAL**: Run yalc push to send updates to all linked apps:
+2. **CRITICAL**: Run `yalc push` to send updates to all linked apps:
 
-```
-cd <top dir>
+```shell
+cd <React on Rails root>/packages/react-on-rails
 # Will send the updates to other folders - MUST DO THIS AFTER ANY CHANGES
 yalc push
-cd spec/dummy
+cd <your project root>
 
 # Will update from yalc
 yarn
@@ -111,18 +120,77 @@ yarn
 
 When you run `yalc push`, you'll get an informative message
 
-```
-✗ yalc push
+```terminaloutput
+$ yalc push
 [email protected] published in store.
 Pushing [email protected] in /Users/justin/shakacode/react-on-rails/react_on_rails/spec/dummy
 Package [email protected] added ==> /Users/justin/shakacode/react-on-rails/react_on_rails/spec/dummy/node_modules/react-on-rails.
 Don't forget you may need to run yarn after adding packages with yalc to install/update dependencies/bin scripts.
 ```
 
-#### Example: Testing NPM changes with the dummy app
+Of course, you can do the same with `react-on-rails-pro` and `@shakacode-tools/react-on-rails-pro-node-renderer` packages.
+
+This is the approach `spec/dummy` apps use, so you can also look at their implementation.
+
+### Example: Testing NPM changes with the dummy app
+
+1. Add `console.log('Hello!')` to [clientStartup.ts, function render](https://github.com/shakacode/react_on_rails/blob/master/packages/react-on-rails/src/clientStartup.ts) in `/packages/react-on-rails/src/clientStartup.ts` to confirm we're getting an update to the node package client-side. Do the same for function `serverRenderReactComponent` in [/packages/react-on-rails/src/serverRenderReactComponent.ts](https://github.com/shakacode/react_on_rails/blob/master/packages/react-on-rails/src/serverRenderReactComponent.ts).
+2. Refresh the browser if the server is already running or start the server using `foreman start` from `react_on_rails/spec/dummy` and navigate to `http://localhost:3000/`. You will now see the `Hello!` message printed in the browser's console. If you did not see that message, then review the steps above for the workflow of making changes and pushing them via yalc.
+
+## Git dependencies
+
+If you push your local changes to Git, you can use them as dependencies as follows:
+
+### Ruby
+
+Adjust depending on the repo you pushed to and commit/branch you want to use, see [Bundler documentation](https://bundler.io/guides/git.html):
+
+```ruby
+gem 'react_on_rails',
+  git: 'https://github.com/shakacode/react_on_rails',
+  branch: 'master'
+gem 'react_on_rails_pro',
+  git: 'https://github.com/shakacode/react_on_rails',
+  glob: 'react_on_rails_pro/react_on_rails_pro.gemspec',
+  branch: 'master'
+```
+
+### JS
+
+Unfortunately, not all package managers allow depending on a single subfolder of a Git repo.
+The examples below are for the `master` branch of `react-on-rails` package.
+
+#### Yarn Berry
+
+See [Yarn Git protocol documentation](https://yarnpkg.com/protocol/git#workspaces-support).
+
+```shell
+yarn add "[email protected]:shakacode/react_on_rails.git#workspace=react-on-rails&head=master"
+```
+
+#### PNPM (starting from v9)
+
+See [this issue](https://github.com/pnpm/pnpm/issues/4765).
+
+```shell
+pnpm add "github:shakacode/react_on_rails/repo#master&path:packages/react-on-rails"
+```
+
+#### NPM
+
+[Explicitly doesn't want to support it.](https://github.com/npm/cli/issues/6253)
+
+## Tarball
+
+This method works only for JS packages, not for Ruby gems.
+
+Run `yarn pack` in the package you modified, copy the generated file into your app or upload it somewhere, and run
+
+```shell
+npm install <tarball path/URL>
+```
 
-1. Add `console.log('Hello!')` to [clientStartup.ts, function render](https://github.com/shakacode/react_on_rails/blob/master/packages/react-on-rails/src/clientStartup.ts) in `/packages/react-on-rails/src/clientStartup.ts` to confirm we're getting an update to the node package client side. Do the same for function `serverRenderReactComponent` in [/packages/react-on-rails/src/serverRenderReactComponent.ts](https://github.com/shakacode/react_on_rails/blob/master/packages/react-on-rails/src/serverRenderReactComponent.ts).
-2. Refresh the browser if the server is already running or start the server using `foreman start` from `react_on_rails/spec/dummy` and navigate to `http://localhost:5000/`. You will now see the `Hello!` message printed in the browser's console. If you did not see that message, then review the steps above for the workflow of making changes and pushing them via yalc.
+or the equivalent command for your package manager.
 
 # Development Setup for Gem and Node Package Contributors
 

react_on_rails_pro/package.json

@@ -100,10 +100,11 @@
     }
   },
   "files": [
-    "packages/node-renderer/dist"
+    "packages/node-renderer/dist",
+    "script/preinstall.js"
   ],
   "scripts": {
-    "preinstall": "yarn run link-source && yalc add --link react-on-rails",
+    "preinstall": "node ./script/preinstall.js",
     "postinstall": "test -f post-yarn-install.local && ./post-yarn-install.local || true",
     "link-source": "cd ../packages/react-on-rails && yarn && yalc publish",
     "test": "nps test",

react_on_rails_pro/script/preinstall.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const cp = require('child_process');
+
+const inNodeModules = __dirname.split(path.sep).includes('node_modules');
+
+if (inNodeModules) {
+  console.log('preinstall: running inside node_modules — skipping link steps.');
+  process.exit(0);
+}
+
+function runCommand(cmd, args) {
+  const res = cp.spawnSync(cmd, args, { stdio: 'inherit' });
+  if (res.error) throw res.error;
+  if (res.status !== 0) throw new Error(`${cmd} ${args.join(' ')} exited with status ${res.status}`);
+}
+
+try {
+  // Run the original optional link steps sequentially in a cross-platform way.
+  // First run the package script `link-source` via yarn, which will run any shell ops inside the script
+  // (yarn itself will handle invoking a shell for the script body), then call yalc.
+  runCommand('yarn', ['run', 'link-source']);
+  runCommand('yalc', ['add', '--link', 'react-on-rails']);
+} catch (err) {
+  // Don't fail the overall install if these optional commands aren't available or fail,
+  // just log the error.
+  console.error('preinstall: optional link steps failed or are unavailable — continuing.', err);
+  // Keep the exit code 0 so the install doesn't fail.
+  process.exit(0);
+}