From a82dec1ad73b1239a2d72985d97b8a6858b139e8 Mon Sep 17 00:00:00 2001
From: Robert-Frampton <ROBERT.FRAMPTON@LIFERAY.COM>
Date: Tue, 3 Oct 2017 09:23:09 -0700
Subject: [PATCH] Documents metal/metal.js#267

---
 src/pages/docs/guides/isomorphic.md | 67 +++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 src/pages/docs/guides/isomorphic.md

diff --git a/src/pages/docs/guides/isomorphic.md b/src/pages/docs/guides/isomorphic.md
new file mode 100644
index 00000000..8ccc4b8b
--- /dev/null
+++ b/src/pages/docs/guides/isomorphic.md
@@ -0,0 +1,67 @@
+---
+title: "Isomorphic Rendering"
+description: "Server side rendering of Metal.js components."
+layout: "guide"
+weight: 240
+---
+
+<article id="server_rendering">
+
+## [Server Side Rendering](#server_rendering)
+
+In most cases Metal components will be rendered client side. Let's take the
+following component for example.
+
+```jsx
+import JSXComponent from 'metal-jsx';
+
+class MyComponent extends JSXComponent {
+	render() {
+		return <div>{this.props.message}</div>
+	}
+}
+
+MyComponent.PROPS = {
+	message: {
+		value: ''
+	}
+};
+
+export default MyComponent;
+```
+
+After transpiling/bundling this component. It can be invoked in client side
+JavaScript.
+
+```javascript
+const component = new metal.MyComponent({
+	message: 'Hello, World!'
+});
+
+// component.element.innerHTML === '<div>Hello, World!</div>'
+```
+
+Rendering a component this way requires DOM manipulation, and the existence of
+various global variables/utilities that are provided by web browsers. This
+means there is no way to render the HTML of this component in a Node.js
+environment without the help of libraries such as `JSDom` that emulate client
+functionality.
+
+However, thanks to the `Component.renderToString` method, out of the box server
+side rendering of Metal components is possible in Node.js environments.
+
+```javascript
+const Component = require('metal-component').Component;
+const MyComponent = require('./MyComponent').MyComponent;
+
+const htmlString = Component.renderToString(MyComponent, {
+	message: 'Hello, World!'
+});
+
+// htmlString === '<div>Hello, World!</div>'
+```
+
+Now all of your custom Metal components can be rendered directly to HTML on the
+server.
+
+</article>
\ No newline at end of file