diff --git a/CHANGELOG.md b/CHANGELOG.md index d50625a18a..d63264690e 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37874ea65b..09d8537f07 100644 --- a/CONTRIBUTING.md +++ b/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: "" ``` -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_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 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 /packages/react-on-rails yalc publish -cd spec/dummy +cd 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 +```shell +cd /packages/react-on-rails # Will send the updates to other folders - MUST DO THIS AFTER ANY CHANGES yalc push -cd spec/dummy +cd # 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 react-on-rails@12.0.0-12070fd1 published in store. Pushing react-on-rails@12.0.0 in /Users/justin/shakacode/react-on-rails/react_on_rails/spec/dummy Package react-on-rails@12.0.0-12070fd1 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 "git@github.com: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 +``` -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 diff --git a/react_on_rails_pro/package.json b/react_on_rails_pro/package.json index be861fb2e9..db05cccff1 100644 --- a/react_on_rails_pro/package.json +++ b/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", diff --git a/react_on_rails_pro/script/preinstall.js b/react_on_rails_pro/script/preinstall.js new file mode 100644 index 0000000000..f5b47cff29 --- /dev/null +++ b/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); +}