Skip to content

Commit f98ac9a

Browse files
taiontaion
committed
Add docs [ci skip]
1 parent 8c981b6 commit f98ac9a

File tree

2 files changed

+179
-15
lines changed

2 files changed

+179
-15
lines changed

‎README.md

Lines changed: 167 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ export default AppPage;
120120
- [Basic usage with JSX route configuration](/examples/basic-jsx)
121121
- [Global pending state](/examples/global-pending)
122122
- [Transition hook usage](/examples/transition-hook)
123+
- [Server-side rendering](/examples/universal)
123124

124125
## Extensions
125126

@@ -131,8 +132,8 @@ export default AppPage;
131132
### Installation
132133

133134
```
134-
npm i -S react
135-
npm i -S found
135+
$ npm i -S react
136+
$ npm i -S found
136137
```
137138

138139
### Basic usage
@@ -442,7 +443,7 @@ ReactDOM.render(
442443
);
443444
```
444445

445-
The `createBrowserRouter` function takes an options object. The only mandatory property on this object is `routeConfig`, which should be a route configuration as above.
446+
`createBrowserRouter` takes an options object. The only mandatory property on this object is `routeConfig`, which should be a route configuration as above.
446447

447448
The options object also accepts a number of optional properties:
448449

@@ -466,7 +467,7 @@ The created `<BrowserRouter>` accepts an optional `matchContext` prop as describ
466467

467468
#### `createFarceRouter`
468469

469-
`createFarceRouter` exposes additional configuration for customizing navigation management and route element resolution. To enable minimizing bundle size, it omits the defaults from `createBrowserRouter`.
470+
`createFarceRouter` exposes additional configuration for customizing navigation management and route element resolution. To enable minimizing bundle size, it omits some defaults from `createBrowserRouter`.
470471

471472
```js
472473
import { BrowserProtocol, queryMiddleware } from 'farce';
@@ -476,8 +477,6 @@ import { createFarceRouter, createRender, resolveElements } from 'found';
476477

