Skip to content

Commit f6cfabf

Browse files
oivindhagenoivindhagen
committed
Finish readme, clean up code.
1 parent 8f4a373 commit f6cfabf

5 files changed

Lines changed: 227 additions & 59 deletions

File tree

‎Docs/README.MD‎

Lines changed: 192 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,13 @@
22
SSR.Net
33
============
44

5-
SSR.Net makes it possible to server side render components in React 17, React 18 and Vue 3. It is open for extension, and can support other frameworks. It aims to be a performant, minimalistic way to support SSR in .Net.
5+
SSR.Net enables you to Server Side Render (SSR) components in React 17, React 18 and Vue 3 in .Net Framework/Core/5/6/7. It is open for extension and can support other frontend frameworks. It aims at being a performant, minimalistic way to support SSR in .Net.
6+
67
It is based on many of the ideas in ReactJS.Net: https://github.com/reactjs/React.NET.
7-
This README is not finished yet.
8+
9+
**Table of Contents**
10+
11+
[TOC]
812

913
## Installation
1014
This library can be installed through NuGet. You will also need to install a JavaScriptEngineSwitcher engine and native engine libraries according to your environment.
@@ -21,18 +25,63 @@ The easiest way to get started is to copy or look at one of the example projects
2125
To build frontend, just run the build scripts in package.json.
2226

