Merge branch 'develop' into pwa-1074-storybook-again-again-again

pwa-devdocs/src/_data/home-sections.yml

@@ -4,7 +4,7 @@
 
 - title: Tutorials
   content: Step-by-step instructions to help you become familiar with PWA Studio tools and concepts.
-  url: /tutorials/pwa-studio-fundamentals/
+  url: /tutorials/
 
 - title: Basic Concepts
   content: Things you need to know to work with the Magento PWA Studio tools.

pwa-devdocs/src/_data/tutorials.yml

@@ -1,63 +1,45 @@
 title: Tutorials
+
 entries:
-    - label: Overview
+    - label: Getting Started
       url: /tutorials/
+      entries:
+
+          - label: Setup your project
+            url: /tutorials/pwa-studio-fundamentals/project-setup/
 
-    - label: Magento Cloud deployment
-      url: /tutorials/cloud-deploy/
+          - label: Explore the project structure
+            url: /tutorials/pwa-studio-fundamentals/project-structure/
 
-    - label: Hello UPWARD
+    - label: Basic modifications
       entries:
-          - label: Creating a simple server
-            url: /tutorials/hello-upward/simple-server/
 
-          - label: Using the TemplateResolver
-            url: /tutorials/hello-upward/using-template-resolver/
+          - label: Enable SASS or LESS support
+            url: /tutorials/enable-sass-less-support/
 
-          - label: Adding React
-            url: /tutorials/hello-upward/adding-react/
+          - label: Add a static route
+            url: /tutorials/pwa-studio-fundamentals/add-a-static-route/
 
-    - label: Create a TagList component
-      url: /tutorials/create-taglist-component/
+          - label: Modify the site footer
+            url: /tutorials/pwa-studio-fundamentals/modify-site-footer/
 
-    - label: Enable SASS or LESS support
-      url: /tutorials/enable-sass-less-support/
+          - label: Create a TagList component
+            url: /tutorials/create-taglist-component/
 
-    - label: Intercept a Target
+    - label: Target interception
       url: /tutorials/intercept-a-target/
       entries:
+
           - label: Modify talon results
             url: /tutorials/intercept-a-target/modify-talon-results/
 
           - label: Add a new environment variable
             url: /tutorials/intercept-a-target/add-new-environment-variable/
 
-    - label: PWA Studio fundamentals
-      url: /tutorials/pwa-studio-fundamentals/
+    - label: Production deployments
+      url: /tutorials/pwa-studio-fundamentals/production-launch-checklist/
       entries:
-          - label: Project setup
-            url: /tutorials/pwa-studio-fundamentals/project-setup/
-
-          - label: Project structure
-            url: /tutorials/pwa-studio-fundamentals/project-structure/
-
-          - label: Add a static route
-            url: /tutorials/pwa-studio-fundamentals/add-a-static-route/
-
-          - label: Modify the site footer
-            url: /tutorials/pwa-studio-fundamentals/modify-site-footer/
-
-          - label: Using component props
-            url: /tutorials/pwa-studio-fundamentals/using-component-props/
-
-          - label: CSS modules
-            url: /tutorials/pwa-studio-fundamentals/css-modules/
-
-          - label: Manage state
-            url: /tutorials/pwa-studio-fundamentals/manage-state/
 
-          - label: Work with GraphQL
-            url: /tutorials/pwa-studio-fundamentals/work-with-graphql/
+          - label: Deploy to Magento Cloud
+            url: /tutorials/cloud-deploy/
 
-          - label: Production launch checklist
-            url: /tutorials/pwa-studio-fundamentals/production-launch-checklist/

pwa-devdocs/src/_includes/layout/toc.html

@@ -10,7 +10,7 @@ <h4 class="guide-title">{{toc.title}}</h4>
             {% if entry.url %}
             <a href="{{ site.baseurl }}{{ entry.url }}" class="spectrum-SideNav-itemLink {% if entry.css-classes %}{{entry.css-classes}}{% endif %} {% if entry.entries.size > 0 %}parent{% endif %}">{{ entry.label }}</a>
             {% else %}
-            <span class="spectrum-SideNav-heading">{{ entry.label }}</span>
+            <span class="spectrum-SideNav-itemLink">{{ entry.label }}</span>
             {% endif %}
 
             {% if entry.entries.size > 0 %}

pwa-devdocs/src/frequently-asked-questions/index.md

@@ -26,8 +26,6 @@ The Tutorials section of this site contains a number of tutorials which cover cu
 
 -   [How to add a static route][]
 -   [How to modify the site footer][]
--   [How to use component props][]
--   [How to use CSS modules][]
 
 ## Are there any live stores built using PWA Studio
 
@@ -101,10 +99,6 @@ _**Note:** For testing, resize the viewport manually instead of using the native
 
 [how to modify the site footer]: <{%link tutorials/pwa-studio-fundamentals/modify-site-footer/index.md %}>
 
