diff --git a/docs/contributor-info/releasing.md b/docs/contributor-info/releasing.md index a22bbea09f..a5dc2633ab 100644 --- a/docs/contributor-info/releasing.md +++ b/docs/contributor-info/releasing.md @@ -165,32 +165,12 @@ You must be logged in and have publish permissions: npm login ``` -**For private packages (GitHub Packages):** - -- Get a GitHub personal access token with `write:packages` scope -- Add to `~/.npmrc`: - ```ini - //npm.pkg.github.com/:_authToken= - always-auth=true - ``` -- Set environment variable: - ```bash - export GITHUB_TOKEN= - ``` - ### RubyGems Publishing **For public gem (rubygems.org):** - Standard RubyGems credentials via `gem push` -**For private gem (GitHub Packages):** - -- Add to `~/.gem/credentials`: - ``` - :github: Bearer - ``` - ### Ruby Version Management The script automatically detects and switches Ruby versions when needed: diff --git a/docs/getting-started/pro-quick-start.md b/docs/getting-started/pro-quick-start.md new file mode 100644 index 0000000000..b8548e85fb --- /dev/null +++ b/docs/getting-started/pro-quick-start.md @@ -0,0 +1,171 @@ +# React on Rails Pro: Quick Start from Scratch + +This guide walks you through creating a complete React on Rails Pro application with server-side rendering via the Node Renderer, from an empty directory to a running app. + +**Time:** ~5 minutes + +**Prerequisites:** Ruby 3.0+, Rails 7.0+, Node.js 18+, npm/yarn/pnpm + +## Step 1: Create a new Rails app + +```bash +rails new my-pro-app --skip-javascript --skip-docker +cd my-pro-app +``` + +`--skip-javascript` is required because Shakapacker handles JavaScript bundling. + +## Step 2: Add gems + +```ruby +# Append to Gemfile +gem "shakapacker", "~> 9.5" +gem "react_on_rails_pro", "~> 16.4" +``` + +Since v16.4.0.rc.5, `react_on_rails_pro` automatically requires `react_on_rails` — you only need the Pro gem. On older versions, add both gems explicitly: + +```ruby +gem "shakapacker", "~> 9.5" +gem "react_on_rails", "~> 16.3" +gem "react_on_rails_pro", "~> 16.3" +``` + +Then install: + +```bash +bundle install +``` + +## Step 3: Install Shakapacker + +```bash +rails shakapacker:install +``` + +## Step 4: Commit (required by generator) + +The React on Rails generator requires a clean git working tree: + +```bash +git add -A && git commit -m "Rails app with Shakapacker" +``` + +## Step 5: Install React on Rails with Pro + +This single command sets up everything — base React on Rails, Pro configuration, Node Renderer, webpack configs, and npm packages: + +```bash +rails generate react_on_rails:install --pro +``` + +The `--pro` flag creates: + +| File | Purpose | +| ------------------------------------------- | ---------------------------------------------------------------------------- | +| `config/initializers/react_on_rails.rb` | Base React on Rails config | +| `config/initializers/react_on_rails_pro.rb` | Pro config with NodeRenderer settings | +| `client/node-renderer.js` | Fastify-based Node.js SSR server entry | +| `config/webpack/serverWebpackConfig.js` | Server webpack config with `target: 'node'` and `libraryTarget: 'commonjs2'` | +| `app/javascript/src/HelloWorld/` | Example React component with SSR | +| `app/controllers/hello_world_controller.rb` | Rails controller | +| `app/views/hello_world/index.html.erb` | View using `react_component` helper | +| `Procfile.dev` | All dev processes including Node Renderer | + +Commit: + +```bash +git add -A && git commit -m "react_on_rails:install --pro" +``` + +## Step 6: Start the app + +```bash +./bin/dev +``` + +This starts four processes: + +- **Rails server** on port 3000 +- **Webpack dev server** (HMR) on port 3035 +- **Webpack SSR watcher** for server bundle +- **Node Renderer** on port 3800 + +## Step 7: Visit the app + +Open [http://localhost:3000/hello_world](http://localhost:3000/hello_world) + +You should see the HelloWorld component rendered with SSR. View the page source to confirm pre-rendered HTML. The input field is interactive (client-side hydration). + +## What the generator configured + +The generator creates complete configuration files. Below are the key settings — see the generated files for full details including timeout, retry, and tracing options. + +### Rails-side (config/initializers/react_on_rails_pro.rb) + +```ruby +ReactOnRailsPro.configure do |config| + config.server_renderer = "NodeRenderer" + config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800") + config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "devPassword") + config.prerender_caching = true +end +``` + +### Node-side (client/node-renderer.js) + +```js +const path = require('path'); +const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); + +reactOnRailsProNodeRenderer({ + serverBundleCachePath: path.resolve(__dirname, '../.node-renderer-bundles'), + port: Number(process.env.RENDERER_PORT) || 3800, + password: process.env.RENDERER_PASSWORD || 'devPassword', + supportModules: true, + workersCount: Number(process.env.NODE_RENDERER_CONCURRENCY) || 3, +}); +``` + +### Key configuration options + +| Rails Config | Node Config | Purpose | +| -------------------------- | ----------- | ------------------------------------------------ | +| `config.renderer_url` | `port` | Must point to the same host:port | +| `config.renderer_password` | `password` | Shared authentication secret | +| `config.prerender_caching` | — | Cache SSR results in Rails cache | +| `config.server_renderer` | — | Must be `"NodeRenderer"` to use the Node process | + +## Adding React Server Components + +To add RSC support to your Pro app: + +```bash +rails generate react_on_rails:rsc +``` + +Or for a fresh app with RSC from the start: + +```bash +rails generate react_on_rails:install --rsc +``` + +See the [RSC tutorial](https://www.shakacode.com/react-on-rails-pro/docs/react-server-components/tutorial/) for details. + +## Next Steps + +- [Configuration Reference](https://www.shakacode.com/react-on-rails-pro/docs/configuration/) — All Pro config options +- [Node Renderer Configuration](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/js-configuration/) — All Node Renderer options +- [Caching Guide](https://www.shakacode.com/react-on-rails-pro/docs/caching/) — Fragment and prerender caching +- [Streaming SSR](https://www.shakacode.com/react-on-rails-pro/docs/streaming-server-rendering/) — Progressive rendering +- [Code Splitting](https://www.shakacode.com/react-on-rails-pro/docs/code-splitting-loadable-components/) — Loadable components with SSR + +## Troubleshooting + +**"uninitialized constant ReactOnRailsPro"**: The `react_on_rails_pro` gem is not in your Gemfile. Run `bundle add react_on_rails_pro`. + +**"You have the Pro gem installed but are using the base 'react-on-rails' package"**: Uninstall `react-on-rails` and install `react-on-rails-pro` instead. The `--pro` generator handles this automatically. + +**Node Renderer not connecting**: Ensure the `renderer_url` in `react_on_rails_pro.rb` matches the `port` in `node-renderer.js` (default: 3800). + +**Server bundle errors**: Ensure `serverWebpackConfig.js` has `target: 'node'` and `libraryTarget: 'commonjs2'` set. The `--pro` generator configures this automatically. diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000000..b72a11c5ab --- /dev/null +++ b/llms.txt @@ -0,0 +1,111 @@ +# React on Rails + +> React on Rails integrates React with Ruby on Rails, providing server-side rendering (SSR), component registration, and seamless Rails view integration. React on Rails Pro adds advanced features: a high-performance Node.js rendering server, fragment caching, prerender caching, React Server Components (RSC), and streaming SSR. + +## Package Relationships + +React on Rails consists of Ruby gems and npm packages that must be paired correctly: + +### Open-Source (base): +- Ruby gem: `react_on_rails` +- npm package: `react-on-rails` + +### Pro (commercial, extends base): +- Ruby gem: `react_on_rails_pro` (depends on `react_on_rails`) +- npm package: `react-on-rails-pro` (REPLACES `react-on-rails`, do NOT use both) +- npm package: `react-on-rails-pro-node-renderer` (standalone Fastify SSR server, optional) + +IMPORTANT: When using the `react_on_rails_pro` gem, you MUST use the `react-on-rails-pro` npm package. The base `react-on-rails` npm package will be rejected at runtime. + +## Quick Setup + +### Base (open-source): +```bash +rails generate react_on_rails:install +``` + +### Pro with Node Renderer: +```bash +bundle add react_on_rails_pro +rails generate react_on_rails:install --pro +``` + +### Pro with React Server Components: +```bash +bundle add react_on_rails_pro +rails generate react_on_rails:install --rsc +``` + +## Node Renderer API + +The Node Renderer is a Fastify-based Node.js server for high-performance SSR. + +### Correct usage: +```js +const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); + +reactOnRailsProNodeRenderer({ + serverBundleCachePath: path.resolve(__dirname, '.node-renderer-bundles'), + port: 3800, + supportModules: true, + password: process.env.RENDERER_PASSWORD, + workersCount: 3, + logLevel: 'info', +}); +``` + +The function name is `reactOnRailsProNodeRenderer` (NOT `createServer` or `startRenderer`). +The config key for the bundle cache directory is `serverBundleCachePath` (NOT `bundlePath`, which is deprecated). + +### Rails-side configuration: +```ruby +# config/initializers/react_on_rails_pro.rb +ReactOnRailsPro.configure do |config| + config.server_renderer = "NodeRenderer" + config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800") + config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "devPassword") + config.prerender_caching = true +end +``` + +Key attributes: `server_renderer`, `renderer_url`, `renderer_password`, `prerender_caching`, `ssr_timeout`, `renderer_use_fallback_exec_js`, `throw_js_errors`, `tracing`, `dependency_globs`. + +### Webpack server config requirements (for Pro Node Renderer): +```js +// serverWebpackConfig.js output section +libraryTarget: 'commonjs2', + +// after output section +serverWebpackConfig.target = 'node'; +``` + +## Client-Side Component Registration + +```js +// With base package +import ReactOnRails from 'react-on-rails'; +ReactOnRails.register({ MyComponent }); + +// With Pro package (use this when react_on_rails_pro gem is installed) +import ReactOnRails from 'react-on-rails-pro'; +ReactOnRails.register({ MyComponent }); +``` + +## Pro-Exclusive Imports + +```js +import { RSCRoute } from 'react-on-rails-pro/RSCRoute'; +import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client'; +import { wrapServerComponentRenderer } from 'react-on-rails-pro/wrapServerComponentRenderer/client'; +``` + +## Documentation Links + +- Docs: https://www.shakacode.com/react-on-rails/docs/ +- Pro Docs: https://www.shakacode.com/react-on-rails-pro/docs/ +- Pro Installation: https://www.shakacode.com/react-on-rails-pro/docs/installation/ +- Pro Configuration: https://www.shakacode.com/react-on-rails-pro/docs/configuration/ +- Node Renderer Basics: https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/basics/ +- Node Renderer JS Config: https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/js-configuration/ +- RSC Tutorial: https://www.shakacode.com/react-on-rails-pro/docs/react-server-components/tutorial/ +- GitHub: https://github.com/shakacode/react_on_rails diff --git a/packages/react-on-rails-pro-node-renderer/README.md b/packages/react-on-rails-pro-node-renderer/README.md new file mode 100644 index 0000000000..f6258285ec --- /dev/null +++ b/packages/react-on-rails-pro-node-renderer/README.md @@ -0,0 +1,172 @@ +# react-on-rails-pro-node-renderer + +A high-performance standalone Node.js server for server-side rendering (SSR) of React components in [React on Rails Pro](https://github.com/shakacode/react_on_rails) applications. Built on [Fastify](https://fastify.dev/) with worker pool management. + +## Installation + +```bash +npm install react-on-rails-pro-node-renderer +# or +yarn add react-on-rails-pro-node-renderer +# or +pnpm add react-on-rails-pro-node-renderer +``` + +**Prerequisites:** This package is used with the `react_on_rails_pro` Ruby gem and the `react-on-rails-pro` npm package. See the [full installation guide](https://www.shakacode.com/react-on-rails-pro/docs/installation/). + +## Quick Start + +### 1. Create the Node Renderer entry file + +Create `node-renderer.js` in your project root: + +```js +const path = require('path'); +const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); + +reactOnRailsProNodeRenderer({ + // Directory where the renderer caches uploaded server bundles + serverBundleCachePath: path.resolve(__dirname, '.node-renderer-bundles'), + + // Port the renderer listens on (must match Rails config) + port: Number(process.env.RENDERER_PORT) || 3800, + + // Enable Node.js globals in the rendering VM context + supportModules: true, + + // Log level: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent' + logLevel: process.env.RENDERER_LOG_LEVEL || 'info', + + // Password for Rails <-> Node renderer authentication (must match Rails config) + password: process.env.RENDERER_PASSWORD, + + // Number of worker processes (defaults to CPU count - 1) + workersCount: Number(process.env.RENDERER_WORKERS_COUNT) || 3, +}); +``` + +### 2. Configure Rails + +```ruby +# config/initializers/react_on_rails_pro.rb +ReactOnRailsPro.configure do |config| + config.server_renderer = "NodeRenderer" + config.renderer_url = ENV.fetch("REACT_RENDERER_URL", "http://localhost:3800") + config.renderer_password = ENV.fetch("RENDERER_PASSWORD", "devPassword") +end +``` + +### 3. Configure Webpack + +Set your server bundle webpack configuration to target Node.js: + +```js +// In serverWebpackConfig.js +serverWebpackConfig.target = 'node'; + +// In output config +libraryTarget: 'commonjs2', +``` + +### 4. Start the renderer + +```bash +node node-renderer.js +``` + +Or add to your `Procfile.dev`: + +```text +node-renderer: node node-renderer.js +``` + +## Generator (Recommended) + +The `react_on_rails:install --pro` generator automates all of the above setup: + +```bash +bundle add react_on_rails_pro +rails generate react_on_rails:install --pro +``` + +## Configuration Options + +All options can be set via the config object or environment variables. Config object values take precedence over environment variables. + +| Option | Env Variable | Default | Description | +| -------------------------------------- | --------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- | +| `port` | `RENDERER_PORT` | `3800` | Port the renderer listens on | +| `logLevel` | `RENDERER_LOG_LEVEL` | `'info'` | Log level (`fatal`, `error`, `warn`, `info`, `debug`, `trace`, `silent`) | +| `logHttpLevel` | `RENDERER_LOG_HTTP_LEVEL` | `'error'` | HTTP server log level | +| `serverBundleCachePath` | `RENDERER_SERVER_BUNDLE_CACHE_PATH` | Auto-detected or `/tmp/...` | Directory for cached server bundles | +| `supportModules` | `RENDERER_SUPPORT_MODULES` | `false` | Enable Node.js globals in VM context (`Buffer`, `process`, `setTimeout`, etc.) | +| `workersCount` | `RENDERER_WORKERS_COUNT` | CPU count - 1 | Number of worker processes. The `--pro` generator uses `NODE_RENDERER_CONCURRENCY` instead. | +| `password` | `RENDERER_PASSWORD` | (none) | Shared secret for Rails authentication | +| `stubTimers` | `RENDERER_STUB_TIMERS` | `true` | Stub timer functions during SSR | +| `allWorkersRestartInterval` | `RENDERER_ALL_WORKERS_RESTART_INTERVAL` | (disabled) | Minutes between restarting all workers | +| `delayBetweenIndividualWorkerRestarts` | `RENDERER_DELAY_BETWEEN_INDIVIDUAL_WORKER_RESTARTS` | (disabled) | Minutes between each worker restart | +| `fastifyServerOptions` | — | `{}` | Additional [Fastify server options](https://fastify.dev/docs/latest/Reference/Server/#factory) | + +## Advanced: Custom Fastify Configuration + +For custom routes (e.g., health checks) or plugins, import the master/worker modules directly. The example below uses ES Modules — use a `.mjs` extension, add `"type": "module"` to your `package.json`, or convert to `require()` calls: + +```js +import masterRun from 'react-on-rails-pro-node-renderer/master'; +import run, { configureFastify } from 'react-on-rails-pro-node-renderer/worker'; +import cluster from 'cluster'; + +const config = { + /* your config */ +}; + +configureFastify((app) => { + app.get('/health', (request, reply) => { + reply.send({ status: 'ok' }); + }); +}); + +if (cluster.isPrimary) { + masterRun(config); +} else { + run(config); +} +``` + +## Error Reporting + +Integrate with Sentry or Honeybadger: + +```js +import { addNotifier } from 'react-on-rails-pro-node-renderer/integrations/api'; + +addNotifier((error) => { + Sentry.captureException(error); +}); +``` + +See [Error Reporting and Tracing docs](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/error-reporting-and-tracing/). + +## Documentation + +- [Node Renderer Basics](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/basics/) +- [JavaScript Configuration](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/js-configuration/) +- [Rails Configuration](https://www.shakacode.com/react-on-rails-pro/docs/configuration/) +- [Debugging](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/debugging/) +- [Troubleshooting](https://www.shakacode.com/react-on-rails-pro/docs/node-renderer/troubleshooting/) + +## Package Relationships + +```text +Rails App +├── react_on_rails gem (base Rails integration) +├── react_on_rails_pro gem (Pro server rendering features) +├── react-on-rails-pro npm (client JS - replaces react-on-rails) +└── react-on-rails-pro-node-renderer npm (this package - standalone SSR server) +``` + +**Important:** When using `react_on_rails_pro` gem, you must use `react-on-rails-pro` npm package (not `react-on-rails`). + +## License + +Commercial software. No license required for evaluation, development, testing, or CI/CD. A paid license is required for production deployments. Contact [justin@shakacode.com](mailto:justin@shakacode.com) for licensing. diff --git a/packages/react-on-rails-pro/README.md b/packages/react-on-rails-pro/README.md new file mode 100644 index 0000000000..0ce975e057 --- /dev/null +++ b/packages/react-on-rails-pro/README.md @@ -0,0 +1,97 @@ +# react-on-rails-pro + +The client-side JavaScript package for [React on Rails Pro](https://github.com/shakacode/react_on_rails). This package **replaces** the base `react-on-rails` package and re-exports everything from it, plus Pro-exclusive features like React Server Components support. + +## Installation + +```bash +npm install react-on-rails-pro +# or +yarn add react-on-rails-pro +# or +pnpm add react-on-rails-pro +``` + +**Important:** When using the `react_on_rails_pro` Ruby gem, you **must** use this package (`react-on-rails-pro`) instead of `react-on-rails`. If the Pro gem detects the base `react-on-rails` npm package at runtime, it will raise an error. + +## Usage + +### Component Registration + +```javascript +// Import from react-on-rails-pro (NOT react-on-rails) +import ReactOnRails from 'react-on-rails-pro'; + +import MyComponent from './MyComponent'; + +// Register components for use in Rails views +ReactOnRails.register({ MyComponent }); +``` + +### React Server Components (Pro-exclusive) + +```javascript +import { RSCRoute } from 'react-on-rails-pro/RSCRoute'; +import registerServerComponent from 'react-on-rails-pro/registerServerComponent/client'; +import { wrapServerComponentRenderer } from 'react-on-rails-pro/wrapServerComponentRenderer/client'; + +// Register a server component for client-side hydration +registerServerComponent({ MyServerComponent }); +``` + +## Package Relationship + +```text +react-on-rails-pro (this package) +└── react-on-rails (base package, automatically installed as dependency) +``` + +This package wraps and extends the base `react-on-rails` package. You only need to install `react-on-rails-pro` — the base package is included as a dependency. + +### What this package adds over `react-on-rails` + +- React Server Components support (`RSCRoute`, `RSCProvider`, `registerServerComponent`) +- Server component renderer wrapping (`wrapServerComponentRenderer`) +- Conditional exports for `react-server` and `node` environments +- Seamless integration with the `react_on_rails_pro` Ruby gem + +## Exports + +| Export Path | Description | +| ------------------------------------------------------- | ------------------------------------------------------- | +| `react-on-rails-pro` | Main entry — full ReactOnRails API (same as base + Pro) | +| `react-on-rails-pro/client` | Client-only build (no SSR utilities) | +| `react-on-rails-pro/RSCRoute` | React Server Components route component | +| `react-on-rails-pro/RSCProvider` | RSC provider component | +| `react-on-rails-pro/registerServerComponent/client` | Client-side server component registration | +| `react-on-rails-pro/registerServerComponent/server` | Server-side server component registration | +| `react-on-rails-pro/wrapServerComponentRenderer/client` | Client-side renderer wrapping | +| `react-on-rails-pro/wrapServerComponentRenderer/server` | Server-side renderer wrapping | + +## Rails-Side Setup + +This npm package works with the `react_on_rails_pro` Ruby gem: + +```ruby +# Gemfile +gem "react_on_rails_pro" +``` + +Or use the generator for automated setup: + +```bash +rails generate react_on_rails:install --pro +``` + +See the [full installation guide](https://www.shakacode.com/react-on-rails-pro/docs/installation/). + +## Documentation + +- [Installation Guide](https://www.shakacode.com/react-on-rails-pro/docs/installation/) +- [Configuration Reference](https://www.shakacode.com/react-on-rails-pro/docs/configuration/) +- [React Server Components Tutorial](https://www.shakacode.com/react-on-rails-pro/docs/react-server-components/tutorial/) +- [React on Rails Pro Overview](https://www.shakacode.com/react-on-rails-pro/) + +## License + +Commercial software. No license required for evaluation, development, testing, or CI/CD. A paid license is required for production deployments. Contact [justin@shakacode.com](mailto:justin@shakacode.com) for licensing. diff --git a/packages/react-on-rails-pro/package.json b/packages/react-on-rails-pro/package.json index 590fdf8453..4afd3a212d 100644 --- a/packages/react-on-rails-pro/package.json +++ b/packages/react-on-rails-pro/package.json @@ -67,6 +67,7 @@ } }, "files": [ + "README.md", "lib/**/*.js", "lib/**/*.d.ts" ], diff --git a/packages/react-on-rails/README.md b/packages/react-on-rails/README.md new file mode 100644 index 0000000000..2d681293ae --- /dev/null +++ b/packages/react-on-rails/README.md @@ -0,0 +1,106 @@ +# react-on-rails + +The client-side JavaScript package for [React on Rails](https://github.com/shakacode/react_on_rails) — the integration layer between Rails and React. This package handles component registration, client-side hydration, and server-side rendering support. + +## Installation + +```bash +npm install react-on-rails +# or +yarn add react-on-rails +# or +pnpm add react-on-rails +``` + +**Using React on Rails Pro?** Install [`react-on-rails-pro`](https://www.npmjs.com/package/react-on-rails-pro) instead. The Pro package re-exports everything from this package plus Pro-exclusive features. The `react_on_rails_pro` gem requires the Pro npm package. + +## Quick Start + +### Register Components + +```javascript +import ReactOnRails from 'react-on-rails'; +import HelloWorld from './HelloWorld'; + +// Register components so Rails views can render them +ReactOnRails.register({ HelloWorld }); +``` + +### Use in Rails Views + +```erb +<%# app/views/hello_world/index.html.erb %> +<%= react_component("HelloWorld", props: { name: "World" }, prerender: true) %> +``` + +### Server-Side Rendering + +For SSR, create a server bundle entry that registers the same components: + +```javascript +// app/javascript/packs/server-bundle.js +import ReactOnRails from 'react-on-rails'; +import HelloWorld from '../src/HelloWorld'; + +ReactOnRails.register({ HelloWorld }); +``` + +## API + +### `ReactOnRails.register(components)` + +Register React components for use in Rails views. + +```javascript +ReactOnRails.register({ + HelloWorld, + UserProfile, + Dashboard, +}); +``` + +### Render Functions + +For advanced SSR control, register render functions instead of components: + +```javascript +ReactOnRails.register({ + MyApp: (props, railsContext) => { + return { renderedHtml: '
...
' }; + }, +}); +``` + +## Exports + +| Export Path | Description | +| ----------------------- | ----------------------------------- | +| `react-on-rails` | Full build with SSR utilities | +| `react-on-rails/client` | Client-only build (smaller, no SSR) | +| `react-on-rails/types` | TypeScript type exports | + +## Rails-Side Setup + +This npm package works with the `react_on_rails` Ruby gem: + +```ruby +# Gemfile +gem "react_on_rails" +``` + +Use the generator for automated setup: + +```bash +rails generate react_on_rails:install +``` + +## Documentation + +- [Getting Started](https://www.shakacode.com/react-on-rails/docs/getting-started/quick-start/) +- [Installation Guide](https://www.shakacode.com/react-on-rails/docs/getting-started/installation-into-an-existing-rails-app/) +- [API Reference](https://www.shakacode.com/react-on-rails/docs/api-reference/) +- [Configuration](https://www.shakacode.com/react-on-rails/docs/configuration/) + +## License + +See [LICENSE.md](https://github.com/shakacode/react_on_rails/blob/master/LICENSE.md). diff --git a/packages/react-on-rails/package.json b/packages/react-on-rails/package.json index a24bf20f23..b2e16b7d5c 100644 --- a/packages/react-on-rails/package.json +++ b/packages/react-on-rails/package.json @@ -60,6 +60,7 @@ "react-dom": ">= 16" }, "files": [ + "README.md", "lib/**/*.js", "lib/**/*.cjs", "lib/**/*.mjs", diff --git a/react_on_rails_pro/README.md b/react_on_rails_pro/README.md index 487f4e43ef..443b16087c 100644 --- a/react_on_rails_pro/README.md +++ b/react_on_rails_pro/README.md @@ -191,11 +191,12 @@ High-performance standalone Node.js server for server-side rendering with connec **Example Configuration:** ```javascript -// react-on-rails-pro/react-on-rails-pro-node-renderer.js -const { reactOnRailsProNodeRenderer } = require('@shakacode-tools/react-on-rails-pro-node-renderer'); +// node-renderer.js +const path = require('path'); +const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer'); reactOnRailsProNodeRenderer({ - bundlePath: path.resolve(__dirname, '../app/assets/webpack'), + serverBundleCachePath: path.resolve(__dirname, '.node-renderer-bundles'), port: 3800, workersCount: 4, supportModules: true, // Required for loadable-components diff --git a/react_on_rails_pro/docs/code-splitting-loadable-components.md b/react_on_rails_pro/docs/code-splitting-loadable-components.md index 0b6340cbe7..ce249ff70b 100644 --- a/react_on_rails_pro/docs/code-splitting-loadable-components.md +++ b/react_on_rails_pro/docs/code-splitting-loadable-components.md @@ -284,9 +284,8 @@ reactOnRailsProNodeRenderer(config); ## Making HMR Work To make HMR work, it's best to disable loadable-components when using the Dev Server. -Note: you will need access to our **private** React on Rails Pro repository to open the following links. -Take a look at the code searches for ['imports-loadable'](https://github.com/shakacode/react_on_rails_pro/search?q=imports-loadable&type=code) and ['imports-hmr'](https://github.com/shakacode/react_on_rails_pro/search?q=imports-hmr&type=code) +Take a look at the code searches for ['imports-loadable'](https://github.com/shakacode/react_on_rails/search?q=imports-loadable&type=code) and ['imports-hmr'](https://github.com/shakacode/react_on_rails/search?q=imports-hmr&type=code) The general concept is that we have a non-loadable, HMR-ready, file that substitutes for the loadable-enabled one, with the suffixes `imports-hmr.js` instead of `imports-loadable.js` @@ -294,7 +293,7 @@ The general concept is that we have a non-loadable, HMR-ready, file that substit Use the [NormalModuleReplacement plugin](https://webpack.js.org/plugins/normal-module-replacement-plugin/): -[code](https://github.com/shakacode/react_on_rails_pro/blob/a361f4e163b9170f180ae07ee312fb9b4c719fc3/spec/dummy/config/webpack/environment.js#L81-L91) +[code](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/config/webpack/commonWebpackConfig.js#L41-L49) ```js if (isWebpackDevServer) { @@ -313,17 +312,15 @@ And compare: ### Routes file -Note: you will need access to our **private** React on Rails Pro repository to open the following links. - -- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx) -- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx) +- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/components/Loadable/routes/Routes.imports-hmr.jsx) +- [spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/components/Loadable/routes/Routes.imports-loadable.jsx) ### Client-Side Startup -- [spec/dummy/client/app/loadable/loadable-client.imports-hmr.js](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-client.imports-hmr.js) -- [spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx) +- [spec/dummy/client/app/loadable/loadable-client.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-client.imports-hmr.jsx) +- [spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx) ### Server-Side Startup -- [spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx) -- [spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx](https://github.com/shakacode/react_on_rails_pro/blob/master/spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx) +- [spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-server.imports-hmr.jsx) +- [spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/spec/dummy/client/app/loadable/loadable-server.imports-loadable.jsx) diff --git a/react_on_rails_pro/docs/ruby-api.md b/react_on_rails_pro/docs/ruby-api.md index b6f040cfed..f86569f115 100644 --- a/react_on_rails_pro/docs/ruby-api.md +++ b/react_on_rails_pro/docs/ruby-api.md @@ -1,11 +1,9 @@ # Ruby API -Note: you will need access to our **private** React on Rails Pro repository to open the following links. - ## View Helpers -See the [app/helpers/react_on_rails_pro_helper.rb](https://github.com/shakacode/react_on_rails_pro/blob/master/app/helpers/react_on_rails_pro_helper.rb) source. +See the [app/helpers/react_on_rails_pro_helper.rb](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/app/helpers/react_on_rails_pro_helper.rb) source. ## Utility Methods -See the [lib/react_on_rails_pro/utils.rb](https://github.com/shakacode/react_on_rails_pro/blob/master/lib/react_on_rails_pro/utils.rb) source. +See the [lib/react_on_rails_pro/utils.rb](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/lib/react_on_rails_pro/utils.rb) source. diff --git a/react_on_rails_pro/docs/updating.md b/react_on_rails_pro/docs/updating.md index eacd648b6a..8aabf29d0e 100644 --- a/react_on_rails_pro/docs/updating.md +++ b/react_on_rails_pro/docs/updating.md @@ -6,7 +6,7 @@ This guide is for existing React on Rails Pro customers who are: -- Currently using GitHub Packages authentication (private distribution) +- Previously using GitHub Packages authentication (private distribution) - On version 16.2.0-beta.x or earlier - Upgrading to version 16.2.0 or higher