[Documentation] hello upward tutorial

[jcalcaben]

Description

Creates a three part tutorial that show a "from scratch" approach of creating a web application backed by an UPWARD server.

Related Issue

Closes #1046

Motivation and Context

There have been a lot of questions on how people can get started from scratch.
It also helps to teach basic UPWARD concepts.

Verification Steps

React project created following the steps described in the tutorials.

How Has This Been Tested?

n/a

Screenshots / Screen Captures (if appropriate):

n/a

Proposed Labels for Change Type/Package

documentation
devdocs

Checklist:

• I have read the CONTRIBUTING document.
• I have linked an issue to this PR.
• I have indicated the change type and relevant package(s).
• I have proposed a change level by adding one of the version: Major, version: Minor, or version: Patch labels based on the defined Public API.
• I have updated the documentation accordingly, if necessary.
• I have added tests to cover my changes, if necessary.
• All new and existing tests passed.
• All CI checks are green (linting, build/deploy, etc).
• At least one core contributor has approved this PR.

[vercel]

This pull request is automatically deployed with Now.
To access deployments, click Details below or on the icon next to each push.

[supernova-at]

This is great and will really help people!

[supernova-at]

I think the partials are overkill for this tutorial.

Since this isn't a tutorial on Mustache, I think the hello-world.mst template could just contain all of this.

[jcalcaben]

I agree that partials add some complexity for a simple tutorial. However, this pattern is used in the Venia implementation. Readers will undoubtedly draw comparisons between what's in the Venia source and how we're telling them to do something.

[supernova-at]

I think this topic can be made much simpler by getting rid of all the "extras" around React.

Since React doesn't actually need JSX you can get rid of the dependency on babel and webpack here.

Check it out:

hello-world.mst

{{> templates/open-document}}

<title>{{ title }}</title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react/16.8.6/umd/react.production.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react-dom/16.8.6/umd/react-dom.production.min.js"></script>

{{> templates/open-body}}

<div id="root">Loading...</div>

<script defer src="/app.js"></script>

{{> templates/close-document}}

Notice that the template is pulling in React and React DOM from CDNs. This eliminates the need to install them locally.

app.js

const App = () => {
    return React.createElement(
        'h1',
        null,
        'Hello World from React!'
    );
};

ReactDOM.render(
    React.createElement(App),
    document.getElementById('root')
);

Notice that we aren't using JSX here and instead using the React.createElement function directly. This is what Babel does for you.

The only thing left to do is fix up the UPWARD spec a bit:

status: response.status
headers: response.headers
body: response.body

response:
  resolver: conditional
  when:
      - matches: request.url.pathname
        pattern: '^/?$'
        use: helloWorld
      - matches: request.url.pathname
        pattern: '^/hello-world/?$'
        use: helloWorld
      - matches: request.url.pathname
        pattern: '^/app.js$'
        use: appScript
  default: notFound

helloWorld:
  inline:
      status:
          resolver: inline
          inline: 200
      headers:
          resolver: inline
          inline:
              content-type:
                  resolver: inline
                  inline: 'text/html'
      body:
          resolver: template
          engine: mustache
          template: './templates/hello-world.mst'
          provide:
            title:
              resolver: inline
              inline: 'This is the page title!'
notFound:
    inline:
        status:
            resolver: inline
            inline: 404
        headers:
            resolver: inline
            inline:
                content-type:
                    resolver: inline
                    inline: 'text/string'
        body:
            resolver: inline
            inline: 'Page not found!'

appScript:
  inline:
    status:
      resolver: inline
      inline: 200
    headers:
      resolver: inline
      inline:
        content-type:
          resolver: inline
          inline: 'application/javascript'
    body:
      resolver: file
      file:
        resolver: inline
        inline: './app.js'
      encoding:
        resolver: inline
        inline: 'utf-8'

---

Since this is an UPWARD tutorial, I think this greatly simplifies the topic and introduces readers to the FileResolver more quickly.

We probably want to include a paragraph about how production code should use webpack and babel but I don't think they need to be introduced in this tutorial.

[jcalcaben]

Even though it's billed as an UPWARD tutorial, I also wanted the end result of doing this tutorial to be an environment that the reader can use as a starting point for their PWA Studio projects. This is something the community has been asking us for.

It's true that React doesn't require JSX, but most examples out there use JSX and ES6 syntax. I think it would be a bad experience for developers if we introduce how something is done in the tutorial and promote something very different in the implementation code.

[supernova-at]

Two minor edits that I think will help differentiate the use cases and give instant feedback to someone going through the tutorial.

Take 'em or leave 'em 😄