Add SSR guide

Author: CaerusKaru

guides/SSR.md

@@ -0,0 +1,87 @@
+# Using Flex Layout with Server-Side Rendering (SSR)
+
+### Introduction
+
+In the browser, Flex Layout works by utilizing the global `Window` object's 
+`MatchMedia` interface. When a breakpoint is activated/deactivated, the service
+informs the Flex directives, which inject CSS styles inline as necessary.
+
+Unfortunately, on the server, we have no access to the `MatchMedia` service,
+and so when the view is rendered for users using SSR, none of the responsive
+breakpoints (i.e. `fxFlex.sm`) are respected. This leads to a mismatch between
+the initial view generated by the server, and the bootstrapped view generated
+by the client.
+
+The solution provided allows Flex Layout to inject static CSS into the head of
+the DOM instead of inline, and taps in to the CSS `@media` breakpoint interface,
+instead of the dynamic JavaScript `MatchMedia` interface.
+
+This guide introduces how to incorporate this functionality into your apps, and
+the limitations to be aware of when using this utility.
+
+### Usage
+
+#### Option 1: Generate static CSS on the server
+
+1. Import the `FlexLayoutServerModule` into the server bundle for your app,
+generally called `app.server.module.ts`:
+
+```typescript
+import {NgModule} from '@angular/core';
+import {FlexLayoutServerModule} from '@angular/flex-layout/server';
+
+@NgModule(({
+  imports: [
+    ... other imports here
+    FlexLayoutServerModule,
+  ]
+}))
+export class AppServerModule {}
+```
+
+2. That's it! Your app should now be configured to use the server-side
+implementations of the Flex Layout utilities. 
+
+
+#### Option 2: Only generate inline styles (legacy option)
+
+1. Simply don't import the `FlexLayoutServerModule`. You'll receive a warning
+on bootstrap, but this won't prevent you from using the library, and the
+warning won't be logged on the client side
+
+
+#### Option 3: Generate no Flex Layout stylings on the server
+
+1. Don't import the `FlexLayoutServerModule`
+2. DO import the `SERVER_TOKEN` and provide it in your app as follows:
+
+```typescript
+import {SERVER_TOKEN} from '@angular/flex-layout';
+
+{provide: SERVER_TOKEN, useValue: true}
+```
+
+3. This will tell Flex Layout to not generate server stylings. Please note that
+if you provide this token *and* the `FlexLayoutServerModule`, stylings **will**
+still be rendered
+
+### Limitations
+
+One of the deficiencies of SSR is the lack of a fully-capable DOM rendering
+engine. As such, some functionality of the Flex Layout library is imparied.
+For instance, some Flex directives search for parent nodes with flex stylings
+applied to avoid overwriting styles. However, if those styles are defined in
+a style block, the external component styles, or another stylesheet, Flex Layout
+won't be able to find those styles on the server.
+
+The workaround for this is to **inline all Flex-related styles** as necessary. 
+For instance, if in an external stylesheet you have a class that applies
+`flex-direction` to an element, add that styling inline on the element the
+class is applied to. Chances are the impact of this will be minimal, and the
+stylings will be loaded correctly on bootstrap. However, it is an unfortunate 
+reality of SSR and the DOM implementation used on the server.
+
+### References
+
+The design doc for this utility can be found 
+[here](https://docs.google.com/document/d/1fg04ihw42dJJHGd6fugdiBe39iJot8aErhiE7CjwfmQ)