Skip to content

Add centralized help and support messaging system #1803

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 9 commits into from
Sep 22, 2025
Merged

Add centralized help and support messaging system #1803

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
55b820a
Add centralized help and support messaging system
justin808 Sep 21, 2025
2c67f41
Add help message to fatal error output
justin808 Sep 21, 2025
8e1875d
Add help messages to additional error classes
justin808 Sep 22, 2025
e7a3b6a
Improve markdown-to-terminal conversion to preserve URLs
justin808 Sep 22, 2025
8976d09
Simplify help message system - use hardcoded message
justin808 Sep 22, 2025
f769676
Improve JsonParseError message formatting
justin808 Sep 22, 2025
882b43c
Improve docs
justin808 Sep 22, 2025
6c21f69
Improve docs
justin808 Sep 22, 2025
0e0f18b
Fix critical issues from code review
justin808 Sep 22, 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
23 changes: 15 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,16 +140,21 @@ _Requires creating a free account._
- Node.js >= 20 (CI tested: 20 - 22)
- A JavaScript package manager (npm, yarn, pnpm, or bun)

# Support
# 🆘 Get Help & Support

- [Click to join **React + Rails Slack**](https://join.slack.com/t/reactrails/shared_invite/zt-38oicm9d0-OO0V~bdg4aYNuZuUbRFSXg).
**Need immediate help?** Here are your options, ordered by response time:

- [**Subscribe**](https://app.mailerlite.com/webforms/landing/l1d9x5) for announcements of new releases of React on Rails and of our latest [blog articles](https://blog.shakacode.com) and tutorials.
- [Discussions](https://github.com/shakacode/react_on_rails/discussions): Post your questions regarding React on Rails
- **[forum.shakacode.com](https://forum.shakacode.com)**: Other discussions
- **[@railsonmaui on Twitter](https://twitter.com/railsonmaui)**
- _See [NEWS.md](https://github.com/shakacode/react_on_rails/tree/master/NEWS.md) for more notes over time._
- See [Projects](https://github.com/shakacode/react_on_rails/tree/master/PROJECTS.md) using and [KUDOS](https://github.com/shakacode/react_on_rails/tree/master/KUDOS.md) for React on Rails. Please submit yours! Please edit either page or [email us](mailto:contact@shakacode.com) and we'll add your info. We also **love stars** as it helps us attract new users and contributors.
- 🚀 **Professional Support**: [react_on_rails@shakacode.com](mailto:react_on_rails@shakacode.com) - Fastest resolution for bugs, upgrades, and consulting
- 💬 **React + Rails Slack**: [Join our community](https://invite.reactrails.com) - Chat with other developers
- 🆓 **GitHub Issues**: [Report bugs](https://github.com/shakacode/react_on_rails/issues) - Community support
- 📖 **Discussions**: [Ask questions](https://github.com/shakacode/react_on_rails/discussions) - General help

**Additional Resources:**

- [**Subscribe**](https://app.mailerlite.com/webforms/landing/l1d9x5) for announcements of new releases and tutorials
- **[forum.shakacode.com](https://forum.shakacode.com)** - Development discussions
- **[@railsonmaui on Twitter](https://twitter.com/railsonmaui)** - Updates and tips
- [Projects using React on Rails](https://github.com/shakacode/react_on_rails/tree/master/PROJECTS.md) - Submit yours!

## Contributing

Expand All @@ -163,6 +168,8 @@ ShakaCode is **[hiring passionate software engineers](http://www.shakacode.com/c

The gem is available as open source under the terms of the [MIT License](https://github.com/shakacode/react_on_rails/tree/master/LICENSE.md).

Note, some features are available only with a React on Rails Pro subscription. See [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) for more information.

# Supporters

The following companies support our open-source projects, and ShakaCode uses their products!
Expand Down
7 changes: 6 additions & 1 deletion lib/react_on_rails/json_parse_error.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,12 @@ class JsonParseError < ::ReactOnRails::Error
def initialize(parse_error:, json:)
@json = json
@original_error = parse_error
super(parse_error.message)
message = <<~MSG
#{parse_error.message}

#{Utils.default_troubleshooting_section}
MSG
super(message)
end

def to_honeybadger_context
Expand Down
4 changes: 4 additions & 0 deletions lib/react_on_rails/prerender_error.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,10 @@ def calc_message(component_name, console_messages, err, js_code, props)
MSG

end

# Add help and support information
message << "\n#{Utils.default_troubleshooting_section}\n"

Comment on lines +86 to +89
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue

Avoid duplicate help blocks; prefer dynamic content with fallback.

If upstream raises an error that already includes the help section, PrerenderError will append it again. Also, this uses the static default rather than the dynamically extracted README block.

Apply this diff:

-      # Add help and support information
-      message << "\n#{Utils.default_troubleshooting_section}\n"
+      # Add help and support information (once, dynamic with fallback)
+      unless message.include?('Get Help & Support:')
+        message << "\n#{Utils.help_and_support_section}\n"
+      end

And add these helpers in lib/react_on_rails/utils.rb:

def self.help_and_support_section
  @help_and_support_section ||= begin
    extract_troubleshooting_section
  rescue StandardError
    nil
  end || default_troubleshooting_section
end

def self.append_help_section_once(str)
  return str if str&.include?('Get Help & Support:')
  [str, help_and_support_section].compact.join("\n\n")
end
🤖 Prompt for AI Agents 
In lib/react_on_rails/prerender_error.rb around lines 86 to 89, the code appends
the default troubleshooting block unconditionally which can cause duplicate help
text and doesn't use the dynamic README extraction; replace the direct append
with a single call to Utils.append_help_section_once(message) so the help block
is added only when missing and falls back to the extracted or default section,
and add the two helper methods shown in lib/react_on_rails/utils.rb
(help_and_support_section and append_help_section_once) to handle extraction,
caching, error-safe fallback, and idempotent appending.

[backtrace, message]
end
end
Expand Down
8 changes: 5 additions & 3 deletions lib/react_on_rails/server_rendering_pool/ruby_embedded_java_script.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ def exec_server_render_js(js_code, render_options, js_evaluator = nil)
if err.message.include?("ReferenceError: self is not defined")
msg << "\nError indicates that you may have code-splitting incorrectly enabled.\n"
end
msg << "\n#{Utils.default_troubleshooting_section}\n"
raise ReactOnRails::Error, msg, err.backtrace
Comment on lines +80 to 81
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue

Append help once and use dynamic README-backed content.

This risks duplicate help blocks when wrapped by higher-level errors and uses the static default.

Apply this diff:

-            msg << "\n#{Utils.default_troubleshooting_section}\n"
+            msg << "\n#{Utils.help_and_support_section}\n" unless msg.include?('Get Help & Support:')
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
msg << "\n#{Utils.default_troubleshooting_section}\n"
raise ReactOnRails::Error, msg, err.backtrace
msg << "\n#{Utils.help_and_support_section}\n" unless msg.include?('Get Help & Support:')
raise ReactOnRails::Error, msg, err.backtrace
🤖 Prompt for AI Agents 
In lib/react_on_rails/server_rendering_pool/ruby_embedded_java_script.rb around
lines 80-81, avoid appending the static troubleshooting block unconditionally
which can duplicate help when errors are re-wrapped; instead detect whether the
message already contains the troubleshooting marker and only append the help
once, and pull that help from the dynamic README-backed helper (e.g.
Utils.default_troubleshooting_section or a new
Utils.readme_troubleshooting_content) so the content is driven from the README;
then raise the error with the original backtrace unchanged.

end

Expand Down Expand Up @@ -122,7 +123,7 @@ def read_bundle_js_code
rescue StandardError => e
msg = "You specified server rendering JS file: #{server_js_file}, but it cannot be " \
"read. You may set the server_bundle_js_file in your configuration to be \"\" to " \
"avoid this warning.\nError is: #{e}"
"avoid this warning.\nError is: #{e}\n\n#{Utils.default_troubleshooting_section}"
raise ReactOnRails::Error, msg
end
Comment on lines 124 to 128
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue

Preserve original backtrace when re-raising; also prefer dynamic help.

Current raise drops e.backtrace, reducing debuggability. Include the original backtrace for parity with exec_server_render_js.

Apply this diff:

-          msg = "You specified server rendering JS file: #{server_js_file}, but it cannot be " \
+          msg = "You specified server rendering JS file: #{server_js_file}, but it cannot be " \
                 "read. You may set the server_bundle_js_file in your configuration to be \"\" to " \
-                "avoid this warning.\nError is: #{e}\n\n#{Utils.default_troubleshooting_section}"
-          raise ReactOnRails::Error, msg
+                "avoid this warning.\nError is: #{e}\n\n#{Utils.help_and_support_section}"
+          raise ReactOnRails::Error, msg, e.backtrace
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
msg = "You specified server rendering JS file: #{server_js_file}, but it cannot be " \
"read. You may set the server_bundle_js_file in your configuration to be \"\" to " \
"avoid this warning.\nError is: #{e}"
"avoid this warning.\nError is: #{e}\n\n#{Utils.default_troubleshooting_section}"
raise ReactOnRails::Error, msg
end
msg = "You specified server rendering JS file: #{server_js_file}, but it cannot be " \
"read. You may set the server_bundle_js_file in your configuration to be \"\" to " \
"avoid this warning.\nError is: #{e}\n\n#{Utils.help_and_support_section}"
raise ReactOnRails::Error, msg, e.backtrace
end
🤖 Prompt for AI Agents 
In lib/react_on_rails/server_rendering_pool/ruby_embedded_java_script.rb around
lines 124 to 128, the rescue currently raises ReactOnRails::Error with a message
but discards the original exception backtrace; instead re-raise preserving
e.backtrace (for example: raise ReactOnRails::Error, msg, e.backtrace) so the
original stack is retained, and ensure the troubleshooting/help text is obtained
dynamically from Utils.default_troubleshooting_section when building the
message.


Expand All @@ -149,7 +150,8 @@ def create_js_context
msg = "ERROR when compiling base_js_code! " \
"See file #{file_name} to " \
"correlate line numbers of error. Error is\n\n#{e.message}" \
"\n\n#{e.backtrace.join("\n")}"
"\n\n#{e.backtrace.join("\n")}" \
"\n\n#{Utils.default_troubleshooting_section}"
Rails.logger.error(msg)
trace_js_code_used("Error when compiling JavaScript code for the context.", base_js_code,
file_name, force: true)
Expand Down Expand Up @@ -227,7 +229,7 @@ def file_url_to_string(url)
encoding_type = match[:encoding]
response.body.force_encoding(encoding_type)
rescue StandardError => e
msg = "file_url_to_string #{url} failed\nError is: #{e}"
msg = "file_url_to_string #{url} failed\nError is: #{e}\n\n#{Utils.default_troubleshooting_section}"
raise ReactOnRails::Error, msg
end
Comment on lines +232 to 234
Copy link
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue

Preserve backtrace and avoid duplicate/static help.

Apply this diff:

-          msg = "file_url_to_string #{url} failed\nError is: #{e}\n\n#{Utils.default_troubleshooting_section}"
-          raise ReactOnRails::Error, msg
+          msg = "file_url_to_string #{url} failed\nError is: #{e}\n\n#{Utils.help_and_support_section}"
+          raise ReactOnRails::Error, msg, e.backtrace
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
msg = "file_url_to_string #{url} failed\nError is: #{e}\n\n#{Utils.default_troubleshooting_section}"
raise ReactOnRails::Error, msg
end
msg = "file_url_to_string #{url} failed\nError is: #{e}\n\n#{Utils.help_and_support_section}"
raise ReactOnRails::Error, msg, e.backtrace
end
🤖 Prompt for AI Agents 
In lib/react_on_rails/server_rendering_pool/ruby_embedded_java_script.rb around
lines 232-234, the current code builds an error message that unconditionally
appends Utils.default_troubleshooting_section and then raises a new
ReactOnRails::Error, which loses the original exception backtrace and can
duplicate the static help text; change it to construct the message without
repeating the troubleshooting section (only append the help if it’s not already
present), and raise the ReactOnRails::Error while preserving the original
exception backtrace by passing e.backtrace as the third argument (e.g., raise
ReactOnRails::Error, msg, e.backtrace).


Expand Down
12 changes: 12 additions & 0 deletions lib/react_on_rails/utils.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ def self.invoke_and_exit_if_failed(cmd, failure_message)
MSG

puts wrap_message(msg)
puts ""
puts default_troubleshooting_section

# Rspec catches exit without! in the exit callbacks
exit!(1)
Expand Down Expand Up @@ -278,5 +280,15 @@ def self.prepend_to_file_if_text_not_present(file:, text_to_prepend:, regex:)

puts "Prepended\n#{text_to_prepend}to #{file}."
end

def self.default_troubleshooting_section
<<~DEFAULT
📞 Get Help & Support:
• 🚀 Professional Support: react_on_rails@shakacode.com (fastest resolution)
• 💬 React + Rails Slack: https://invite.reactrails.com
• 🆓 GitHub Issues: https://github.com/shakacode/react_on_rails/issues
• 📖 Discussions: https://github.com/shakacode/react_on_rails/discussions
DEFAULT
end
end
end
24 changes: 19 additions & 5 deletions lib/tasks/generate_packs.rake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,24 @@ namespace :react_on_rails do
puts Rainbow("=" * 80).red
end

def show_help_and_support
puts ""
troubleshooting_content = ReactOnRails::Utils.default_troubleshooting_section
# Display the troubleshooting content with color formatting
troubleshooting_content.split("\n").each do |line|
case line
when /^📞/
puts Rainbow(line).magenta.bold
when /^\s*•\s*🚀/
puts Rainbow(line).yellow
when /^\s*•/
puts Rainbow(line).cyan
else
puts Rainbow(line).white unless line.strip.empty?
end
end
end

# rubocop:disable Metrics/AbcSize
def handle_standard_error(error)
puts ""
Expand All @@ -142,11 +160,7 @@ namespace :react_on_rails do
puts Rainbow(" 2. Check Rails logs: tail -f log/development.log").white
puts Rainbow(" 3. Verify all dependencies are installed: bundle install && npm install").white
puts Rainbow(" 4. Clear cache: rm -rf tmp/cache").white
puts ""
puts Rainbow("📞 GET HELP:").magenta.bold
puts Rainbow(" • Create an issue: https://github.com/shakacode/react_on_rails/issues").cyan
puts Rainbow(" • Community discussions: https://github.com/shakacode/react_on_rails/discussions").cyan
puts Rainbow(" • Professional support: https://www.shakacode.com/react-on-rails-pro").cyan
show_help_and_support
puts Rainbow("=" * 80).red
end
# rubocop:enable Metrics/AbcSize
Expand Down
Loading