Update docs

This updates docs to account for `foobar.html.erb` files made optional by superglue_rails v1.1.0. We also update some copy here too.
thoughtbot · Feb 18, 2025 · 7c4d757 · 7c4d757
1 parent f4ab59b
commit 7c4d757
Show file tree

Hide file tree

Showing 12 changed files with 111 additions and 48 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -27,7 +27,7 @@ when the internet is down.
     Stop by the [tutorial] to learn how to work with this file.
 
     **Vite Users** This step can be entirely optional if you're using Vite. See
-    the [recipe](recipe/vite.md) for more information.
+    the [recipe](recipes/vite.md) for more information.
 
 This file exports a mapping between a `componentIdentifier` to an imported page
 component. This gets used in your `application.js` so that superglue knows

diff --git a/docs/cross-cutting-concerns.md b/docs/cross-cutting-concerns.md
@@ -30,11 +30,9 @@ app/
 |   |-- posts/
 |   |   |-- index.js
 |   |   |-- index.json.props
-|   |   |-- index.html.erb
 |   |-- comments/
 |   |   |-- index.js
 |   |   |-- index.json.props
-|   |   |-- index.html.erb
 ```
 
 By [design](./redux-state-shape.md) this results in duplicate JSON nodes

diff --git a/docs/index.md b/docs/index.md
@@ -1,10 +1,10 @@
 # Overview
 
-Superglue is a library that thoughtfully pairs Rails and React. Its
-built with a laser focus on The Rails Way and aims to provide a simple
-developer experience on par with Hotwire, Stimulus, and Turbo. Confidently use
-Rails routes, controllers, views as you normally would in a multi-page
-application and integrate with React's vast ecosystem.
+Superglue and friends [thoughtfully pairs Rails and React]. Its built with a
+laser focus on The Rails Way and aims to provide a simple developer experience
+on par with Hotwire, Stimulus, and Turbo. Confidently use Rails routes,
+controllers, views as you normally would in a multi-page application and
+integrate with React's vast ecosystem.
 
 ## Who is it for?
 
@@ -78,7 +78,7 @@ end
 ```
 
 Familiar Rails conveniences include form_props (a fork of `form_with` made for React),
-flash messages integrated as a Redux [slice], and [Unobtrusive Javascript](UJS) helpers.
+flash messages integrated as a Redux [slice], and [Unobtrusive Javascript][UJS] helpers.
 
 ### It’s React
 
@@ -120,7 +120,7 @@ export default function FooBar() {
 }
 ```
 
-### It’s Turbolinks and UJS
+### It’s Turbolinks
 
 Superglue drew inspiration fromthe original Turbolinks, but instead of sending
 your `foobar.html.erb` over the wire and swapping the `<body>`, it sends
@@ -134,12 +134,7 @@ your React components to SPA transition to the next page.
 <a href=”/next_page” data-sg-visit> Next Page </a>
 ```
 
-## A thoughtful pairing
-
-Superglue is about thoughfully pairing React and Rails that brings out the best
-of both frameworks.
-
-### The return of UJS and diggable templates
+### The return of UJS
 
 Superglue’s secret sauce is that your `foobar.json.props` is diggable; making
 any part of your page dynamic by using a query string. It’s a simpler approach
@@ -231,6 +226,7 @@ your team.
 
 
 [Redux state]: ./redux-state-shape.md
-[modals]: ./recipes/modals.md
-[more]: ./recipes
+[modals]: recipes/modals.md
+[more]: recipes/
 [slice]: ./cross-cutting-concerns.md#slices