477478
const FarceRouter = createFarceRouter({
478479
historyProtocol: new BrowserProtocol(),
479-
historyMiddlewares: [queryMiddleware],
480-
481480
routeConfig,
482481

483482
render: createRender({
@@ -497,7 +496,7 @@ ReactDOM.render(
497496

498497
The options object for `createFarceRouter` should have a `historyProtocol` property that has a history protocol object. For example, to use the HTML History API as with `createBrowserRouter`, you would provide `new BrowserProtocol()`.
499498

500-
The `createFarceRouter` options object does not have defaults for the `historyMiddlewares` and `render` properties. It ignores the `renderPending`, `renderReady`, and `renderError` properties.
499+
The `createFarceRouter` options object does not have a default for the `render` property. It ignores the `renderPending`, `renderReady`, and `renderError` properties.
501500

502501
The created `<FarceRouter>` manages setting up and providing a Redux store with the appropriate configuration internally. It also requires a `resolveElements` prop with the route element resolution function. For routes configured as above, this should be the `resolveElements` function in this library.
503502

@@ -525,8 +524,6 @@ import { combineReducers, compose, createStore } from 'redux';
525524

526525
/* ... */
527526

528-
const matcher = new Matcher(routeConfig);
529-
530527
const store = createStore(
531528
combineReducers({
532529
found: foundReducer,
@@ -536,15 +533,15 @@ const store = createStore(
536533
protocol: new BrowserProtocol(),
537534
middlewares: [queryMiddleware],
538535
}),
539-
createMatchEnhancer(matcher),
536+
createMatchEnhancer(
537+
new Matcher(routeConfig),
538+
),
540539
),
541540
);
542541

543542
store.dispatch(FarceActions.init());
544543

545544
const ConnectedRouter = createConnectedRouter({
546-
matcher,
547-
548545
render: createRender({
549546
renderError: ({ error }) => (
550547
<div>
@@ -562,9 +559,9 @@ ReactDOM.render(
562559
);
563560
```
564561

565-
When creating a store for use with the created `<ConnectedRouter>`, you should install the `foundReducer` reducer under the `found` key. You should also use a store enhancer created with `createHistoryEnhancer` from Farce, and a store enhancer created with `createMatchEnhancer`, which must go after the history store enhancer. `createMatchEnhancer` takes a matcher object which handles the actual route matching. Dispatch `FarceActions.init()` after setting up your store to initialize the event listeners and the initial location for the history store enhancer.
562+
When creating a store for use with the created `<ConnectedRouter>`, you should install the `foundReducer` reducer under the `found` key. You should also use a store enhancer created with `createHistoryEnhancer` from Farce and a store enhancer created with `createMatchEnhancer`, which must go after the history store enhancer. Dispatch `FarceActions.init()` after setting up your store to initialize the event listeners and the initial location for the history store enhancer.
566563

567-
`createConnectedRouter` ignores the `historyProtocol`, `historyMiddlewares`, and `historyOptions` properties on its options object. It requires the `matcher` property with the matcher object used in creating the match enhancer.
564+
`createConnectedRouter` ignores the `historyProtocol`, `historyMiddlewares`, and `historyOptions` properties on its options object.
568565

569566
`createConnectedRouter` also accepts an optional `getFound` property. If you installed `foundReducer` on a key other than `found`, specify the `getFound` function to retrieve the reducer state.
570567

@@ -678,7 +675,7 @@ If you want to run your transition hooks when the user attempts to leave the pag
678675

679676
The [transition hook usage example](/examples/transition-hook) demonstrates the use of transition hooks in more detail, including the use of the `useBeforeUnload` option.
680677

681-
#### Redux integration
678+
### Redux integration
682679

683680
Found uses Redux to manage all serializable state. Farce uses Redux actions for navigation. As such, you can also access those serializable parts of the routing state from the store state, and you can navigate by dispatching actions.
684681

@@ -699,6 +696,161 @@ const MyConnectedComponent = connect(
699696
)(MyComponent);
700697
```
701698

699+
### Server-side rendering
700+
701+
Found supports server-side rendering for universal applications. Functionality specific to server-side rendering is available in `found/lib/server`.
702+
703+
To render your application on the server, use `getFarceResult`.
704+
705+
```js
706+
import { getFarceResult } from 'found/lib/server';
707+
708+
/* ... */
709+
710+
app.use(async (req, res) => {
711+
const { redirect, status, element } = await getFarceResult({
712+
url: req.url,
713+
routeConfig,
714+
render,
715+
});
716+
717+
if (redirect) {
718+
res.redirect(302, redirect.url);
719+
return;
720+
}
721+
722+
res.status(status).send(`
723+
<!DOCTYPE html>
724+
<html>
725+
726+
<head>
727+
<meta charset="UTF-8">
728+
<title>Found Universal Example</title>
729+
</head>
730+
731+
<body>
732+
<div id="root">${ReactDOMServer.renderToString(element)}</div>
733+
734+
<script src="/static/bundle.js"></script>
735+
</body>
736+
737+
</html>
738+
`);
739+
});
740+
```
741+
742+
`getFarceResult` takes an options object. This object must include the `url` property that is the full path of the current request, along with the `routeConfig` and `render` properties needed to create a Farce router component class normally.
743+
744+
The options object for `getFarceResult` also takes the `historyMiddlewares` and `historyOptions` properties, as above for creating Farce router component classes. This options object also takes optional `matchContext` and `resolveElements` properties, as described above as props for router components. `resolveElements` defaults to the standard `resolveElements` function in this library.
745+
746+
`getFarceResult` returns a promise for an object with the following properties:
747+
748+
- `redirect`: if present, indicates that element resolution triggered a redirect; `redirect.url` contains the full path for the redirect location
749+
- `status`: if there was no redirect, the HTTP status code for the response; this will be `error.status` from any encountered `HttpError`, or 200 otherwise
750+
- `element`: if there was no redirect, the React element corresponding to the router component on the client
751+
752+
This promise resolves when all asynchronous dependencies are available. If your routes require asynchronous data, e.g. from `getData` methods, you may want to dehydrate those data on the server, then rehydrate them on the client, to avoid the client having to request those data again.
753+
754+
#### Server-side rendering with custom Redux store
755+
756+
If you are using server-side rendering, you will need to delay the initial render on the client. In this case, use `createInitialBrowserRouter` or `createInitialFarceRouter` instead of `createBrowserRouter` or `createFarceRouter` respectively.
757+
758+
```js
759+
import { createInitialBrowserRouter } from 'found';
760+
761+
/* ... */
762+
763+
(async () => {
764+
const BrowserRouter = await createInitialBrowserRouter({
765+
routeConfig,
766+
render,
767+
});
768+
769+
ReactDOM.render(
770+
<BrowserRouter />,
771+
document.getElementById('root'),
772+
);
773+
})();
774+
```
775+
776+
These behave similarly to their counterparts above, except that the options object for `createInitialBrowserRouter` requires a `render` method, and ignores the `renderPending`, `renderReady`, and `renderError` properties. Additionally, these functions take the initial `matchContext` and `resolveElements` if relevant as properties on the options object, rather than as props.
777+
778+
Found exposes lower-level functionality for doing server-side rendering for use with your own Redux store, as with `createConnectedRouter` above. On both the server, use `getStoreRenderArgs` to get a promise for the arguments to your `render` function, then wrap the rendered elements with a `<RouterProvider>`.
779+
780+
```js
781+
import { getStoreRenderArgs } from 'found';
782+
import { RedirectException, RouterProvider } from 'found/lib/server';
783+
784+
/* ... */
785+
786+
app.use(async (req, res) => {
787+
/* ... */
788+
789+
let renderArgs;
790+
791+
try {
792+
renderArgs = await getStoreRenderArgs({
793+
store,
794+
matchContext,
795+
resolveElements,
796+
});
797+
} catch (e) {
798+
if (e instanceof RedirectException) {
799+
res.redirect(302, store.farce.createHref(e.location));
800+
return;
801+
}
802+
803+
throw e;
804+
}
805+
806+
res
807+
.status(renderArgs.error ? renderArgs.error.status : 200)
808+
.send(renderPageToString(
809+
(
810+
<Provider store={store}>
811+
<RouterProvider router={renderArgs.router}>
812+
{render(renderArgs)}
813+
</RouterProvider>
814+
</Provider>
815+
),
816+
store.getState(),
817+
));
818+
});
819+
```
820+
821+
You must dispatch `FarceActions.init()` before calling `getStoreRenderArgs`. `getStoreRenderArgs` takes an options object. This object must have the `store` property for your store and the `resolveElements` property as described above. It supports an optional `matchContext` property as described above as well. `getStoreRenderArgs` returns a promise that resolves to a `renderArgs` object that can be passed into a `render` function as above.
822+
823+
`<RouterProvider>` requires a `router` prop that is the router context object as described above. This is available on `renderArgs.router`, from the value resolved by `getStoreRenderArgs`.
824+
825+
On the client, pass the value resolved by by `getStoreRenderArgs` to your `<ConnectedRouter>` as the `initialRenderArgs` prop.
826+
827+
```js
828+
import { getStoreRenderArgs } from 'found';
829+
830+
/* ... */
831+
832+
(async () => {
833+
/* ... */
834+
835+
const initialRenderArgs = await getStoreRenderArgs({
836+
store,
837+
matchContext,
838+
resolveElements,
839+
});
840+
841+
ReactDOM.render(
842+
<Provider store={store}>
843+
<ConnectedRouter
844+
matchContext={matchContext}
845+
resolveElements={resolveElements}
846+
initialRenderArgs={initialRenderArgs}
847+
/>
848+
</Provider>,
849+
document.getElementById('root'),
850+
);
851+
})();
852+
```
853+
702854
### Minimizing bundle size
703855

704856
The top-level `found` package exports everything available in this library. It is unlikely that any single application will use all the features available. As such, for real applications, you should import the modules that you need from `found/lib` directly, to pull in only the code that you use.

‎examples/universal/README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Found Universal Example
2+
3+
This example uses the same route configuration as the [basic JSX example](../basic-jsx), but uses server-side rendering for the initial page load.
4+
5+
## Usage
6+
7+
```
8+
$ npm i
9+
$ npm start
10+
```
11+
12+
Then open [http://localhost:3000/](http://localhost:3000/) in your browser.

0 commit comments

Comments
 (0)