2327
To configure and use SSR.Net, you need to do several things:
24-
* Build a JavaScript bundle fit for SSR
25-
* Set up a web project
26-
* Set up a controller and a view
28+
* [Build a JavaScript bundle fit for SSR](#Building-a-JavaScript-bundle-fit-for-SSR)
29+
* [Set up a web project](#set-up-a-web-project)
30+
* [Set up a controller and a view](#Set-up-a-controller-and-a-view)
2731

2832
We will look at how to do this for React 18 and .Net 6 in the following chapters. There are examples for React 17, React 18 and Vue 3 for both .Net Framework and .Net 6 in the code base. The examples in .Net 6 should be quite descriptive for .Net Core 2 and forward.
2933

3034
### Building a JavaScript bundle fit for SSR
3135

32-
Create a bundle with some components. For React 18, there is an example here: https://github.com/knowit/SSR.Net/tree/main/src/Frontend/React18Source
36+
We start by creating a bundle with some components. For React 18, there is an example here: https://github.com/knowit/SSR.Net/tree/main/src/Frontend/React18Source
37+
38+
We will create a FrontPage component for this example (source code here: https://github.com/knowit/SSR.Net/blob/main/src/Frontend/React18Source/src/Components/FrontPage.tsx).
39+
40+
```
41+
import React, { useState } from "react";
42+
43+
interface Link {
44+
text: string;
45+
href: string;
46+
}
47+
48+
interface Props {
49+
header?: string;
50+
links?: Link[];
51+
}
52+
53+
const FrontPage = ({ header, links }: Props) => {
54+
const [expanded, setExpanded] = useState(false);
55+
return (
56+
<div>
57+
<h1>{header}</h1>
58+
{links && (
59+
<>
60+
<button onClick={() => setExpanded(!expanded)}>Expand links</button>
61+
{expanded && (
62+
<ul>
63+
{links.map((link, idx) => (
64+
<li key={idx}>
65+
<a href={link.href}>{link.text}</a>
66+
</li>
67+
))}
68+
</ul>
69+
)}
70+
</>
71+
)}
72+
</div>
73+
);
74+
};
75+
76+
export default FrontPage;
77+
78+
```
3379

34-
Expose the React, ReactDOMServer and ReactDOMClient libraries as global variables. Also expose your components somehow. See an example of how this is done here:
80+
This component has a simple expand/collapse function. This will show us that React is actually working interactively on the client side.
81+
82+
We then create an entry point for our bundle. Here, we expose the React, ReactDOMServer and ReactDOMClient libraries as global variables. We also expose the components we've created. It works well to just import them all and add them to a global Components variable. See an example of how this is done here:
3583
https://github.com/knowit/SSR.Net/blob/main/src/Frontend/React18Source/src/app.tsx
84+
3685
```
3786
import * as React from 'react'
3887
import * as ReactDOMServer from 'react-dom/server'
@@ -46,13 +95,28 @@ globalThis.ReactDOMClient = ReactDOMClient;
4695
globalThis.Components = {FrontPage, ArticlePage};
4796
```
4897

49-
For .Net 6 the resulting js bundle is build to the wwwroot folder as react18example.js: https://github.com/knowit/SSR.Net/tree/main/src/SSR.Net.DotNet6/wwwroot
98+
In this simple example we use esbuild alone to build the bundle, but it's no problem to use Webpack. You can also use Vite, but you will need to turn off the built in minification and find a different way of minifying it, otherwise the global variables will be removed from the bundle during tree shaking. The esbuild command we use is in the package.json (https://github.com/knowit/SSR.Net/blob/main/src/Frontend/React18Source/package.json):
99+
100+
```
101+
"scripts": {
102+
...
103+
"build-dotnet6": "esbuild ./src/app.tsx --bundle --outfile=../../SSR.Net.DotNet6/wwwroot/react18example.js"
104+
},
105+
```
106+
107+
We run this through npm:
108+
109+
```
110+
npm run build-dotnet6
111+
```
112+
113+
The resulting js bundle is build to the wwwroot folder in the DotNet6 project as react18example.js: https://github.com/knowit/SSR.Net/tree/main/src/SSR.Net.DotNet6/wwwroot
50114

51115
### Set up a web project
52116

53-
An example of this is set up here: https://github.com/knowit/SSR.Net/tree/main/src/SSR.Net.DotNet6
117+
Let's look at this example web project: https://github.com/knowit/SSR.Net/tree/main/src/SSR.Net.DotNet6
54118

55-
Create an extension method for adding a React18Renderer to IoC. Here is an example:
119+
We have an extension method for adding a React18Renderer to IoC, which is the normal way of adding things to .Net Core and forward:
56120
https://github.com/knowit/SSR.Net/blob/main/src/SSR.Net.DotNet6/Services/ServiceCollectionExtensionsReact18SSR.cs
57121

58122
```
@@ -76,8 +140,13 @@ namespace SSR.Net.DotNet6.Services
76140
}
77141
```
78142

79-
We use the V8 JavaScript engine for this example, and configure a new JavaScriptEnginePool. To make this work, you have to add some packages to your web project. See this file for reference:
143+
The code above adds both a server side polyfill named React18TextEncoderPolyfill.js (React 18 needs this, and it's missing in the Java Script Engine), and the bundle we created in [Building a JavaScript bundle fit for SSR](#Building-a-JavaScript-bundle-fit-for-SSR), react18example.js. These script files will be run on each server side JavaScript engine during initialization. This means that each JavaScript engine on the server side will be able to run React, ReactDOMServer, ReactDOMClient and access our FrontPage component through the global variable Components.
144+
145+
We use the V8 JavaScript engine in this example. This, and the scripts, is configured in a JavaScriptEnginePool. This pool will manage JavaScript engines, create new ones proactively, dispose exhausted engines and be a broker for the actual rendering commands.
146+
147+
To make this work, we have to reference some packages in our web project:
80148
https://github.com/knowit/SSR.Net/blob/main/src/SSR.Net.DotNet6/SSR.Net.DotNet6.csproj
149+
81150
```
82151
<PackageReference Include="JavaScriptEngineSwitcher.Core" Version="3.19.0" />
83152
<PackageReference Include="JavaScriptEngineSwitcher.V8" Version="3.20.10" />
@@ -86,9 +155,7 @@ https://github.com/knowit/SSR.Net/blob/main/src/SSR.Net.DotNet6/SSR.Net.DotNet6.
86155
<PackageReference Include="Microsoft.ClearScript.V8.Native.win-x86" Version="7.3.7" />
87156
```
88157

89-
Then we add a server side polyfill named React18TextEncoderPolyfill.js, and react18example.js (our bundle, with React 18, the components and the global variables). These script files will be run on each server side JavaScript engine during initialization.
90-
91-
After this is done, we call the extension method during the initialization of our program. See this file for reference: https://github.com/knowit/SSR.Net/blob/main/src/SSR.Net.DotNet6/Program.cs
158+
After this is done, we call the extension method during the initialization of our program in Program.cs: https://github.com/knowit/SSR.Net/blob/main/src/SSR.Net.DotNet6/Program.cs
92159

93160
```
94161
builder.Services.AddReact18Renderer(builder.Environment);
@@ -97,24 +164,119 @@ builder.Services.AddReact18Renderer(builder.Environment);
97164

98165
### Set up a controller and a view
99166

167+
To do the actual Server Side Rendering, we need to serialize props for the React component we want to Server Side Render and send the props as JSON to the React18Renderer, together with the component name. In this simplified example, we do this directly in the controller (https://github.com/knowit/SSR.Net/blob/main/src/SSR.Net.DotNet6/Controllers/HomeController.cs).
168+
169+
First, we inject the React18Renderer in the controller (some lines are removed for brevity and clarity):
170+
171+
```
172+
public class HomeController : Controller {
173+
private readonly React18Renderer _react18Renderer;
174+
175+
public HomeController(React18Renderer react18Renderer)
176+
{
177+
_react18Renderer = react18Renderer;
178+
}
179+
...
180+
}
181+
```
182+
183+
Then we add an action to the controller, where we serialize our model and let the React18Renderer create both the HTML and the initialization script. These are returned as a RenderedComponent from the React18Renderer, and passed on to the view:
184+
185+
```
186+
public ActionResult React18() {
187+
var propsJson = JsonConvert.SerializeObject(
188+
new {
189+
header = "React 18 with SSR",
190+
links = new[]{
191+
new {
192+
text = "Google.com",
193+
href = "https://www.google.com"
194+
},
195+
new {
196+
text = "Hacker news",
197+
href = "https://news.ycombinator.org"
198+
}
199+
}
200+
});
201+
var renderedComponent = _react18Renderer.RenderComponent("Components.FrontPage", propsJson);
202+
return View(renderedComponent);
203+
}
204+
```
205+
206+
The view is kept very simple (https://github.com/knowit/SSR.Net/blob/main/src/SSR.Net.DotNet6/Views/Home/React18.cshtml):
207+
208+
```
209+
@using SSR.Net.Models;
210+
@model RenderedComponent
211+
@{
212+
Layout = null;
213+
}
214+
215+
<!DOCTYPE html>
216+
<html>
217+
<head>
218+
<meta charset="utf-8" />
219+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
220+
<title>React 18 with SSR</title>
221+
<script src="~/react18example.js"></script>
222+
</head>
223+
<body>
224+
@Html.Raw(Model.Html)
225+
<script>@Html.Raw(Model.InitScript)</script>
226+
</body>
227+
</html>
228+
```
229+
230+
Here we use RenderedComponent as our model. We set Layout to null, because we only use the markup in this file. We include the react18example.js script that we created in [Building a JavaScript bundle fit for SSR](#Building-a-JavaScript-bundle-fit-for-SSR) in a <script> tag in the <head> tag.
231+
232+
Inside the <body> tag, there are just two lines. The first one takes the HTML from our RenderedComponent and renders it as a raw string in the view. The second one takes the initialization script and renders it as a raw string inside a <script> tag.
233+
234+
## Running the solution
235+
236+
When running the solution and visiting the React 18 view, we see that it's working and that we can interact with it (clicking Expand links will expand the links):
237+
238+
![React 18 in the browser](./React18InBrowser.png)
239+
240+
If we view the source, we see that we get markup from the server and not just an empty <div>. We also see the initialization script, which instructs React to latch on to the DOM in the <div> with the markup by calling ReactDOMClient.hydrateRoot:
241+
242+
![React 18 view source](./React18ViewSource.png)
243+
244+
If the rendering was done without SSR, then the div would be empty and the initialization script would call ReactDOMClient.createRoot:
245+
246+
![React 18 view source without SSR](./React18ViewSourceCSR.png)
247+
100248
## Performance and scaling
101-
In order to be ready to render components quickly, SSR.Net ensures that a configurable number of JavaScript engines are initialized with a given JavaScript bundle. There are several thresholds controlling this:
249+
In order to be ready to render components quickly, SSR.Net ensures that a configurable number of JavaScript engines are initialized with a given JavaScript bundle. This is done when instantiating a new JavaScriptEnginePool. There are several thresholds controlling this:
102250
* Minimum engines: When starting or reconfiguring SSR.Net, it will make sure there are at least this number of engines in the engine pool.
103251
* Maximum engines: The number of engines in the engine pool will never exceed this threshold.
104252
* Standby engines: The number of unoccupied (spare) engines in the pool.
105253
* Maximum engine usages: A given engine can be used this number of times before it gets disposed of.
106254

255+
There are methods to configure this when initializing the JavaScriptEnginePool:
256+
257+
```
258+
var pool = new JavaScriptEnginePool(new V8JsEngineFactory(), config =>
259+
config
260+
.AddScriptFile(Path.Combine(webHostEnvironment.WebRootPath, "React18TextEncoderPolyfill.js"))
261+
.AddScriptFile(Path.Combine(webHostEnvironment.WebRootPath, "react18example.js"))
262+
.WithMinEngineCount(5)
263+
.WithStandbyEngineCount(3)
264+
.WithMaxEngineCount(25)
265+
.WithMaxUsagesCount(100)
266+
);
267+
services.AddSingleton(new React18Renderer(pool));
268+
```
269+
107270
Example:
108271

109272
Let's say we have configured a minimum of 5 engines, a maximum of 25 engines and 3 engines on standby. Before any requests come in, there will be 5 vacant engines.
110273
Then 3 requests come in at the same time, occupying 3 engines. SSR.Net will see that there are only 2 engines on standby, and will initialize another engine to comply with the "3 engines on standby" requirement.
111-
Traffic increases, and at some point, 23 engines are occupied concurrently. SSR.Net will ensure that there are 25 engines initialized, but will not exceed this threshold, to comply with the "maximum of 25 engines" requirement.
112-
Then, there are only 2-3 concurrent requests for a long time. The engines will eventually be exhausted and disposed of, and the number of engines sinks.
113-
At some point, there are only 5 engines left. The next time an engine gets exhausted, SSR.Net will dispose of it and see that there are only 4 engines left. Then SSR.Net will initialize a new engine to comply with the "minimum of 5 engines" requirement.
114274

275+
Traffic increases drastically, and at some point 23 engines are occupied concurrently. SSR.Net will ensure that there are 25 engines initialized, but will not exceed this threshold, to comply with the "maximum of 25 engines" requirement.
115276

277+
Then, there are only 2-3 concurrent requests for a long time. The engines will eventually be exhausted and disposed of, and the number of engines declines. At some point, there are only 5 engines left. The next time an engine gets exhausted, SSR.Net will dispose of it and see that there are only 4 engines left. Then SSR.Net will initialize a new engine to comply with the "minimum of 5 engines" requirement.
116278

117-
## Limitations when doing SSR:
279+
## Limitations and workarounds when doing SSR
118280
* The window object does not exist. This means that your code needs to check if window is defined before using it:
119281
```
120282
if (typeof window !== 'undefined')
@@ -123,4 +285,14 @@ if (typeof window !== 'undefined')
123285
}
124286
```
125287
* Global variables must not be used (except the ones described above for exposing objects to SSR.Net). Each JavaScript Engine is used multiple times, so global variables will cause state to be shared between requests, meaning data can leak from one user to another.
126-
* Some 3rd party packages may fail, if they use the window object or global variables.
288+
* Some 3rd party packages may fail, if they use the window object or global variables.
289+
* SSR in React won't run useEffect hooks. So using the window object in a useEffect is safe. Also, if you have code that requires the window object and that doesn't contain markup that you need served from the server side, then you can defer including it to after the first contentful paint:
290+
291+
```
292+
const [initialized, setInitialized] = useState(false);
293+
294+
useEffect(()=>setInitialized(true));
295+
296+
return (<div>{initialized && <ComponentThatDoesNotSupportSSR {...someProps} />}</div>);
297+
```
298+

‎Docs/React18InBrowser.png‎

13.9 KB
Loading

‎Docs/React18ViewSource.png‎

60.6 KB
Loading

‎Docs/React18ViewSourceCSR.png‎

57.2 KB
Loading

‎src/SSR.Net.DotNet6/Controllers/HomeController.cs‎

Lines changed: 35 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,52 +2,46 @@
22
using Newtonsoft.Json;
33
using SSR.Net.Services;
44

5-
namespace SSR.Net.DotNet6.Controllers
6-
{
7-
public class HomeController : Controller
8-
{
5+
namespace SSR.Net.DotNet6.Controllers {
6+
public class HomeController : Controller {
97
private readonly React17Renderer _react17Renderer;
108
private readonly React18Renderer _react18Renderer;
119
private readonly Vue3Renderer _vue3Renderer;
1210

1311
public HomeController(React17Renderer react17Renderer,
1412
React18Renderer react18Renderer,
15-
Vue3Renderer vue3Renderer)
16-
{
13+
Vue3Renderer vue3Renderer) {
1714
_react17Renderer = react17Renderer;
1815
_react18Renderer = react18Renderer;
1916
_vue3Renderer = vue3Renderer;
2017
}
2118

2219
public ActionResult Index() => View();
2320

24-
public ActionResult React17() =>
25-
View(_react17Renderer.RenderComponent(
26-
"Components.FrontPage",
27-
JsonConvert.SerializeObject(
28-
new
29-
{
21+
public ActionResult React17() {
22+
var propsJson = JsonConvert.SerializeObject(
23+
new {
3024
header = "React 17 with SSR",
3125
links = new[]{
32-
new {
33-
text = "Google.com",
34-
href ="https://www.google.com"
35-
},
36-
new {
37-
text = "Hacker news",
38-
href = "https://news.ycombinator.org"
26+
new {
27+
text = "Google.com",
28+
href ="https://www.google.com"
29+
},
30+
new {
31+
text = "Hacker news",
32+
href = "https://news.ycombinator.org"
33+
}
3934
}
40-
}
41-
})));
35+
});
36+
var renderedComponent = _react17Renderer.RenderComponent("Components.FrontPage", propsJson);
37+
return base.View(renderedComponent);
38+
}
4239

43-
public ActionResult React18() =>
44-
View(_react18Renderer.RenderComponent(
45-
"Components.FrontPage",
46-
JsonConvert.SerializeObject(
47-
new
48-
{
49-
header = "React 18 with SSR",
50-
links = new[]{
40+
public ActionResult React18() {
41+
var propsJson = JsonConvert.SerializeObject(
42+
new {
43+
header = "React 18 with SSR",
44+
links = new[]{
5145
new {
5246
text = "Google.com",
5347
href = "https://www.google.com"
@@ -57,16 +51,18 @@ public ActionResult React18() =>
5751
href = "https://news.ycombinator.org"
5852
}
5953
}
60-
})));
54+
});
55+
var renderedComponent = _react18Renderer.RenderComponent("Components.FrontPage", propsJson);
56+
return View(renderedComponent);
57+
}
6158

62-
public ActionResult Vue3() =>
63-
View(_vue3Renderer.RenderComponent(
64-
"Components.Example",
65-
JsonConvert.SerializeObject(
66-
new
67-
{
68-
title = "Vue 3 with SSR"
69-
}
70-
)));
59+
public ActionResult Vue3() {
60+
var propsJson = JsonConvert.SerializeObject(
61+
new {
62+
title = "Vue 3 with SSR"
63+
});
64+
var renderedComponent = _vue3Renderer.RenderComponent("Components.Example", propsJson);
65+
return View(renderedComponent);
66+
}
7167
}
7268
}

0 commit comments

Comments
 (0)