-[how to use component props]: <{%link tutorials/pwa-studio-fundamentals/using-component-props/index.md %}>
-
-[how to use css modules]: <{%link tutorials/pwa-studio-fundamentals/css-modules/index.md %}>
-
 [magento cloud deployment]: <{% link tutorials/cloud-deploy/index.md %}>
 
 [project repository]: https://github.com/magento/pwa-studio

pwa-devdocs/src/peregrine/routing/index.md

@@ -26,8 +26,6 @@ Early versions of the Venia storefront used this approach, but
 in the current version, every page request now returns the same HTML with the application shell.
 The application decides how the page should render based on the request.
 
-If you want a better idea of how UPWARD works, follow the [Hello UPWARD tutorial][].
-
 ### Client-side routing
 
 Client-side routing happens inside the storefront application.
@@ -73,7 +71,6 @@ The [`resolveUnknownRoute()`][] function is a utility function for fetching page
 The `getRouteComponent()` function uses the information from this query to get the correct root component from an object that maps page types to root components.
 
 [upward]: {%link venia-pwa-concept/features/modular-components/index.md %}
-[hello upward tutorial]: {%link tutorials/hello-upward/simple-server/index.md %}
 [peregrine talon]: {%link peregrine/talons/index.md %}
 
 [app component]: https://github.com/magento/pwa-studio/blob/develop/packages/venia-ui/lib/components/App/app.js

pwa-devdocs/src/tutorials/cloud-deploy/index.md

@@ -25,6 +25,9 @@ This tutorial requires the following tools:
 
 If you need to do more advanced Cloud tasks, see the [Cloud technologies and requirements][] for the full list of tools you need to fully manage the rest of your Cloud project.
 
+You also need an existing storefront project to do this tutorial.
+Follow the instructions on the [Project setup][] page to set up your storefront project using the scaffolding tool.
+
 ## Tasks overview
 
 1. Clone your Cloud project
@@ -162,13 +165,14 @@ To find the correct root directory path for an environment, [SSH][] into the rem
 
 ## Build your storefront application
 
-In _your storefront project_ directory, use `yarn` or `npm` to run the project's build command.
+In _your storefront project_ directory, use `yarn` or `npm` to install project dependencies and run the project's build command.
 
 ```sh
+yarn install &&
 yarn build
 ```
 
-This command runs the build process, which creates a `dist` folder that contains code bundles for your storefront application.
+These commands install project dependencies and runs the build process, which creates a `dist` folder that contains code bundles for your storefront application.
 It also copies over the static assets your application needs from your project into this folder.
 
 ## Add your storefront project code