+[thoughtfully pairs Rails and React]: https://thoughtbot.com/blog/superglue-1-0-react-rails-a-new-era-of-thoughtfulness
diff --git a/docs/navigation-context.md b/docs/navigation-context.md
@@ -17,7 +17,7 @@ const {
 ```
 
 <div class="grid cards" markdown>
-  -  [:octicons-arrow-right-24: See complete reference](../reference/types/#navigationcontextprops)
+  -  [:octicons-arrow-right-24: See complete reference](reference/types.md#navigationcontextprops)
      for `NavigationContext`
 </div>
 
@@ -73,5 +73,5 @@ the URL.
      for `navigateTo`
 </div>
 
-[saving]: ../reference/#saveandprocesspage
-[copyPage]: ../reference/#copypage
+[saving]: ./reference/index.md#saveandprocesspage
+[copyPage]: ./reference/index.md#copypage
diff --git a/docs/rails-utils.md b/docs/rails-utils.md
@@ -1,5 +1,6 @@
 # Rails utils
 
+
 ## `redirect_back_with_props_at`
 
 A helper to help retain the `props_at` parameter as part of the redirect `location`.
@@ -11,6 +12,58 @@ def create
 end
 ```
 
+## Rendering defaults
+
+Superglue typically requires 3 templates.
+
+```
+app/views/
+  posts/
+    index.html.erb # typically duplicated
+    index.jsx
+    index.json.props
+  users/
+    index.html.erb
+    index.jsx
+    index.json.props
+```
+
+Use `use_jsx_rendering_defaults` and `superglue_template` for cleaner
+directories.
+
+```ruby
+class PostsController < ApplicationController
+  before_action :use_jsx_rendering_defaults
+  superglue_template "application/superglue" #defaults to application/superglue
+end
+```
+
+Which will allow you to deduplicate the files:
+
+```
+app/views
+  application/
+    superglue.html.erb
+  posts/
+    index.jsx
+    index.json.props
+  users/
+    index.jsx
+    index.json.props
+```
+
+and allow for `props` files for cases where you don't need props.
+
+```
+app/views
+  application/
+    superglue.html.erb
+  posts/
+    index.jsx
+  users/
+    index.jsx
+```
+
 ## Setting the content location
 
 You can override the URL Superglue uses to display on the address bar and

diff --git a/docs/recipes/infinite-scroll.md b/docs/recipes/infinite-scroll.md
@@ -16,7 +16,7 @@ And continue off from our [pagination] recipe.
     We'll use the `beforeSave` callback to modify the payload before superglue
     saves it to the store. This callback is an option for both `visit` and
     `remote` functions. See the
-    [beforeSave reference](../reference/types.requests/#beforesave-2) for more details.
+    [beforeSave reference](../reference/types.requests.md#beforesave-2) for more details.
 
 ```diff
 // app/views/posts/index.js

diff --git a/docs/recipes/modals.md b/docs/recipes/modals.md
@@ -40,7 +40,7 @@ Both urls render a list of posts. Lets set up the controller and the
         Similarly, we tie the `componentIdentifier` to the same page component.
 
         **Vite Users** This step can be entirely optional if you're using Vite. See
-        the [recipe](recipe/vite.md) for more information.
+        the [recipe](./vite.md) for more information.
 
     ```js
     import PostIndex from '../views/posts/index'

diff --git a/docs/recipes/ssr.md b/docs/recipes/ssr.md
@@ -33,7 +33,7 @@ setHumidRenderer((json, baseUrl, path) => {
       // and `remote` thunks.
       baseUrl={baseUrl}
       // The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
-      // template, e.g., index.html.erb
+      // template, e.g., application/superglue.html.erb
       initialPage={initialState}
       // The initial path of the page, e.g., /foobar
       path={path}
@@ -125,9 +125,14 @@ Add a line to your `package.json` like so:
 +    "build:ssr": "node ./build-ssr.mjs"
 ```
 
-Use `Humid.render` in all your ERB templates `index.html.erb`:
+Use `Humid.render` in all your ERB templates `superglue.html.erb`:
 
 ```diff
+  <script type="text/javascript">
+-   window.SUPERGLUE_INITIAL_PAGE_STATE=<%= render_props %>;<%# erblint:disable ErbSafety %>
++   <% initial_state = render_props %>
++   window.SUPERGLUE_INITIAL_PAGE_STATE=<%= initial_state %>;<%# erblint:disable ErbSafety %>
+  </script>
 - <div id="app"></div>
 + <div id="app"><%= Humid.render(initial_state, request.scheme + '://' + request.host_with_port, request.fullpath).html_safe %></div>
 ```

diff --git a/docs/recipes/vite.md b/docs/recipes/vite.md
@@ -45,7 +45,7 @@ And finally, one of the more manual process of using superglue is the [manual bu
 of your `page_to_page_mapping.js` file. We can improve the developer experience by 
 removing that step by using this snippet:
 
-[manual build]: ../configuration
+[manual build]: ../configuration.md
 
 ```javascript
 const pageIdentifierToPageComponent = {}

diff --git a/docs/requests.md b/docs/requests.md
@@ -5,7 +5,7 @@ offers, Superglue comes with two functions built around `fetch`, `visit` and
 `remote`. These are wrapped with your own implementation in
 [application_visit.js] and can be accessed via the [NavigationContext].
 
-[NavigationContext]: ../reference/types/#navigationcontextprops
+[NavigationContext]: reference/types.md#navigationcontextprops
 
 
 !!! tip

diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -25,20 +25,38 @@ Lets begin by adding a route and a controller to an app.
 === "`greet_controller.rb`"
     in `app/controllers/greet_controller.rb`
 
+    !!! tip Enable jsx rendering defaults
+        `use_jsx_rendering_defaults` enables Rails to look for `.jsx` files and
+        pairs with `.props` files. For example:
+
+        ```
+        app/views
+          application/
+            superglue.html.erb
+          about/
+            index.jsx
+          users/
+            index.jsx
+            index.json.props
+        ```
+
     ```ruby
     class GreetController < ApplicationController
+      before_action :use_jsx_rendering_defaults
+
       def show
       end
     end
     ```
 
 ### Add the views
 
-Next lets add the following views. Here we're splitting the usual `show.html.erb` into 3 parts:
-
+Next lets add the following views.
 - `app/views/greet/show.json.props`
-- `app/views/greet/show.js`
-- `app/views/greet/show.html.erb`
+- `app/views/greet/show.jsx`
+
+The Superglue installation generator also adds a `application/superglue.html.erb`, which
+will be used as the default html template for every controller action.
 
 Click the tabs below to see the contents:
 
@@ -72,7 +90,7 @@ Click the tabs below to see the contents:
         body,
         footer
       } = useContent();
-  
+
       const {greet} = body
 
       return (
@@ -84,22 +102,15 @@ Click the tabs below to see the contents:
     }
     ```
 
-=== "3. `show.html.erb`"
-
-    !!! info
-        This file is usually generated by a scaffold and stays exactly the same
-        regardless if its `index.html.erb`, `show.html.erb`, `edit.html.erb`, etc.
+=== "3. `application/superglue.html.erb`"
 
 
     ```ruby
-    <% initial_state = controller.render_to_string(formats: [:json], locals: local_assigns, layout: true) %>
-
     <script type="text/javascript">
-      window.SUPERGLUE_INITIAL_PAGE_STATE=<%= initial_state.html_safe %>;<%# erblint:disable ErbSafety %>
+      window.SUPERGLUE_INITIAL_PAGE_STATE=<%= render_props %>;<%# erblint:disable ErbSafety %>
     </script>
 
     <div id="app"></div>
-
     ```
 
     This file renders `show.json.props`, injects it globally as the initial
@@ -108,10 +119,10 @@ Click the tabs below to see the contents:
 
 ### Connect the dots
 
-The json [payload] that gets rendered into `show.html.erb` contains an the
-`componentIdentifier`. We're going to use the `componentIdentifier` to tie
-`show.json.props` to `show.js` so superglue knows which component to render
-with which response by modifying `app/javascript/page_to_page_mapping.js`.
+The json [payload] that gets injected contains a `componentIdentifier`.  We're
+going to use the `componentIdentifier` to tie `show.json.props` to `show.js` so
+superglue knows which component to render with which response by modifying
+`app/javascript/page_to_page_mapping.js`.
 
   [payload]: page-response.md
 
@@ -121,7 +132,7 @@ with which response by modifying `app/javascript/page_to_page_mapping.js`.
     gets rendered. In our case: http://localhost:3000/greet.json
 
     **Vite Users** This step can be entirely optional if you're using Vite. See
-    the [recipe](/superglue/recipes/vite/) for more information.
+    the [recipe](recipes/vite.md) for more information.
 
 === "1. Example `greet.json`"
     The layout for `show.json.props` is located at `app/views/layouts/application.json.props`. It

diff --git a/superglue/lib/types/index.ts b/superglue/lib/types/index.ts
@@ -472,7 +472,7 @@ export interface BuildVisitAndRemote {
 export interface SetupProps {
   /**
    * The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
-   * template, e.g., index.html.erb
+   * template, e.g., application/superglue.html.erb
    */
   initialPage: VisitResponse
   /**
@@ -517,7 +517,7 @@ export interface ApplicationProps
   extends React.ComponentPropsWithoutRef<'div'> {
   /**
    * The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
-   * template, e.g., index.html.erb
+   * template, e.g., application/superglue.html.erb
    */
   initialPage: VisitResponse
   /**