improve www guide layouts, add routing guide

www/_template/guides.md

@@ -6,6 +6,8 @@ layout: layouts/content.njk
 
 Snowpack Guides are deep dives into popular Snowpack topics.
 
+- [Routing](/guides/routing)
+- [Server-Side Render](/guides/server-side-render)
 - [SSL, HTTPS, and HTTP/2 in Development](/guides/https-ssl-certificates)
 - [Connecting your dev tools](/guides/connecting-tools)
 - [Bundling for Deployment](/guides/bundling)

www/_template/guides/jest.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: 'Jest'
 ---
 

www/_template/guides/optimize.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: Optimize for production
 ---
 

www/_template/guides/react-global-imports.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: React + babel-plugin-import-global
 ---
 

www/_template/guides/react-loadable-components.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: React + Loadable Components
 ---
 

www/_template/guides/routing.md

@@ -0,0 +1,60 @@
+---
+layout: layouts/content.njk
+title: Routing
+---
+
+<div class="notification">
+Status: Experimental 
+</div>
+
+As a web build tool, Snowpack has no knowledge of how (or where) your application is served in production. But Snowpack's dev server can be customized to recreate something close to your production environment for local development.
+
+This guide will walk you through some common routing scenarios and how to configure the `routes` option to support them in development.
+
+### Scenario 1: SPA Fallback Paths
+
+Single Page Applications (SPA) give the client application complete control over routing logic. The web host itself has no idea what is a valid route and what is a 404, since that logic lives completely in the client. Therefore, every route (valid or not) must be served the the same HTML response that will load and run the HTML/JS/CSS application in the browser. This special file is called the "SPA Fallback".
+
+To implement this pattern, you'll want to define a single "catch-all" route for development:
+
+```js
+// snowpack.config.js
+"experiments": {
+    "routes": [
+        {"src": ".*", "dest": "/index.html", "match": "routes"}
+    ]
+}
+```
+
+This tells Snowpack's dev server to serve the fallback `/index.html` URL for all routes (`.*` in RegEx means "match everything").
+
+The term "route", in this case, refers to all URLs that either do not include a file extension or that include the ".html" file extension. If you changed the above example to `"match": "all"` instead, then all URLs (including JS and CSS files) would respond with the fallback HTML file. This wouldn't make much sense, which is why `"match": "routes"` is Snowpack's default when not explicitly included.
+
+### Scenario 2: Proxy API Paths
+
+Many modern frontend applications will talk directly to an API. Often this API is hosted as a seperate application at another domain (ex: `api.example.com/users`) and no special server configuration is needed to talk with it. However in some cases, your API may be hosted at the same domain as your website using a different path scheme (ex: `www.example.com/api/users`).
+
+To serve the correct API response to a URL like `/api/users` in development, you can configure Snowpack to proxy some requests to another server. In this example, we'll proxy all "/api/\*" requests to another server that we have running locally on port `3001`:
+
+```js
+// snowpack.config.js
+const httpProxy = require('http-proxy');
+const proxy = httpProxy.createServer({ target: 'http://localhost:3001' });
+
+module.exports = {
+  experiments: {
+    routes: [
+      {
+        src: '/api/.*',
+        dest: (req, res) => proxy.web(req, res),
+      },
+    ],
+  },
+};
+```
+
+We recommend the [http-proxy](https://github.com/http-party/node-http-proxy) library for proxying requests to another server, which supports a wide range of options to customize how each request is proxied. But feel free to implement the `dest` proxy function however you like. Your own server logic could even be called directly inside of the `dest` function, however this is not recommended over proxying.
+
+### Scenario 3: Custom Server Rendering
+
+If you only use Snowpack to build assets and rely on your own custom server (ex: Rails, Laravel, etc) for serving HTML, then you probably have no use for routing. Consider reading our guide on [Server-Side Rendering (SSR)](/guides/server-side-render) which explains how to integrate Snowpack into your own server as middleware.

www/_template/guides/sass.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: 'Sass'
 ---
 

www/_template/guides/server-side-render.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: Server-Side Rendering (SSR)
 ---
 
@@ -55,24 +55,4 @@ app.use((req, res, next) => {
 
 Note that you'll still need to set up static file serving out of the `build/` directory for production deployments. For that reason, this can be seen as an enhancement over the static setup in Option 1 for faster development speeds.
 
-### Bonus Option 3: via Snowpack Dev Server
-
-If your application is written in JavaScript exposed through a traditional Express-style JavaScript middleware function (`(req, res, next) => ...`) then you can integrate your application logic directly into Snowpack's dev server via `experiments.app`:
-
-```js
-// Example snowpack.config.js
-"experiments": {
-  "app": (req, res, next) => {
-    if (req.url === '/home') {
-      // Implement your own response.
-    }
-    if (req.url.startsWith('/api')) {
-      // Works to add API endpoints as well!
-    }
-    // Otherwise, let Snowpack's dev server handle it.
-    next();
-  }
-}
-```
-
-This can be great for rapid development and prototyping, but note that this support is limited: Snowpack's dev server is not designed to be run in production. For any real-world usage, you'll still want to run your own server logic using either of the other options outlined above.
+While our official API is written in JavaScript and requires Node.js to run, you could implement your own API for any language/environment using the `snowpack dev` CLI command to start the server and loading assets directly by fetching each URL.

www/_template/guides/tailwind-css.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: 'Tailwind CSS'
 ---
 

www/_template/guides/web-test-runner.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: '@web/test-runner'
 ---
 

www/_template/reference/hot-module-replacement.md

@@ -1,5 +1,5 @@
 ---
-layout: layouts/main.njk
+layout: layouts/content.njk
 title: Hot Module Replacement (HMR) API
 ---
 

www/src/css/components/_view.scss

@@ -73,6 +73,7 @@ $top-padding: 24px;
 
   .snow-view-main {
     grid-area: main;
+    overflow: hidden;
   }
   .snow-view-full {
     grid-row-start: main;