@@ -218,6 +222,7 @@ variables, such as `CONFIG__DEFAULT__WEB__UPWARD__PATH` and `MAGENTO_BACKEND_URL
 
 [compatible]: <{%link technologies/magento-compatibility/index.md %}>
 [environment variables]: <{%link pwa-buildpack/reference/environment-variables/core-definitions/index.md %}>
+[project setup]: <{%link tutorials/pwa-studio-fundamentals/project-setup/index.md %}>
 
 [magento pwa studio]: http://pwastudio.io
 [`@magento/venia-concept`]: https://www.npmjs.com/package/@magento/venia-concept

pwa-devdocs/src/tutorials/index.md

@@ -1,26 +1,32 @@
 ---
-title: Tutorials
+title: Getting started
 ---
 
-This section contains links to tutorials that will help you become familiar with the different tools provided by PWA Studio.
+PWA Studio is a library of tools and packages designed to help you create a Magento PWA storefront.
+In this section you will learn how to set up your storefront project using the scaffolding tool and learn about the different files and folders in your project.
 
-## Recommended tutorials
+## Prerequisites
 
-### UPWARD
+-   A basic understanding of working with [React][]
+-   Node >= 10.14.1
+-   Yarn (recommended) or NPM
 
-This three part tutorial provides an introduction to the concepts introduced in the UPWARD spec.
-By the end of this tutorial, you should have a simple React application running on top of an UPWARD server.
+### Node 12 deprecation warning
 
-1.  [Creating a simple UPWARD server][] - Teaches the very basics of reading and writing an UPWARD specification file for your projects
-2.  [Using the TemplateResolver][] - Introduces the concept of using templates and the TemplateResolver to keep your UPWARD specification file lean
-3.  [Adding React][] - Add React and Webpack into your UPWARD project
+If you are using Node 12, you may see the following deprecation warning in the log when you run `yarn watch:venia`.
 
-### Magento Cloud deployment
+```sh
+(node:89176) [DEP0066] DeprecationWarning: OutgoingMessage.prototype._headers is deprecated
+```
 
-[Magento Cloud deployment][] - Provides steps for deploying a PWA Studio storefront into the Magento Cloud.
-This tutorial uses the Venia example storefront to illustrate the general process.
+This is caused by a project dependency used by PWA Studio and not by PWA Studio itself.
 
-[creating a simple upward server]: <{%link tutorials/hello-upward/simple-server/index.md%}>
-[using the templateresolver]: <{%link tutorials/hello-upward/using-template-resolver/index.md%}>
-[adding react]: <{%link tutorials/hello-upward/adding-react/index.md%}>
-[magento cloud deployment]: <{%link tutorials/cloud-deploy/index.md %}>
+## First steps
+
+-   [Setup your project][]
+-   [Explore the project structure][]
+
+[setup your project]: <{%link tutorials/pwa-studio-fundamentals/project-setup/index.md %}>
+[explore the project structure]: <{%link tutorials/pwa-studio-fundamentals/project-structure/index.md %}>
+
+[react]: https://reactjs.org/

pwa-devdocs/src/tutorials/intercept-a-target/index.md

@@ -1,5 +1,5 @@
 ---
-title: Intercept a Target
+title: Target interception
 ---
 
 Target interception is a feature provided by PWA Studio's extensibility framework.

pwa-devdocs/src/tutorials/pwa-studio-fundamentals/index.md

@@ -33,10 +33,6 @@ This is caused by a project dependency used by PWA Studio and not by PWA Studio
 -   [Project Structure][] - Learn about the project structure of your new project
 -   [Add a static route][] - Add a static route to your PWA Studio app
 -   [Modify the site footer][] - Learn how to modify existing components by modifying the site footer
--   [Using component props][] - Learn how to use props in your custom components
--   [CSS modules][] - Learn how to use CSS modules in you custom components
--   [Manage state][] - Learn how to manage internal and global state in your components
--   [Work with GraphQL][] - Learn how to work with GraphQL from Magento
 -   [Production launch checklist][] - Make sure your storefront is production ready with this checklist
 
 ## Related content
@@ -51,10 +47,6 @@ This is caused by a project dependency used by PWA Studio and not by PWA Studio
 [project structure]: {%link tutorials/pwa-studio-fundamentals/project-structure/index.md %}
 [add a static route]: {%link tutorials/pwa-studio-fundamentals/add-a-static-route/index.md %}
 [modify the site footer]: {%link tutorials/pwa-studio-fundamentals/modify-site-footer/index.md %}
-[using component props]: {%link tutorials/pwa-studio-fundamentals/using-component-props/index.md %}
-[css modules]: {%link tutorials/pwa-studio-fundamentals/css-modules/index.md %}
-[manage state]: {%link tutorials/pwa-studio-fundamentals/manage-state/index.md %}
-[work with graphql]: {%link tutorials/pwa-studio-fundamentals/work-with-graphql/index.md %}
 [production launch checklist]: {%link tutorials/pwa-studio-fundamentals/production-launch-checklist/index.md %}
 
 [react]: https://reactjs.org/

pwa-devdocs/src/tutorials/pwa-studio-fundamentals/project-setup/index.md

@@ -137,6 +137,10 @@ Apply these fixes to address common issues you may encounter during project setu
 
 If you encounter any other issues, ask the Magento community in the [#PWA][] Slack channel.
 
+## Next
+
+[Explore the project structure][]
+
 [scaffolding]: {%link pwa-buildpack/scaffolding/index.md %}
 [peregrine]: {%link peregrine/index.md %}
 [venia concept storefront]: {%link venia-pwa-concept/index.md %}
@@ -149,6 +153,7 @@ If you encounter any other issues, ask the Magento community in the [#PWA][] Sla
 [compiled successfully screen-shot]: {%link tutorials/pwa-studio-fundamentals/project-setup/images/compiled-successfully.png %}
 [clear storage]: {%link tutorials/pwa-studio-fundamentals/project-setup/images/clear-storage.png %}
 [privacy error]: {%link tutorials/pwa-studio-fundamentals/project-setup/images/privacy-error.png %}
+[explore the project structure]: <{%link tutorials/pwa-studio-fundamentals/project-structure/index.md %}>
 
 [venia.magento.com]: http://venia.magento.com/
 [n]: https://github.com/tj/n

pwa-devdocs/src/tutorials/pwa-studio-fundamentals/project-structure/index.md

@@ -129,6 +129,20 @@ Use the following values for `NODE_ENV`:
 
 For more information on loading environment variables, see: [Load environment file][]
 
+## Next steps
+
+Now that you have a storefront project setup and understand its structure, lets learn about some basic customizations you can make to your project:
+
+-   [Enable SASS or LESS support][]
+-   [Add a static route][]
+-   [Modify the site footer][]
+-   [Create a TagList component][]
+
+
+[enable sass or less support]: <{%link tutorials/enable-sass-less-support/index.md %}>
+[add a static route]: <{%link tutorials/pwa-studio-fundamentals/add-a-static-route/index.md %}>
+[modify the site footer]: <{%link tutorials/pwa-studio-fundamentals/modify-site-footer/index.md %}>
+[create a taglist component]: <{%link tutorials/create-taglist-component/index.md %}>
 [modular components]: <{%link venia-pwa-concept/features/modular-components/index.md %}>
 [project setup]: <{%link tutorials/pwa-studio-fundamentals/index.md %}>
 [`configurewebpack`]: <{%link pwa-buildpack/reference/configure-webpack/index.md %}>