Skip to content

Docs/auto bundle rename and dummy reference #1758

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 6, 2025
Merged

Docs/auto bundle rename and dummy reference #1758

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
36d08b6
rename BarComponentTwo to SpecialComponentNotToAutoLoadBundle in the …
ihabadham Sep 2, 2025
a341b67
add dummy/app cross-references for further clarity
ihabadham Sep 2, 2025
ea09111
fix: replace append_javascript_pack with append_javascript_pack_tag
ihabadham Sep 2, 2025
47956e3
fix ci: format to satisfy Prettier CI
ihabadham Sep 2, 2025
07ef6f9
Revise documentation for React component bundle loading
justin808 Sep 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions docs/guides/file-system-based-automated-bundle-generation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ default:

For more details, see [Configuration and Code](https://github.com/shakacode/shakapacker#configuration-and-code) section in [shakapacker](https://github.com/shakacode/shakapacker/).

> Example (dummy app): `nested_entries: true` with a different `source_path: client/app`. See `config/shakapacker.yml` in the dummy app.
> [Dummy shakapacker.yml](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/shakapacker.yml)

### Configure Components Subdirectory

`components_subdirectory` is the name of the matched directories containing components that will be automatically registered for use by the view helpers.
Expand All @@ -28,6 +31,9 @@ config.components_subdirectory = "ror_components"

Now all React components inside the directories called `ror_components` will automatically be registered for usage with [`react_component`](../api/view-helpers-api.md#react_component) and [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) helper methods provided by React on Rails.

> Example (dummy app): the configured components subdirectory is named `startup` instead of `ror_components`.
> [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/initializers/react_on_rails.rb)

### Configure `auto_load_bundle` Option

For automated component registry, [`react_component`](../api/view-helpers-api.md#react_component) and [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) view helper method tries to load generated bundle for component from the generated directory automatically per `auto_load_bundle` option. `auto_load_bundle` option in `config/initializers/react_on_rails` configures the default value that will be passed to component helpers. The default is `false`, and the parameter can be passed explicitly for each call.
Expand All @@ -38,6 +44,9 @@ You can change the value in `config/initializers/react_on_rails` by updating it
config.auto_load_bundle = true
```

> Example (dummy app): `auto_load_bundle` is set to `true` in the same initializer.
> [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/initializers/react_on_rails.rb)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ihabadham

  1. Should all of the references have line numbers?
  2. Should they be on a particular commit? if we leave on master, line number will eventually be invalid.

I'll merge as-is for now.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2. if we leave on master, line number will eventually be invalid.

yeah makes sense, i didn't see this one. i'll open a followup pr and address this


### Location of generated files

Generated files will go to the following two directories:
Expand Down Expand Up @@ -65,6 +74,9 @@ import './../generated/server-bundle-generated.js';

We recommend committing this import statement to your version control system.

> Example (dummy app): see the server bundle entrypoint import.
> [Dummy server-bundle.js](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/packs/server-bundle.js)

## Usage

### Basic usage
Expand Down Expand Up @@ -146,24 +158,26 @@ The tricky part is to figure out which bundles to load on any Rails view. [Shaka

File-system-based automated pack generation simplifies this process with a new option for the view helpers.

For example, if you wanted to utilize our file-system based entrypoint generation for `FooComponentOne` and `BarComponentOne`, but not `BarComponentTwo` (for whatever reason), then...
> Note: In the Background examples above, we used `BarComponentTwo`. In the Solution below, we refer to the same component as `SpecialComponentNotToAutoLoadBundle` to emphasize that it is excluded from auto-loading. You do not need to rename your files.

For example, if you wanted to utilize our file-system based entrypoint generation for `FooComponentOne` and `BarComponentOne`, but not `SpecialComponentNotToAutoLoadBundle` (formerly `BarComponentTwo`) (for whatever reason), then...

1. Remove generated entrypoints from parameters passed directly to `javascript_pack_tag` and `stylesheet_pack_tag`.
2. Remove generated entrypoints from parameters passed directly to `append_javascript_pack_tag` and `append_stylesheet_pack_tag`.

Your layout would now contain:

```erb
<%= javascript_pack_tag('BarComponentTwo') %>
<%= stylesheet_pack_tag('BarComponentTwo') %>
<%= javascript_pack_tag('SpecialComponentNotToAutoLoadBundle') %>
<%= stylesheet_pack_tag('SpecialComponentNotToAutoLoadBundle') %>
```

3. Create a directory structure where the components that you want to be auto-generated are within `ReactOnRails.configuration.components_subdirectory`, which should be a subdirectory of `Shakapacker.config.source_path`:

```text
app/javascript:
└── packs:
│ └── BarComponentTwo.jsx # Internally uses ReactOnRails.register
│ └── SpecialComponentNotToAutoLoadBundle.jsx # Internally uses ReactOnRails.register
└── src:
│ └── Foo
│ │ └── ...
Expand All @@ -174,16 +188,17 @@ For example, if you wanted to utilize our file-system based entrypoint generatio
│ │ └── ror_components # configured as `components_subdirectory`
│ │ │ └── BarComponentOne.jsx
│ │ └── something_else
│ │ │ └── BarComponentTwo.jsx
│ │ │ └── SpecialComponentNotToAutoLoadBundle.jsx
```

4. You no longer need to register the React components within the `ReactOnRails.configuration.components_subdirectory` nor directly add their bundles. For example, you can have a Rails view using three components:

```erb
<% append_javascript_pack('BarComponentTwo') %>
<%= react_component("FooComponentOne", {}, auto_load_bundle: true) %>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

put line 200 right under this.
and should have a blank line separating

<%= react_component("BarComponentOne", {}, auto_load_bundle: true) %>
<%= react_component("BarComponentTwo", {}) %>

<% append_javascript_pack_tag('SpecialComponentNotToAutoLoadBundle') %>
<%= react_component("SpecialComponentNotToAutoLoadBundle", {}) %>
```

If a component uses multiple HTML strings for server rendering, the [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) view helper can be used on the Rails view, as illustrated below.
Expand All @@ -208,6 +223,8 @@ For example, if you wanted to utilize our file-system based entrypoint generatio

If server rendering is enabled, the component will be registered for usage both in server and client rendering. To have separate definitions for client and server rendering, name the component files `ComponentName.server.jsx` and `ComponentName.client.jsx`. The `ComponentName.server.jsx` file will be used for server rendering and the `ComponentName.client.jsx` file for client rendering. If you don't want the component rendered on the server, you should only have the `ComponentName.client.jsx` file.

> Example (dummy app): paired files such as [`ReduxApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/ReduxApp.client.jsx) and [`ReduxApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/ReduxApp.server.jsx), and [`RouterApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/RouterApp.client.jsx) and [`RouterApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/RouterApp.server.jsx).

Once generated, all server entrypoints will be imported into a file named `[ReactOnRails.configuration.server_bundle_js_file]-generated.js`, which in turn will be imported into a source file named the same as `ReactOnRails.configuration.server_bundle_js_file`. If your server bundling logic is such that your server bundle source entrypoint is not named the same as your `ReactOnRails.configuration.server_bundle_js_file` and changing it would be difficult, please let us know.

> [!IMPORTANT]
Expand Down
Loading