API Discussion: Why isn't template just a render function?

aickin commented 7 years ago

First off, congratulations on your launch! Nice job. 🚀🌈🔥 Also: thanks for having good docs!

It's great that you included static templates, but I'm a little confused about your choice to use template strings rather than just making another render function with plain old React elements. It seems to me that using template strings requires the developer to learn a second API (in addition to render), but that's not really required. If instead you made it a plain old function (called, say, `renderTemplate``), I think Rapscallion might have a more compact, learnable API.

To get a sense for what this would look like, the example in the template section would become:

import { render, renderTemplate } from "rapscallion";

// ...

app.get('/example', function(req, res){
  // ...

  const store = createStore(/* ... */);
  const componentRenderer = render(<MyComponent store={store} />);

  const responseRenderer = renderTemplate (
    <html>
    <body>
      {componentRenderer}
      <MyOtherComponent />
      <script>
        // Expose initial state to client store bootstrap code.
        window._initialState = {JSON.stringify(store.getState())};
        // Attach checksum to the component's root element.
        document.querySelector("#id-for-component-root").setAttribute("data-react-checksum", "{componentRenderer.checksum()}")
        // Bootstrap your application here...
      </script>
    </body>
    </html>
  );

  responseRenderer.toStream().pipe(res);
});

This also gets rid of the need to support callbacks in the templated strings, I think. Thoughts?

divmain commented 7 years ago

There are a couple of reasons for this. React doesn't support conditional comments or doctype tags, and it looks like that's not something that will change. If you need to inject <script> tags for analytics purposes, or really for anything aside from your React components, it gets a bit clunky.

In all of our sizable projects, we always end needing these things, and the template tag approach was the most ergonomic I came up with. I'd be open to a lower-level API that the template tag relied upon, but that you could also invoke directly. Definitely interested in your thoughts and ideas here.

cescoferraro commented 7 years ago

@divmain First off, thanks for the worderful library! I have been waiting for this in a long time!

I was about to open the same issue. Because the first instinct when finding out about the library was to search for renderToStaticMarkup function. The analogous non streaming react-dom/server module exposes a single object with just two methods on it. It would be nice if we could follow the Principle_of_least_astonishment, and make the API's match

Similar to renderToString, except this doesn't create extra DOM attributes such as data-reactid, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes.

https://facebook.github.io/react/docs/react-dom-server.html

I ended up doing the following on the server

        withAsyncComponents(ServerApp)
            .then((result) => {
                //  Instead of
                // response.send("<!DOCTYPE html>" +
                //     ReactDOMServer.renderToStaticMarkup(
                //         <HTML userAgent={userAgent} css={css} result={result}/>
                //     ));
                // I am doing
                   template`${<HTML userAgent={userAgent} css={css} result={result}/>}`
                    .toStream().pipe(response);  
                // Proposed
                   renderToStaticMarkup(<HTML userAgent={userAgent} css={css} result={result}/>)
                    .toStream().pipe(response);  
        });

Which makes me wonder. why not just alias the templete function so the API actually match.

It seems to me that creating another templating language instead of using react itself does not actually follow the Unix_philosophy . But I am probably overlooking things. I have never tried to add analytics to react.

There are a couple of reasons for this. React doesn't support conditional comments or doctype tags, and it looks like that's not something that will change. If you need to inject Githubissues.
Githubissues is a development platform for aggregating issues.

FormidableLabs / rapscallion

API Discussion: Why isn't template just a render function? #47