Gathering detailed insights and metrics for react-isomorphic-render
Gathering detailed insights and metrics for react-isomorphic-render
A complete solution for building a React/Redux application: routing, page preloading, (optional) server-side rendering, asynchronous HTTP requests, document metadata, etc.
11.0.64
175
MIT
JavaScript
1.14 MB
Installations
npm install react-isomorphic-renderDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Node Version
9.11.1
NPM Version
6.4.0
Releases
Unable to fetch releases
Languages
1
JavaScript
JavaScript (100%)
Developer
catamphetamine
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
175 Stars
1,082 Commits
28 Forks
15 Watchers
5 Branches
5 Contributors
Updated on Feb 11, 2025
Maintainers
1
Package Meta Information
Latest Version
11.0.64
Package Id
react-isomorphic-render@11.0.64
Unpacked Size
1.14 MB
Size
302.94 kB
File Count
218
NPM Version
6.4.0
Node Version
9.11.1
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
14
Peer Dependencies
6
react-pages
A complete solution for building a React/Redux application
- Routing
- Loading pages
- (optional) Code splitting
- (optional) Server-side rendering
- Fetching data
- Easier Redux
- Document metadata (
<title/>,<meta/>, social network sharing) - Webpack "hot reload"
- HTTP Cookies
- etc
Introduction
Getting started
First, install Redux.
1$ yarn add redux react-redux
or:
1$ npm install redux react-redux --save
Then, install react-pages:
1$ yarn add react-pages
or:
1$ npm install react-pages --save
Then, create a react-pages configuration file.
The configuration file:
./src/react-pages.js
1import routes from './routes.js' 2 3export default { 4 routes 5}
The routes:
./src/routes.js
1import App from '../pages/App.js' 2import Item from '../pages/Item.js' 3import Items from '../pages/Items.js' 4 5export default [{ 6 Component: App, 7 path: '/', 8 children: [ 9 { Component: App }, 10 { Component: Items, path: 'items' }, 11 { Component: Item, path: 'items/:id' } 12 ] 13}]
The page components:
./src/pages/App.js
1import React from 'react' 2import { Link } from 'react-pages' 3 4export default ({ children }) => ( 5 <section> 6 <header> 7 Web Application 8 </header> 9 {children} 10 <footer> 11 Copyright 12 </footer> 13 </section> 14)
./src/pages/Items.js
1import React from 'react' 2 3export default () => <div> This is the list of items </div>
./src/pages/Item.js
1import React from 'react' 2 3export default ({ params }) => <div> Item #{params.id} </div>
Finally, call render() in the main client-side javascript file of the app.
The main client-side javascript file of the app:
./src/index.js
1import { render } from 'react-pages/client' 2import settings from './react-pages.js' 3 4// Render the page in a web browser. 5render(settings)
The index.html file of the app usually looks like this:
1<html> 2 <head> 3 <title>Example</title> 4 <!-- Fix encoding. --> 5 <meta charset="utf-8"> 6 <!-- Fix document width for mobile devices. --> 7 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 8 </head> 9 <body> 10 <script src="/bundle.js"></script> 11 </body> 12</html>
Where bundle.js is the ./src/index.js file built with Webpack (or you could use any other javascript bundler).
And make sure that the output files are accessible from a web browser.
The index.html and bundle.js files must be served over HTTP(S).
If you're using Webpack then add HtmlWebpackPlugin to generate index.html, and run webpack-dev-server with historyApiFallback to serve the generated index.html and bundle.js files over HTTP on localhost:8080.
See HtmlWebpackPlugin configuration example
webpack.config.js
1const HtmlWebpackPlugin = require('html-webpack-plugin') 2 3const buildOutputPath = '...' 4const devServerPort = 8080 // Any port number. 5 6module.exports = { 7 output: { 8 path: buildOutputPath, 9 publicPath: `http://localhost:${devServerPort}`, 10 ... 11 }, 12 ..., 13 plugins: [ 14 new HtmlWebpackPlugin({ 15 template: 'src/index.html' // Path to `index.html` file. 16 }), 17 ... 18 ], 19 devServer: { 20 port: devServerPort, 21 contentBase: buildOutputPath, 22 historyApiFallback : true 23 } 24}
src/index.html
1<html> 2 <head> 3 <title>Example</title> 4 <!-- Fix encoding. --> 5 <meta charset="utf-8"> 6 <!-- Fix document width for mobile devices. --> 7 <meta name="viewport" content="width=device-width, initial-scale=1.0"> 8 </head> 9 <body> 10 <!-- HtmlWebpackPlugin will insert a <script> tag here. --> 11 </body> 12</html>
webpack-dev-server --hot --config webpack.config.js
Or see the Webpack example project.
If you're using Parcel instead of Webpack then see the basic example project for the setup required in order to generate and serve index.html and bundle.js files over HTTP on localhost:1234.
Done
So now the website should be fully working.
The website (index.html, bundle.js, CSS stylesheets and images, etc) can now be deployed as-is in a cloud (e.g. on Amazon S3) and served statically for a very low price. The API can be hosted "serverlessly" in a cloud (e.g. Amazon Lambda) which is also considered cheap. No running Node.js server is required.
Yes, it's not a Server-Side Rendered approach because a user is given a blank page first, then bundle.js script is loaded by the web browser, then bundle.js script is executed fetching some data from the API via an HTTP request, and only when that HTTP request comes back — only then the page is rendered (in the browser). Google won't index such websites, but if searchability is not a requirement (at all or yet) then that would be the way to go (e.g. startup "MVP"s or "internal applications"). Server-Side Rendering can be easily added to such setup should the need arise.
Adding Server Side Rendering
Adding server-side rendering to the setup is quite simple, although I'd consider it an "advanced" topic.
While client-side rendering could be done entirely in a web browser, server-side rendering would require running a Node.js process somewhere in a cloud which slightly increases the complexity of the whole setup.
So in case of server-side rendering, index.html file is being generated on-the-fly by a page rendering server (a Node.js process) for each incoming HTTP request, so the index.html file that was used previously for client-side rendering may be deleted now as it's of no longer use.
A Node.js script for running a "rendering server" process would look like this:
./rendering-server.js
1import webpageServer from 'react-pages/server' 2import settings from './react-pages' 3 4// Create webpage rendering server 5const server = webpageServer(settings, { 6 // Pass `secure: true` flag to listen on `https://` rather than `http://`. 7 // secure: true, 8 9 // These are the URLs of the "static" javascript and CSS files 10 // which are injected into the resulting HTML webpage in the form of 11 // <script src="..."/> and <link rel="style" href="..."/> tags. 12 // 13 // The javascript file should be the javascript "bundle" of the website 14 // and the CSS file should be the CSS "bundle" of the website. 15 // 16 // P.S.: To inject other types of javascript or CSS files 17 // (for example, files of 3rd-party libraries), 18 // use a separate configuration parameter called `html`: 19 // https://gitlab.com/catamphetamine/react-pages/blob/master/README-ADVANCED.md#all-webpage-rendering-server-options) 20 // 21 assets() { 22 return { 23 // This should be the URL for the application's javascript bundle. 24 // In this case, the configuration assumes that the website is being run 25 // on `localhost` domain with "static file hosting" enabled for its files. 26 javascript: 'http://localhost:8080/bundle.js', 27 28 // (optional) 29 // This should be the URL for the application's CSS bundle. 30 style: 'http://localhost:8080/bundle.css' 31 } 32 } 33}) 34 35// Start webpage rendering server on port 3000. 36// Syntax: `server.listen(port, [host], [callback])`. 37server.listen(3000, function(error) { 38 if (error) { 39 throw error 40 } 41 console.log(`Webpage rendering server is listening at http://localhost:3000`) 42})
Run the rendering server:
$ npm install npx --global
$ npm install babel-cli
$ npx babel-node rendering-server.js
Now disable javascript in Chrome DevTools, go to localhost:3000 and the server should respond with a fully server-side-rendered page.
Conclusion
This concludes the introductory part of the README and the rest is the description of the various tools and techniques which come prepackaged with this library.
A working example illustrating Server-Side Rendering and all other things can be found here: webpack-react-redux-isomorphic-render-example.
Another minimalistic example using Parcel instead of Webpack can be found here: react-pages-basic-example.
Documentation
Root component
react-pages configuration file supports a rootComponent parameter. It should be the root component of the application. It receives properties: children and store (Redux store).
The default (and minimal) rootComponent is simply a Redux Provider wrapped around the children. The Redux Provider enables Redux, because this library uses Redux internally.
1import { Provider as ReduxProvider } from 'react-redux' 2 3export default function DefaultRootComponent({ store, children }) { 4 return ( 5 <ReduxProvider store={store}> 6 {children} 7 </ReduxProvider> 8 ) 9}
Redux
If you plan on using Redux in your application, provide a reducers object in the react-pages configuration file.
./src/react-pages.js
1import routes from './routes.js' 2 3// The `reducers` parameter should be an object containing 4// Redux reducers that will be combined into a single Redux reducer 5// using the standard `combineReducers()` function of Redux. 6import * as reducers from './redux/index.js' 7 8export default { 9 routes, 10 reducers 11}
Where the reducers object should be:
./src/redux/index.js
1// For those who're unfamiliar with Redux concepts, 2// a "reducer" is a function `(state, action) => state`. 3// 4// The main (or "root") "reducer" usually consists of "sub-reducers", 5// in which case it's an object rather than a function, 6// and each property of such object is a "sub-reducer" function. 7// 8// There's no official name for "sub-reducer". 9// For example, Redux Toolkit [calls](https://redux.js.org/usage/structuring-reducers/splitting-reducer-logic) them "slices". 10// 11export { default as subReducer1 } from './subReducer1.js' 12export { default as subReducer2 } from './subReducer2.js' 13...
Middleware
To add custom Redux "middleware", specify a reduxMiddleware parameter in the react-pages configuration file.
1export default { 2 ..., 3 4 // `reduxMiddleware` should be an array of custom Redux middlewares. 5 reduxMiddleware: [ 6 middleware1, 7 middleware2 8 ] 9}
Loading pages
To "load" a page before it's rendered (both on server side and on client side), define a static load property function on the page component.
The load function receives a "utility" object as its only argument:
1function Page({ data }) { 2 return ( 3 <div> 4 {data} 5 </div> 6 ) 7} 8 9Page.load = async (utility) => { 10 const { 11 // Can `dispatch()` Redux actions. 12 dispatch, 13 14 // Can be used to get a slice of Redux state. 15 useSelector, 16 17 // (optional) 18 // 19 // "Load Context" could hold any custom developer-defined variables 20 // that could then be accessed inside `.load()` functions. 21 // 22 // To define a "load context": 23 // 24 // * Pass `getLoadContext()` function as an option to the client-side `render()` function. 25 // The options are the second argument of that function. 26 // The result of the function will be passed to each `load()` function as `context` parameter. 27 // The result of the function will be reused within the scope of a given web browser tab, 28 // i.e. `getLoadContext()` function will only be called once for a given web browser tab. 29 // 30 // * (if also using server-side rendering) 31 // Pass `getLoadContext()` function as an option to the server-side `webpageServer()` function. 32 // The options are the second argument of that function. 33 // The result of the function will be passed to each `load()` function as `context` parameter. 34 // The result of the function will be reused within the scope of a given HTTP request, 35 // i.e. `getLoadContext()` function will only be called once for a given HTTP request. 36 // 37 // `getLoadContext()` function recevies an argument object: `{ dispatch }`. 38 // `getLoadContext()` function should return a "load context" object. 39 // 40 // Miscellaneous: `context` parameter will also be passed to `onPageRendered()`/`onBeforeNavigate()` functions. 41 // 42 context, 43 44 // (optional) 45 // A `context` parameter could be passed to the functions 46 // returned from `useNavigation()` hooks. When passed, that parameter 47 // will be available inside the `.load()` function of the page as `navigationContext` parameter. 48 navigationContext, 49 50 // Current page location (object). 51 location, 52 53 // Route URL parameters. 54 // For example, for route "/users/:id" and URL "/users/barackobama", 55 // `params` will be `{ id: "barackobama" }`. 56 params, 57 58 // Navigation history. 59 // Each entry is an object having properties: 60 // * `route: string` — Example: "/user/:userId/post/:postId". 61 // * `action: string` — One of: "start", "push", "redirect", "back", "forward". 62 history, 63 64 // Is this server-side rendering? 65 server, 66 67 // (utility) 68 // Returns a cookie value by name. 69 getCookie 70 } = utility 71 72 // Send HTTP request and wait for response. 73 // For example, it could just be using the standard `fetch()` function. 74 const data = await fetch(`https://data-source.com/data/${params.id}`) 75 76 // Optionally return an object containing page component `props`. 77 // If returned, these props will be available in the page component, 78 // same way it works in Next.js in its `getServerSideProps()` function. 79 return { 80 // `data` prop will be available in the page component. 81 props: { 82 data 83 } 84 } 85}
The load property function could additionally be defined on the application's root React component. In that case, the application would first execute the load function of the application's root React component, and then, after it finishes, it would proceed to executing the page component's load function. This behavior allows the root React component's load function to perform the "initialization" of the application: for example, it could authenticate the user.
Catching errors in load function
To catch all errors originating in load() functions, specify an onLoadError() parameter in react-pages.js settings file.
1{ 2 onLoadError: (error, { url, location, redirect, useSelector, server }) => { 3 redirect(`/error?url=${encodeURIComponent(url)}&error=${error.status}`) 4 } 5}
Redirecting from load function
To redirect from a load function, return an object with redirect property, similar to how it works in Next.js in its getServerSideProps() function.
1UserPage.load = async ({ params }) => { 2 const user = await fetch(`/api/users/${params.id}`) 3 if (user.wasDeleted) { 4 return { 5 redirect: { 6 url: '/not-found' 7 } 8 } 9 } 10 return { 11 props: { 12 user 13 } 14 } 15}
Permanent redirects in routes configuration
To permanently redirect from one URL to another URL, specify a permanentRedirectTo parameter on the "from" route.
1{ 2 path: '/old-path/:id', 3 permanentRedirectTo: '/new-path/:id' 4}
Advanced topic: client-side page load indication (during navigation).
While the application is performing a load as a result of navigating to another page, a developer might prefer to show some kind of a loading indicator. Such loading indicator could be implemented as a React component that listens to the boolean value returned from useLoading() hook.
1import { useLoading } from 'react-pages' 2import LoadingIndicator from './LoadingIndicator.js' 3 4export default function PageLoading() { 5 const isLoading = useLoading() 6 return ( 7 <LoadingIndicator show={isLoading}/> 8 ) 9}
1export default function App({ children }) { 2 return ( 3 <div> 4 <PageLoading/> 5 {children} 6 </div> 7 ) 8}
Advanced topic: client-side page load indication (initial).
Initial client-side (non-server-side) load is different from client-side load during navigation: during the initial client-side load, the <App/> element is not rendered yet. Therefore, while the application is performing an initial client-side load, a blank screen is shown.
There're two possible workarounds for that:
- Perform the initial load on server side (not on client side).
- Show some kind of a loading indicator instead of a blank screen during the initial load.
To show a loading indicator instead of a blank screen during the initial load, one could specify some additional react-pages configuration parameters:
-
InitialLoadComponent— A React component that shows an initial page loading indicator. Receives properties:initial: true— This is just a flag that is alwaystrue.show: boolean— Istruewhen the component should be shown. Isfalsewhen the component should no longer be shown.- When
falseis passed, the component could either hide itself immediately or show some kind of a hiding animation (for example, fade out). The duration of such hiding animation should be passed asinitialLoadHideAnimationDuration: numberparameter (see below) so that the library knows when can it unmount theInitialLoadComponent.
- When
hideAnimationDuration: number— This is just a copy ofinitialLoadHideAnimationDuration: numberparameter (see below) for convenience.
-
initialLoadShowDelay: number— When supplyingInitialLoadComponent, one should also specify the delay before showing theInitialLoadComponent. For example, such delay could be used to only showInitialLoadComponentfor initial loads that aren't fast enough. For "no delay", the value should be0. -
initialLoadHideAnimationDuration: number— When supplyingInitialLoadComponent, one should also specify the duration of the hide animation ofInitialLoadComponent, if it has a hide animation. If there's no hide animation, the value should be0.
On client side, in order for load to work, all links must be created using the <Link/> component imported from react-pages package. Upon a click on a <Link/>, first it waits for the next page to load, and then, when the next page is fully loaded, the navigation itself takes place.
load also works for Back/Forward navigation. To disable page load on Back navigation, pass instantBack property to a <Link/>.
For example, consider a search results page loading some data (could be search results themselves, could be anything else unrelated). A user navigates to this page, waits for load to finish and then sees a list of items. Without instantBack if the user clicks on an item he's taken to the item's page. Then the user clicks "Back" and is taken back to the search results page but has to wait for that load again. With instantBack though the "Back" transition occurs instantly without having to wait for that load again. Same goes then for the reverse "Forward" navigation from the search results page back to the item's page, but that's just a small complementary feature. The main benefit is the instantaneous "Back" navigation creating a much better UX where a user can freely explore a list of results without getting penalized for it with a waiting period on each click.
1import React from 'react' 2import { useSelector } from 'react-redux' 3import { Link } from 'react-pages' 4 5function SearchResultsPage() { 6 const results = useSelector(state => state.searchPage.results) 7 return ( 8 <ul> 9 { results.map((item) => ( 10 <li> 11 <Link to="/items/{item.id}" instantBack> 12 {item.name} 13 </Link> 14 </li> 15 ))) } 16 </ul> 17 ) 18} 19 20SearchResultsPage.load = async () => await fetchSomeData()
There's also instantBack: true option that could be passed to navigate(location, options) function which is returned from useNavigate() hook. The behavior of the option is the same.
instantBack is ignored when navigating to the same route: for example, if there's an <Article/> page component having a <Link instantBack/> to another <Article/> then instantBack is ignored — this feature was originally added for Redux because it made sense that way (in Redux there's only one slot for data of a route that gets rewritten every time the route is navigated to). For other data fetching frameworks like Relay I guess it would make sense to turn that off. Create an issue if that's the case.
One can also use the exported wasInstantNavigation() function (on client side) to find out if the current page was navigated to "instantly". This can be used, for example, to restore a "state" of a widget on instant "Back" navigation so that it renders immediately with the previously cached "results" or something.
There's also a canGoBackInstantly() function (on client side) that tells if the currently page can be navigated "Back" from instantly. This function can be used to render a custom "Go Back" button on a page only when an instant "Back" transition could be performed.
There's also a canGoForwardInstantly() function (analogous to canGoBackInstantly()).
Fetching Data
Fetching data in an application could be done using several approaches:
- Using
fetch()for making HTTP requests and then storing the result in React Component state usinguseState()hook setter. - Using
fetch()for making HTTP requests and then storing the result in Redux state bydispatch()-ing a "setter" action. - Using "asynchronous actions" framework provided by this library, which is described in detail in the next section of this document. This is the most sophisticated variant of the three and it comes with many useful features such as:
- Handling cookies
- CORS utilities
- Authentication utilities
- File upload progress support
- Persisting the result in Redux state
Asynchronous actions
Implementing synchronous actions in Redux is straightforward. But what about asynchronous actions like HTTP requests? Redux itself doesn't provide any built-in solution for that leaving it to 3rd party middlewares. Therefore this library provides one.
Pure Promises
This is the lowest-level approach to asynchronous actions. It is described here just for academic purposes and most likely won't be used directly in any app.
If a Redux "action creator" returns an object with a promise (function) and events (array) then dispatch()ing such an action results in the following steps:
- An event of
type = events[0]is dispatched promisefunction gets called and returns aPromise- If the
Promisesucceeds then an event oftype = events[1]is dispatched havingresultproperty set to thePromiseresult - If the
Promisefails then an event oftype = events[2]is dispatched havingerrorproperty set to thePromiseerror
1function asynchronousAction() { 2 return { 3 promise: () => Promise.resolve({ success: true }), 4 events: ['PROMISE_PENDING', 'PROMISE_SUCCESS', 'PROMISE_ERROR'] 5 } 6}
dispatch(asynchronousAction()) call returns the Promise itself:
1Page.load = async ({ dispatch }) => { 2 await dispatch(asynchronousAction()) 3}
HTTP utility
Because in almost all cases dispatching an "asynchronous action" in practice means "making an HTTP request", the promise function used in asynchronousAction()s always receives an { http } argument: promise: ({ http }) => ....
The http utility has the following methods:
headgetpostputpatchdelete
Each of these methods returns a Promise and takes three arguments:
- the
urlof the HTTP request dataobject (e.g. HTTP GETqueryor HTTP POSTbody)options(described further)
So, API endpoints can be queried using http and ES6 async/await syntax like so:
1function fetchFriends(personId, gender) { 2 return { 3 promise: ({ http }) => http.get(`/api/person/${personId}/friends`, { gender }), 4 events: ['GET_FRIENDS_PENDING', 'GET_FRIENDS_SUCCESS', 'GET_FRIENDS_FAILURE'] 5 } 6}
The possible options (the third argument of all http methods) are
headers— HTTP Headers JSON object.authentication— Set tofalseto disable sending the authentication token as part of the HTTP request. Set to a String to pass it as anAuthorization: Bearer ${token}token (no need to supply the token explicitly for everyhttpmethod call, it is supposed to be set globally, see below).progress(percent, event)— Use for tracking HTTP request progress (e.g. file upload).onResponseHeaders(headers)– Use for examining HTTP response headers (e.g. Amazon S3 file upload).
To set custom HTTP headers or to change HTTP request Content-Type
For that use the http.onRequest(request, { url, originalUrl, useSelector }) setting in ./react-pages.js where:
requestis asuperagentrequestthat can be modified. For example, to set an HTTP header:request.set(headerName, headerValue).originalUrlis the URL argument of thehttputility call.urlis theoriginalUrltransformed byhttp.transformUrl()settings function. If nohttp.transformUrl()is configured thenurlis the same as theoriginalUrl.
Redux module
Once one starts writing a lot of promise/http Redux actions it becomes obvious that there's a lot of copy-pasting and verbosity involved. To reduce those tremendous amounts of copy-pasta "redux module" tool may be used which:
- Gives access to
http. - Autogenerates Redux action status events (
${actionName}_PENDING,${actionName}_SUCCESS,${actionName}_ERROR). - Automatically adds Redux reducers for the action status events.
- Automatically populates the corresponding action status properties (
${actionName}Pending:true/false,${actionName}Error: Error) in Redux state.
For example, the fetchFriends() action from the previous section can be rewritten as:
Before:
1// ./actions/friends.js 2function fetchFriends(personId, gender) { 3 return { 4 promise: ({ http }) => http.get(`/api/person/${personId}/friends`, { gender }), 5 events: ['FETCH_FRIENDS_PENDING', 'FETCH_FRIENDS_SUCCESS', 'FETCH_FRIENDS_FAILURE'] 6 } 7} 8 9// ./reducers/friends.js 10export default function(state = {}, action = {}) { 11 switch (action.type) { 12 case 'FETCH_FRIENDS_PENDING': 13 return { 14 ...state, 15 fetchFriendsPending: true, 16 fetchFriendsError: null 17 } 18 case 'FETCH_FRIENDS_SUCCESS': 19 return { 20 ...state, 21 fetchFriendsPending: false, 22 friends: action.value 23 } 24 case 'FETCH_FRIENDS_ERROR': 25 return { 26 ...state, 27 fetchFriendsPending: false, 28 fetchFriendsError: action.error 29 } 30 default 31 return state 32 } 33}
After:
1import { ReduxModule } from 'react-pages' 2 3const redux = new ReduxModule('FRIENDS') 4 5export const fetchFriends = redux.action( 6 'FETCH_FRIENDS', 7 (personId, gender) => http => { 8 return http.get(`/api/person/${personId}/friends`, { gender }) 9 }, 10 // The fetched friends list will be placed 11 // into the `friends` Redux state property. 12 'friends' 13 // 14 // Or write it like this: 15 // { friends: result => result } 16 // 17 // Or write it as a Redux reducer: 18 // (state, result) => ({ ...state, friends: result }) 19) 20 21// This is the Redux reducer which now 22// handles the asynchronous action defined above. 23export default redux.reducer()
Much cleaner.
Also, when the namespace or the action name argument is omitted it is autogenerated, so this
1const redux = new ReduxModule('FRIENDS') 2... 3redux.action('FETCH_ITEM', id => http => http.get(`/items/${id}`), 'item')
could be written as
1const redux = new ReduxModule() 2... 3redux.action(id => http => http.get(`/items/${id}`), 'item')
and in this case redux will autogenerate the namespace and the action name, something like REACT_WEBSITE_12345 and REACT_WEBSITE_ACTION_12345.
A more complex example: a comments section for a blog post page.
redux/blogPost.js
1import { ReduxModule } from 'react-pages' 2 3const redux = new ReduxModule('BLOG_POST') 4 5// Post comment Redux "action creator" 6export const postComment = redux.action( 7 // 'POST_COMMENT', 8 (userId, blogPostId, commentText) => async http => { 9 // The original action call looks like: 10 // `dispatch(postComment(1, 12345, 'bump'))` 11 return await http.post(`/blog/posts/${blogPostId}/comment`, { 12 userId: userId, 13 text: commentText 14 }) 15 } 16) 17 18// Get comments Redux "action creator" 19export const getComments = redux.action( 20 // 'GET_COMMENTS', 21 (blogPostId) => async http => { 22 return await http.get(`/blog/posts/${blogPostId}/comments`) 23 }, 24 // The fetched comments will be placed 25 // into the `comments` Redux state property. 26 'comments' 27 // 28 // Or write it like this: 29 // { comments: result => result } 30 // 31 // Or write it as a Redux reducer: 32 // (state, result) => ({ ...state, comments: result }) 33) 34 35// A developer can listen to any Redux event via 36// `redux.on('EVENT_NAME', (state, action) => state)`. 37// 38// In this case, it listens to a "success" event of a `redux.action()`. 39// There's a section in this document describing this feature in more detail: 40// "Redux module can also listen for events from other redux modules via <code>redux.on()</code>" 41// 42redux.on('BLOG_POST', 'CUSTOM_EVENT', (state, action) => ({ 43 ...state, 44 reduxStateProperty: action.value 45})) 46 47// This is the Redux reducer which now 48// handles the asynchronous actions defined above 49// (and also the `handler.on()` events). 50// Export it as part of the "main" reducer. 51export default redux.reducer()
redux/index.js
1// The "main" reducer is composed of various reducers. 2export { default as blogPost } from './blogPost' 3...
The React Component would look like this
1import React from 'react' 2import { getBlogPost, getComments, postComment } from './redux/blogPost' 3 4export default function BlogPostPage() { 5 const userId = useSelector(state => state.user.id) 6 const blogPost = useSelector(state => state.blogPost.blogPost) 7 const comments = useSelector(state => state.blogPost.comments) 8 return ( 9 <div> 10 <article> 11 { blogPost.text } 12 </article> 13 <ul> 14 { comments.map(comment => <li>{comment}</li>) } 15 </ul> 16 <button onClick={() => postComment(userId, blogPost.id, 'text')}> 17 Post comment 18 </button> 19 </div> 20 ) 21} 22 23// Load blog post and comments before showing the page 24// (see "Page loading" section of this document) 25BlogPostPage.load = async ({ dispatch, params }) => { 26 // `params` are the URL parameters in route `path`. 27 // For example, "/blog/:blogPostId". 28 await dispatch(getBlogPost(params.blogPostId)) 29 await dispatch(getComments(params.blogPostId)) 30}
Redux module can also handle the conventional "synchronous" actions via export const action = redux.simpleAction()
A simple Redux action that simply updates Redux state.
1action = redux.simpleAction((state, actionArgument) => newState)
1import { ReduxModule } from 'react-pages' 2 3const redux = new ReduxModule('NOTIFICATIONS') 4 5// Displays a notification. 6// 7// The Redux "action" creator is gonna be: 8// 9// function(text) { 10// return { 11// type : 'NOTIFICATIONS:NOTIFY', 12// message : formatMessage(text) 13// } 14// } 15// 16// And the corresponding reducer is gonna be: 17// 18// case 'NOTIFICATIONS:NOTIFY': 19// return { 20// ...state, 21// message: action.message 22// } 23// 24// Call it as `dispatch(notify(text))`. 25// 26export const notify = redux.simpleAction( 27 // (optional) Redux event name. 28 'NOTIFY', 29 // The Redux reducer: 30 (state, message) => ({ ...state, message }), 31 // The Redux reducer above could be also defined as: 32 // 'message' 33) 34 35// This is the Redux reducer which now 36// handles the actions defined above. 37export default redux.reducer()
1dispatch(notify('Test'))
Redux module can also listen for events from other redux modules via redux.on()
1// A developer can listen to any Redux event via 2// `redux.on('EVENT_NAME', (state, action) => state)`. 3// 4// If one string argument is passed then it will listen for 5// an exact Redux `action.type`. 6// 7// If two string arguments are passed then the first argument should be 8// a `ReduxModule` namespace (the argument to `ReduxModule()` function) 9// and the second argument should be a name of an asynchronous `redux.action()`. 10// In that case, it will listen only for a "success" event of that `redux.action()`. 11// 12// To listen for a non-"success" event of a `redux.action()`, 13// specify the full Redux event name. 14// Example for a "pending" event: 'BLOG_POST: CUSTOM_EVENT_PENDING'. 15// 16redux.on('BLOG_POST', 'CUSTOM_EVENT', (state, action) => ({ 17 ...state, 18 reduxStateProperty: action.value 19}))
HTTP cookies
To enable sending and receiving cookies when making cross-domain HTTP requests, specify http.useCrossDomainCookies() function in react-pages.js configuration file. If that function returns true, then it has the same effect as changing credentials: "same-origin" to credentials: "include" in a fetch() call.
When enabling cross-domain cookies on front end, don't forget to make the relevant backend changes:
- Change
Access-Control-Allow-OriginHTTP header from*to an explict comma-separated list of the allowed domain names. - Add
Access-Control-Allow-Credentials: trueHTTP header.
1{ 2 http: { 3 // Allows sending cookies to and receiving cookies from 4 // "trusted.com" domain or any of its sub-domains. 5 useCrossDomainCookies({ getDomain, belongsToDomain, url, originalUrl }) { 6 return belongsToDomain('trusted.com') 7 } 8 } 9}
HTTP authentication
In order to send an authentication token in the form of an Authorization: Bearer ${token} HTTP header, specify http.authentication.accessToken() function in react-pages.js configuration file.
1{ 2 http: { 3 authentication: { 4 // If a token is returned from this function, it gets sent as 5 // `Authorization: Bearer {token}` HTTP header. 6 accessToken({ useSelector, getCookie }) { 7 return localStorage.getItem('accessToken') 8 } 9 } 10 } 11}
Protecting the access token from being leaked to a 3rd party
1{
2 http: {
3 authentication: {
4 // If a token is returned from this function, it gets sent as
5 // `Authorization: Bearer {token}` HTTP header.
6 accessToken({ useSelector, getCookie, url, originalUrl }) {
7 // It's recommended to check the URL to make sure that the access token
8 // is not leaked to a third party: only send it to your own servers.
9 //
10 // `originalUrl` is the URL argument of the `http` utility call.
11 // `url` is the `originalUrl` transformed by `http.transformUrl()` settings function.
12 // If no `http.transformUrl()` is configured then `url` is the same as the `originalUrl`.
13 //
14 if (url.indexOf('https://my.api.com/') === 0) {
15 return localStorage.getItem('accessToken')
16 }
17 }
18 }
19 }
20}Authentication and authorization using access tokens
The accessToken is initially obtained when a user signs in: the web browser sends HTTP POST request to /sign-in API endpoint with { email, password } parameters and gets { userInfo, accessToken } as a response, which is then stored in localStorage (or in Redux state, or in a cookie) and all subsequent HTTP requests use that accessToken to call the API endpoints. The accessToken itself is usually a JSON Web Token signed on the server side and holding the list of the user's priviliges ("roles"). Hence authentication and authorization are completely covered. Refresh tokens are also supported.
This kind of an authentication and authorization scheme is self-sufficient and doesn't require "restricting" any routes: if a route's load uses http utility for querying an API endpoint then this API endpoint must check if the user is signed in and if the user has the necessary priviliges. If yes then the route is displayed. If not then the user is redirected to either a "Sign In Required" page or "Access Denied" page.
A real-world (advanced) example for handling "Unauthenticated"/"Unauthorized" errors happening in loads and during http calls:
./react-pages.js
1{ 2 ..., 3 // Catches errors thrown from page `load()` functions. 4 onLoadError(error, { url, location, redirect, dispatch, useSelector, server }) { 5 // Not authenticated 6 if (error.status === 401) { 7 return handleUnauthenticatedError(error, url, redirect); 8 } 9 // Not authorized 10 if (error.status === 403) { 11 return redirect('/unauthorized'); 12 } 13 // Not found 14 if (error.status === 404) { 15 return redirect('/not-found'); 16 } 17 // Redirect to a generic error page in production 18 if (process.env.NODE_ENV === 'production') { 19 // Prevents infinite redirect to the error page 20 // in case of overall page rendering bugs, etc. 21 if (location.pathname !== '/error') { 22 // Redirect to a generic error page 23 return redirect(`/error?url=${encodeURIComponent(url)}`); 24 } 25 } else { 26 // Report the error 27 console.error('--------------------------------'); 28 console.error(`Error while loading "${url}"`); 29 console.error('--------------------------------'); 30 console.error(error.stack); 31 } 32 }, 33 34 http: { 35 // Catches all HTTP errors that weren't thrown from `load()` functions. 36 onError(error, { url, location, redirect, dispatch, useSelector }) { 37 // JWT token expired, the user needs to relogin. 38 if (error.status === 401) { 39 handleUnauthenticatedError(error, url, redirect); 40 // `return true` indicates that the error has been handled by the developer 41 // and it shouldn't be re-thrown as an "Unhandled rejection". 42 return true 43 } 44 }, 45 ... 46 } 47} 48 49function handleUnauthenticatedError(error, url, redirect) { 50 // Prevent double redirection to `/unauthenticated`. 51 // (e.g. when two parallel `Promise`s load inside `load` 52 // and both get Status 401 HTTP Response) 53 if (typeof window !== 'undefined' && window.location.pathname === '/unauthenticated') { 54 return; 55 } 56 let unauthenticatedURL = '/unauthenticated'; 57 let parametersDelimiter = '?'; 58 if (url !== '/') { 59 unauthenticatedURL += `${parametersDelimiter}url=${encodeURIComponent(url)}`; 60 parametersDelimiter = '&'; 61 } 62 switch (error.message) { 63 case 'TokenExpiredError': 64 return redirect(`${unauthenticatedURL}${parametersDelimiter}expired=✔`); 65 case 'AuthenticationError': 66 return redirect(`${unauthenticatedURL}`); 67 default: 68 return redirect(unauthenticatedURL); 69 } 70}
HTTP errors
This library doesn't force one to dispatch "asynchronous" Redux actions using the http utility in order to fetch data over HTTP. For example, one could use the standard fetch() function instead. But if one chooses to use the http utility, default error handlers for it could be set up.
To listen for http errors, one may specify two functions in react-pages.js configuration file:
onLoadError()— Catches all errors thrown from pageload()functions.http.onError()— Catches all HTTP errors that weren't thrown fromload()functions. Should returntrueif the error has been handled successfully and shouldn't be printed to the console.
1{
2 http: {
3 // (optional)
4 // Catches all HTTP errors that weren't thrown from `load()` functions.
5 onError(error, { url, location, redirect, dispatch, useSelector }) {
6 if (error.status === 401) {
7 redirect('/not-authenticated')
8 // `return true` indicates that the error has been handled by the developer
9 // and it shouldn't be re-thrown as an "Unhandled rejection".
10 return true
11 } else {
12 // Ignore the error.
13 }
14 },
15
16 // (optional)
17 // (advanced)
18 //
19 // Creates a Redux state `error` property from an HTTP `Error` instance.
20 //
21 // By default, returns whatever JSON data was returned in the HTTP response,
22 // if any, and adds a couple of properties to it:
23 //
24 // * `message: string` — `error.message`.
25 // * `status: number?` — The HTTP response status. May be `undefined` if no response was received.
26 //
27 getErrorData(error) {
28 return { ... }
29 }
30 }
31}HTTP request URLs
When sending HTTP requests to API using the http utility it is recommended to set up http.transformUrl(url) configuration setting to make the code a bit cleaner.
Before:
1// Actions. 2 3export const getUser = redux.action( 4 (id) => http => http.get(`https://my-api.cloud-provider.com/users/${id}`), 5 'user' 6) 7 8export const updateUser = redux.action( 9 (id, values) => http => http.put(`https://my-api.cloud-provider.com/users/${id}`, values) 10)
After:
1// Actions. 2 3export const getUser = redux.action( 4 (id) => http => http.get(`api://users/${id}`), 5 'user' 6) 7 8export const updateUser = redux.action( 9 (id, values) => http => http.put(`api://users/${id}`, values) 10) 11 12// Settings. 13 14{ 15 ... 16 http: { 17 transformUrl: url => `https://my-api.cloud-provider.com/${url.slice('api://'.length)}` 18 } 19}
On server side, user's cookies are attached to all relative "original" URLs so http.transformUrl(originalUrl) must not transform relative URLs into absolute URLs, otherwise user's cookies would be leaked to a third party.
File upload
The http utility will also upload files if they're passed as part of data (see example below). The files passed inside data must have one of the following types:
- In case of a
Fileit will be a single file upload. - In case of a
FileListwith a singleFileinside it would be treated as a singleFile. - In case of a
FileListwith multipleFiles inside a multiple file upload will be performed. - In case of an
<input type="file"/>DOM element all its.fileswill be taken as aFileListparameter.
File upload progress can be metered by passing progress option as part of the options .
See example
1// React component. 2function ItemPage() { 3 const dispatch = useDispatch() 4 5 const onFileSelected = (event) => { 6 const file = event.target.files[0] 7 8 // Could also pass just `event.target.files` as `file` 9 dispatch(uploadItemPhoto(itemId, file)) 10 11 // Reset the selected file 12 // so that onChange would trigger again 13 // even with the same file. 14 event.target.value = null 15 } 16 17 return ( 18 <div> 19 ... 20 <input type="file" onChange={onFileSelected}/> 21 </div> 22 ) 23} 24 25// Redux action creator 26function uploadItemPhoto(itemId, file) { 27 return { 28 promise: ({ http }) => http.post( 29 '/item/photo', 30 { itemId, file }, 31 { progress(percent) { console.log(percent) } } 32 ), 33 events: ['UPLOAD_ITEM_PHOTO_PENDING', 'UPLOAD_ITEM_PHOTO_SUCCESS', 'UPLOAD_ITEM_PHOTO_FAILURE'] 34 } 35}
JSON Date parsing
By default, when using http utility all JSON responses get parsed for javascript Dates which are then automatically converted from Strings to Dates.
This has been a very convenient feature that is also safe in almost all cases because such date Strings have to be in a very specific ISO format in order to get parsed (year-month-dayThours:minutes:seconds[timezone], e.g. 2017-12-22T23:03:48.912Z).
Looking at this feature now, I wouldn't advise enabling it because it could potentially lead to a bug when it accidentally mistakes a string for a date. For example, some user could write a comment with the comment content being an ISO date string. If, when fetching that comment from the server, the application automatically finds and converts the comment text from a string to a Date instance, it will likely lead to a bug when the application attempts to access any string-specific methods of such Date instance, resulting in a possible crash of the application.
Therefore, currenly I'd advise setting http.findAndConvertIsoDateStringsToDateInstances flag to false in react-pages.js settings file to opt out of this feature.
1{ 2 ... 3 http: { 4 ... 5 findAndConvertIsoDateStringsToDateInstances: false 6 } 7}
Snapshotting
Server-Side Rendering is good for search engine indexing but it's also heavy on CPU not to mention the bother of setting up a Node.js server itself and keeping it running.
In many cases data on a website is "static" (doesn't change between redeployments), e.g. a personal blog or a portfolio website, so in these cases it will be beneficial (much cheaper and faster) to host a statically generated version a website on a CDN as opposed to hosting a Node.js application just for the purpose of real-time webpage rendering. In such cases one should generate a static version of the website by snapshotting it on a local machine and then host the snapshotted pages in a cloud (e.g. Amazon S3) for a very low price.
Snapshotting instructions
First run the website in production mode (for example, on localhost).
Then run the following Node.js script which is gonna snapshot the currently running website and put it in a folder which can then be hosted anywhere.
1# If the website will be hosted on Amazon S3 2npm install @auth0/s3 --save
1import path from 'path' 2 3import { 4 // Snapshots website pages. 5 snapshot, 6 // Uploads files. 7 upload, 8 // Uploads files to Amazon S3. 9 S3Uploader, 10 // Copies files/folders into files/folders. 11 // Same as Linux `cp [from] [to]`. 12 copy, 13 // Downloads data from a URL into an object 14 // of shape `{ status: Number, content: String }`. 15 download 16} from 'react-pages/static-site-generator' 17 18import configuration from '../configuration' 19 20// Temporary generated files path. 21const generatedSitePath = path.resolve(__dirname, '../static-site') 22 23async function run() { 24 // Snapshot the website. 25 await snapshot({ 26 // The host and port on which the website 27 // is currently running in production mode. 28 // E.g. `localhost` and `3000`. 29 host: configuration.host, 30 port: configuration.port, 31 pages: await generatePageList(), 32 outputPath: generatedSitePath, 33 // 34 // Set this flag to `true` to re-run all `load`s on page load. 35 // For example, if the data used on the page can be updated 36 // in-between the static site deployments. 37 // reloadData: true 38 }) 39 40 // Copy assets (built by Webpack). 41 await copy(path.resolve(__dirname, '../build/assets'), path.resolve(generatedSitePath, 'assets')) 42 await copy(path.resolve(__dirname, '../robots.txt'), path.resolve(generatedSitePath, 'robots.txt')) 43 44 // Upload the website to an Amazon S3 bucket. 45 await upload(generatedSitePath, S3Uploader({ 46 // Setting an `ACL` for the files being uploaded is optional. 47 // Alternatively a bucket-wide policy could be set up instead: 48 // 49 // { 50 // "Version": "2012-10-17", 51 // "Statement": [{ 52 // "Sid": "AddPerm", 53 // "Effect": "Allow", 54 // "Principal": "*", 55 // "Action": "s3:GetObject", 56 // "Resource": "arn:aws:s3:::[bucket-name]/*" 57 // }] 58 // } 59 // 60 // If not setting a bucket-wide policy then the ACL for the 61 // bucket itself should also have "List objects" set to "Yes", 62 // otherwise the website would return "403 Forbidden" error. 63 // 64 ACL: 'public-read', 65 bucket: confiugration.s3.bucket, 66 accessKeyId: configuration.s3.accessKeyId, 67 secretAccessKey: configuration.s3.secretAccessKey, 68 region: configuration.s3.region 69 })) 70 71 console.log('Done'); 72} 73 74run().catch((error) => { 75 console.error(error) 76 process.exit(1) 77}) 78 79// Get the list of all page URLs. 80async function generatePageList() { 81 const pages = [ 82 '/', 83 '/about', 84 // Error pages need a `status` property 85 // to indicate that it shouldn't throw on such errors 86 // and should proceed with snapshotting the next pages. 87 { url: '/unauthenticated', status: 401 }, 88 { url: '/unauthorized', status: 403 }, 89 { url: '/not-found', status: 404 }, 90 { url: '/error', status: 500 } 91 ] 92 93 // (optional) Add some dynamic page URLs, like `/items/123`. 94 95 // Query the database for the list of items. 96 const { status, content } = JSON.parse(await download(`https://example.com/api/items`)) 97 98 if (status !== 200) { 99 throw new Error('Couldn\'t load items') 100 } 101 102 // Add item page URLs. 103 const items = JSON.parse(content) 104 return pages.concat(items.map(item => `/items/${item.id}`)) 105}
The snapshot() function snapshots the list of pages to .html files and then the upload() function uploads them to the cloud (in this case to Amazon S3). The snapshot() function also snapshots a special base.html page which is an empty page that should be used as the "fallback", i.e. the cloud should respond with base.html file contents when the file for the requested URL is not found: in this case base.html will see the current URL and perform all the routing neccessary on the client side to show the correct page. If the snapshot() function isn't passed the list of pages to snapshot (e.g. if pages argument is null or undefined) then it will only snapshot base.html. The static website will work with just base.html, the only point of snapshotting other pages is for Google indexing.
If the website is hosted on Amazon S3 then the IAM policy should allow:
1{ 2 "Version": "2012-10-17", 3 "Statement": [ 4 { 5 "Effect": "Allow", 6 "Action": [ 7 "s3:ListBucket" 8 ], 9 "Resource": [ 10 "arn:aws:s3:::<bucket-name>" 11 ] 12 }, 13 { 14 "Effect": "Allow", 15 "Action": [ 16 "s3:PutObject", 17 "s3:DeleteObject" 18 ], 19 "Resource": [ 20 "arn:aws:s3:::<bucket-name>/*" 21 ] 22 } 23 ] 24}
The snapshotting approach works not only for classical web "documents" (a blog, a book, a portfolio, a showcase) but also for dynamic applications. Consider an online education portal where users (students) can search for online courses and the prices are different for each user (student) based on their institution. Now, an online course description itself is static (must be indexed by Google) and the actual course price is dynamic (must not be indexed by Google).
The solution is to add two loads for the course page: one for static data (which runs while snapshotting) and another for dynamic data (which runs only in a user's web browser).
1import React from 'react' 2 3export default function CoursePage() { 4 ... 5} 6 7CoursePage.load = [ 8 async ({ dispatch }) => await dispatch(loadCourseInfo()), 9 { 10 load: async ({ dispatch }) => await dispatch(loadCoursePrice()), 11 client: true 12 } 13]
In this example loadCourseInfo() will be executed while snapshotting and therefore course info will be present on the snapshotted page. But course price won't be present on the snapshotted page because it's being loaded inside the client: true load that only gets called in a user's web browser. When a user opens the course page in his web browser it will show the snapshotted page with course info with a "loading" spinner on top of it as it is loading the course price. After the course price has been loaded the "loading" spinner disappears and the user sees the fully rendered course page.
Page HTTP response status code
To set a custom HTTP response status code for a specific route set the status property of that route.
1export default [{ 2 path: '/', 3 Component: Application, 4 children: [ 5 { Component: Home }, 6 { path: 'blog', Component: Blog }, 7 { path: 'about', Component: About }, 8 { path: '*', Component: PageNotFound, status: 404 } 9 ] 10}]
Setting <title/> and <meta/> tags
To add <title/> and <meta/> tags to a page, define meta: (...) => object static function on a page component:
1function Page() { 2 return ( 3 <section> 4 ... 5 </section> 6 ) 7} 8 9Page.load = async ({ params }) => { 10 return { 11 props: { 12 bodyBuilder: await getBodyBuilderInfo(params.id) 13 } 14 } 15} 16 17Page.meta = ({ props, useSelector, usePageStateSelector }) => { 18 const notificationsCount = useSelector(state => state.user.notificationsCount) 19 20 const { bodyBuilder } = props 21 22 return { 23 // `<meta property="og:site_name" .../>` 24 siteName: 'International Bodybuilders Club', 25 26 // Webpage `<title/>` will be replaced with this one 27 // and also `<meta property="og:title" .../>` will be added. 28 title: `(${notificationsCount}) ${bodyBuilder.name}`, 29 30 // `<meta property="og:description" .../>` 31 description: 'Muscles', 32 33 // `<meta property="og:image" .../>` 34 // https://iamturns.com/open-graph-image-size/ 35 image: 'https://cdn.google.com/logo.png', 36 37 // Objects are expanded. 38 // 39 // `<meta property="og:image" content="https://cdn.google.com/logo.png"/>` 40 // `<meta property="og:image:width" content="100"/>` 41 // `<meta property="og:image:height" content="100"/>` 42 // `<meta property="og:image:type" content="image/png"/>` 43 // 44 image: { 45 _: 'https://cdn.google.com/logo.png', 46 width: 100, 47 height: 100, 48 type: 'image/png' 49 }, 50 51 // Arrays are expanded (including arrays of objects). 52 image: [{...}, {...}, ...], 53 54 // `<meta property="og:audio" .../>` 55 audio: '...', 56 57 // `<meta property="og:video" .../>` 58 video: '...', 59 60 // `<meta property="og:locale" content="ru_RU"/>` 61 locale: state.user.locale, 62 63 // `<meta property="og:locale:alternate" content="en_US"/>` 64 // `<meta property="og:locale:alternate" content="fr_FR"/>` 65 locales: ['ru_RU', 'en_US', 'fr_FR'], 66 67 // `<meta property="og:url" .../>` 68 url: 'https://google.com/', 69 70 // `<meta property="og:type" .../>` 71 type: 'profile', 72 73 // `<meta charset="utf-8"/>` tag is added automatically. 74 // The default "utf-8" encoding can be changed 75 // by passing custom `charset` parameter. 76 charset: 'utf-16', 77 78 // `<meta name="viewport" content="width=device-width, initial-scale=1.0"/>` 79 // tag is added automatically 80 // (prevents downscaling on mobile devices). 81 // This default behaviour can be changed 82 // by passing custom `viewport` parameter. 83 viewport: '...', 84 85 // All other properties will be transformed directly to 86 // either `<meta property="{property_name}" content="{property_value}/>` 87 // or `<meta name="{property_name}" content="{property_value}/>` 88 } 89})
The parameters of a meta function are:
props— Anypropsreturned from theload()function.useSelector— A hook that could be used to access Redux state.usePageSelector— A hook that could be used to access "page-specific" Redux state.
If the root route component also has a meta function, the result of the page component's meta function will be merged on top of the result of the root route component's meta function.
The meta will be applied on the web page and will overwrite any existing <meta/> tags. For example, if there were any <meta/> tags written by hand in index.html template then all of them will be dicarded when this library applies its own meta, so any "base" <meta/> tags should be moved from the index.html file to the root route component's meta function:
1function App({ children }) { 2 return ( 3 <div> 4 {children} 5 </div> 6 ) 7} 8 9App.meta = ({ useSelector }) => { 10 return { 11 siteName: 'WebApp', 12 description: 'A generic web application', 13 locale: 'en_US' 14 } 15}
The meta function behaves like a React "hook": <meta/> tags will be updated if the values returned from useSelector() function calls do change.
In some advanced cases, the meta() function might need to access some state that is local to the page component and is not stored in global Redux state. That could be done by setting metaComponentProperty property of a page component to true and then rendering the <Meta/> component manually inside the page component, where any properties passed to the <Meta/> component will be available in the props of the meta() function.
1function Page({ Meta }) { 2 const [number, setNumber] = useState(0) 3 return ( 4 <> 5 <Meta number={number}/> 6 <button onClick={() => setNumber(number + 1)}> 7 Increment 8 </button> 9 </> 10 ) 11} 12 13Page.metaComponentProperty = true 14 15Page.meta = ({ props }) => { 16 return { 17 title: String(props.number) 18 } 19}
Navigation Listener
If the application would like to listen to navigation changes — for example, to report the current location to Google Analytics — it might supply onPageRendered() function option to the client-side render() function:
See code example
1import { render } from 'react-pages/client' 2 3await render(settings, { 4 // Runs on the initial page load, and then after each navigation to some page. 5 onPageRendered({ 6 // Relative URL. 7 url, 8 // `location` object. 9 location, 10 // URL pathname parameters. 11 params, 12 // (optional) If `getLoadContext()` function is defined, 13 // this will be the result of calling that function. 14 context, 15 // Redux `dispatch()` function. 16 dispatch, 17 // Mimicks Redux `useSelector()` hook. 18 useSelector 19 }) { 20 if (process.env.NODE_ENV === 'production') { 21 // Set up Google Analytics via `gtag`. 22 gtag('config', configuration.googleAnalytics.id, { 23 // Anonymize IP for all Google Analytics events. 24 // https://developers.google.com/analytics/devguides/collection/gtagjs/ip-anonymization 25 // This makes Google Analytics compliant with GDPR: 26 // https://www.jeffalytics.com/gdpr-ip-addresses-google-analytics/ 27 'anonymize_ip': true, 28 // Google Analytics can get users' "Demographics" (age, sex) 29 // from "3rd party" data sources if "Advertising Reporting Features" 30 // are enabled in Google Analytics admin panel. 31 // Such data could be considered "Personal Identifiable Information" 32 // which falls under the terms of GDPR. 33 // There's also "Remarketing" feature that could also 34 // fall under the terms of GDPR. 35 'allow_display_features': false, 36 // Specifies what percentage of users should be tracked. 37 // This defaults to 100 (no users are sampled out) but 38 // large sites may need to use a lower sample rate 39 // to stay within Google Analytics processing limits. 40 // 'sample_rate': 1, 41 // Report "page view" event to Google Analytics. 42 // https://stackoverflow.com/questions/37655898/tracking-google-analytics-page-views-in-angular2 43 // https://developers.google.com/analytics/devguides/collection/gtagjs/single-page-applications 44 'page_path': location.pathname 45 }) 46 } 47 } 48})
onPageRendered() function option only gets called after the navigation has finished. It also gets called at the initial page load when the user opens the website.
If navigation start events are of interest, one may supply onBeforeNavigate() function option, which is basically the same as onPageRendered() but runs before the navigation has started.
Get current location
Inside a load function: use the location parameter.
Anywhere in a React component: use useLocation() hook.
1import { useLocation } from 'react-pages' 2 3const location = useLocation()
Get Redux state for current location
One edge case is when an application is architectured in such a way that:
- A certain page
Componenthandles a certain route.- For example, an
Itempage component handles/items/:idURLs.
- For example, an
- For that route, it is possible to navigate to the same route but with different route parameters.
- For example, a user could navigate from
/items/1to/items/2via a "Related items" links section.
- For example, a user could navigate from
- The page
Componenthas a.load()function that puts data in Redux state.- For example, the
Itempage component firstfetch()es item data and then puts it in Redux state viadispatch(setItem(itemData)).
- For example, the
- The page
Componentuses the loaded data from the Redux state.- For example, the
Itempage component gets the item data viauseSelector()and renders it on the page.
- For example, the
In the above example, when a user navigates from item A to item B, there's a short timeframe of inconsistency:
- Item
Apage renders itemAdata from Redux state. - User clicks the link to item
B. - Item
Bdata is fetched and put into Redux state. - Item
Apage is still rendered.useSelector()on it gets refreshed with the new data from Redux state and now returns itemBdata while still being on itemApage. - The navigation finishes and item
Bpage is rendered.useSelector()on it returns itemBdata.
In the steps above, there's a short window of data inconsistency at the step before the last one: the page component experiences a data update from item A to item B.
If the page component doesn't account for a possibility of such change, it may lead to tricky bugs. For example, each item could have a list of reviews and the page component can be showing one review at a time. To do that, the page component introduces its own local state — a shownReviewIndex state variable — and then shows the review via <Review review={item.reviews[shownReviewIndex]}/>. In such case, when a user navigates from item A that has some reviews to item B that has no reviews, the review property value is gonna be undefined which would break the <Review/> component which would crash the whole page and display a blank screen to the user.
To work around such issues, any potentially unexpected updates to Redux state should be minimized inside page components. To do that, this package provides a parameter in the settings called pageStateReducerNames: string[] and a set of two hooks that're meant to replace the standard useSelector() hook for use in page components.
The standard route configuration usually has a "root" route and all other routes that branch out from it:
1export default [{ 2 path: "/", 3 Component: App, 4 children: [ 5 { path: 'not-found', Component: NotFound, status: 404 }, 6 { path: 'error', Component: Error, status: 500 }, 7 ... 8 ] 9}]
The pageStateReducerNames parameter is specified in the settings and it should be a list of all Redux state keys that get modified from inside page .load() functions:
1export default { 2 routes, 3 reducers, 4 pageStateReducerNames: ['orderPage'] 5}
Those state keys become inaccessible via the standard useSelector() hook and should be accessed via either usePageStateSelector() hook or usePageStateSelectorOutsideOfPage() hook, depending on where in the route component chain the hook is being called.
Using the hook somewhere inside a page component (or in its children):
1import { usePageStateSelector } from 'react-pages' 2 3export default function Page() { 4 // const order = useSelector(state => state.orderPage.order) 5 const order = usePageStateSelector('orderPage', state => state.orderPage.order) 6 ... 7}
Using the hook somewhere outside a page component:
1export default function Page() { 2 // const order = useSelector(state => state.orderPage.order) 3 const order = usePageStateSelectorOutsideOfPage('orderPage', state => state.orderPage.order) 4 ... 5}
To access "page state" properties in page .meta() functions, there's a parameter called usePageStateSelector that work analogous to the usePageStateSelector() exported hook.
Get last location in the navigation chain
useNavigationLocation hook returns "navigation location" — the last location (so far) in the navigation chain:
- When a user starts navigating to a page, the "navigation location" set to that new page's location.
- If there's an error during said navigation, the "navigation location" is reset back to the current page's location.
Get current route
Inside a load function: you already know what route it is.
Anywhere in a React component: use useRoute() hook.
1import { useRoute } from 'react-pages' 2 3const route = useRoute()
A route has:
path— Example:"/users/:id"params— Example:{ id: "12345" }location— Same asuseLocation()
Changing current location
To navigate to a different URL inside a React component, use useNavigation() hook.
1import { useNavigate, useRedirect } from 'react-pages' 2 3// Usage example. 4// * `navigate` navigates to a URL while adding a new entry in browsing history. 5// * `redirect` does the same replacing the current entry in browsing history. 6function Page() { 7 const navigate = useNavigate() 8 // const redirect = useRedirect() 9 const onClick = (event) => { 10 navigate('/items/1?color=red') 11 // redirect('/somewhere') 12 } 13}
-
One could also pass a
load: falseparameter inoptionswhen callingnavigate(location, options)orredirect(location, options)to skip the.load()function of the target page. -
One could also pass a
navigationparameter inoptionswhen callingnavigate(location, options)orredirect(location, options)to pass an additional parameter callednavigationContextto the.load()function of the target page.
If the current location URL needs to be updated while still staying at the same page (i.e. no navigation should take place), then instead of redirect(location, options) one should call locationHistory.replace(location).
1import { useLocationHistory } from 'react-pages' 2 3function Page() { 4 const locationHistory = useLocationHistory() 5 6 // * `locationHistory.push(location)` 7 // * `locationHistory.replace(location)` 8 // * `locationHistory.go(-1)` 9 10 const onSearch = (searchQuery) => { 11 dispatch( 12 locationHistory.replace({ 13 pathname: '/' 14 query: { 15 searchQuery 16 } 17 }) 18 ) 19 } 20 return ( 21 <input onChange={onSearch}/> 22 ) 23}
To go "Back" or "Forward", one could use useGoBack() or useGoForward() hooks.
1import { useLocationHistory } from 'react-pages' 2 3function Page() { 4 const goBack = useGoBack() 5 const goForward = useGoForward() 6 return ( 7 <button onClick={() => goBack()}> 8 Back 9 </button> 10 ) 11}
Both goBack() and goForward() functions accept an optional delta numeric argument that tells how far should it "go" in terms of the number of entries in the history. The default delta is 1.
If someone prefers to interact with found router directly then it could be accessed at any page: either as a router property of a page component or via useRouter hook.
1import React from 'react' 2import { useRouter } from 'react-pages' 3 4export default function Component() { 5 const { match, router } = useRouter() 6 ... 7}
Changing current location (outside of React component code)
In places where React hooks can't be used, there're dispatch()-able action creator alternatives to each navigation type. Those action creators are exported from this package: import { goto } from "react-pages".
dispatch(goto())→useNavigate()()dispatch(redirect())→useRedirect()()dispatch(pushLocation())→useLocationHistory().push()dispatch(replaceLocation())→useLocationHistory().replace()dispatch(goBack())→useGoBack()()dispatch(goBackTwoPages())→2xuseGoBack()()dispatch(goForward())→useGoForward()()
Get notified when navigation starts or ends
1import { 2 // These hooks can only be used in "leaf" route components. 3 useBeforeNavigateToAnotherPage, 4 useBeforeRenderAnotherPage, 5 useAfterRenderedThisPage, 6 7 // These hooks can only be used in a "root" route component. 8 useBeforeRenderNewPage, 9 useAfterRenderedNewPage 10} from 'react-pages' 11 12function Page() { 13 useBeforeNavigateToAnotherPage(({ location, route, params, instantBack, navigationContext }) => { 14 // Navigation to another page is about to start. 15 // It will start `.load()`ing another page. 16 // This is an appropriate time to snapshot the current page state. 17 }) 18 19 useBeforeRenderAnotherPage(({ location, route, params, instantBack, navigationContext }) => { 20 // Navigation to another page is about to conclude. 21 // That other page has already been `.load()`ed and is about to be rendered. 22 // The current page is about to be unmounted. 23 }) 24 25 useAfterRenderedThisPage(({ location, route, params, instantBack, navigationContext }) => { 26 // This page is currently rendered on screen. 27 // Is triggered at the initial render of the app and then after each navigation. 28 }) 29 30 return ( 31 <section> 32 <h1> 33 Page Title 34 </h1> 35 </section> 36 ) 37} 38 39function Root({ children }) { 40 useBeforeRenderNewPage((newPage, prevPage?) => { 41 // Will render a new page on screen. 42 // 43 // const { location, route, params, instantBack, navigationContext } = newPage 44 }) 45 46 useAfterRenderedNewPage((newPage, prevPage?) => { 47 // Has rendered a new page on screen. 48 // The initial render of the app also counts as "after rendered new page". 49 // 50 // const { location, route, params, instantBack, navigationContext } = newPage 51 }) 52 53 return ( 54 <main> 55 {children} 56 </main> 57 ) 58}
Monitoring
For each page being rendered stats are reported if stats() parameter is passed as part of the rendering service settings.
1{ 2 ... 3 4 stats({ url, route, time: { load } }) { 5 if (load > 1000) { // in milliseconds 6 db.query('insert into server_side_rendering_stats ...') 7 } 8 } 9}
The arguments for the stats() function are:
url— The requested URL (without theprotocol://host:portpart)route— The route path (e.g./user/:userId/post/:postId)time.load— The time for executing allloads.
Rendering a complex React page (having more than 1000 components) takes about 30ms (as of 2017).
One could also set up overall Server Side Rendering performance monitoring using, for example, StatsD
1{ 2 ... 3 4 stats({ url, route, time: { initialize, load, total } }) { 5 statsd.increment('count') 6 7 statsd.timing('initialize', initialize) 8 statsd.timing('load', load) 9 statsd.timing('total', total) 10 11 if (total > 1000) { // in milliseconds 12 db.query('insert into server_side_rendering_stats ...') 13 } 14 } 15}
Where the metrics collected are
count— rendered pages countinitialize— server sideinitialize()function execution time (if defined)load— page loading timetime- total time spent loading and rendering the page
Speaking of StatsD itself, one could either install the conventional StatsD + Graphite bundle or, for example, use something like Telegraf + InfluxDB + Grafana.
Telegraf starter example:
1# Install Telegraf (macOS). 2brew install telegraf 3# Generate Telegraf config. 4telegraf -input-filter statsd -output-filter file config > telegraf.conf 5# Run Telegraf. 6telegraf -config telegraf.conf 7# Request a webpage and see rendering stats being output to the terminal.
Hot Reload
React Hot Reload via Webpack HMR
Webpack's Hot Module Replacement (aka Hot Reload) provides the ability to "hot reload" React components.
To enable hot reload for React components, one could use a combination of react-refresh/babel Babel plugn and react-refresh-webpack-plugin Webpack plugin.
npm install @pmmmwh/react-refresh-webpack-plugin react-refresh --save-dev
.babelrc
1{ 2 "presets": [ 3 "react", 4 ["env", { modules: false }] 5 ], 6 7 "plugins": [ 8 // React "Fast Refresh". 9 "react-refresh/babel" 10 ] 11}
webpack.config.js
1import ReactRefreshWebpackPlugin from '@pmmmwh/react-refresh-webpack-plugin' 2 3export default { 4 mode: 'development', 5 ..., 6 plugins: [ 7 new ReactRefreshWebpackPlugin(), 8 ... 9 ] 10}
Then start webpack-dev-server.
webpack serve --hot --module-strict-export-presence --stats-errors --stats-error-details true --config path-to-webpack.config.js"
P.S.: Hot reload won't work for page component's load/meta functions, so when a load/meta function code is updated, the page has to be refreshed in order to observe the changes.
Redux Hot Reload via Webpack HMR
Webpack's Hot Module Replacement (aka Hot Reload) provides the ability to "hot reload" Redux reducers and Redux action creators.
Enabling "hot reload" for Redux reducers and Redux action creators is slightly more complex and requires some additional "hacky" code. The following line:
1import * as reducers from './redux/reducers.js'
Should be replaced with:
1import * as reducers from './redux/reducers.with-hot-reload.js'
And a new file called reducers.with-hot-reload.js should be created:
1import { updateReducers } from 'react-pages' 2 3import * as reducers from './reducers.js' 4 5export * from './reducers.js' 6 7if (import.meta.webpackHot) { 8 import.meta.webpackHot.accept(['./reducers.js'], () => { 9 updateReducers(reducers) 10 }) 11}
And then add some additional code in the file that calls the client-side render() function:
1import { render } from 'react-pages/client' 2 3import settings from './react-pages.js' 4 5export default async function() { 6 const { enableHotReload } = await render(settings) 7 8 if (import.meta.webpackHot) { 9 enableHotReload() 10 } 11}
WebSocket
websocket() helper sets up a WebSocket connection.
1import { render } from 'react-pages/client' 2import websocket from 'react-pages/websocket' 3 4render(settings).then(({ store }) => { 5 websocket({ 6 host: 'localhost', 7 port: 80, 8 // secure: true, 9 store, 10 token: localStorage.getItem('token') 11 }) 12})
If token parameter is specified then it will be sent as part of every message (providing support for user authentication).
How to use WebSocket
WebSocket will autoreconnect (with "exponential backoff") emitting open event every time it does.
After the websocket() call a global websocket variable is created exposing the following methods:
listen(eventName, function(event, store))onOpen(function(event, store))– is called onopeneventonClose(function(event, store))– is called oncloseeventonError(function(event, store))– is called onerrorevent (closeevent always follows the correspondingerrorevent)onMessage(function(message, store))send(message)close()
The store argument can be used to dispatch() Redux "actions".
1websocket.onMessage((message, store) => { 2 if (message.command) { 3 switch (message.command) { 4 case 'initialized': 5 store.dispatch(connected()) 6 return console.log('Realtime service connected', message) 7 case 'notification': 8 return alert(message.text) 9 default: 10 return console.log('Unknown message type', message) 11 } 12 } 13}) 14 15websocket.onOpen((event, store) => { 16 websocket.send({ command: 'initialize' }) 17}) 18 19websocket.onClose((event, store) => { 20 store.dispatch(disconnected()) 21})
The global websocket object also exposes the socket property which is the underlying robust-websocket object (for advanced use cases).
As for the server-side counterpart I can recommend using uWebSockets
1import WebSocket from 'uws' 2 3const server = new WebSocket.Server({ port: 8888 }) 4 5const userConnections = {} 6 7server.on('connection', (socket) => { 8 console.log('Incoming WebSocket connection') 9 10 socket.sendMessage = (message) => socket.send(JSON.stringify(message)) 11 12 socket.on('close', async () => { 13 console.log('Client disconnected') 14 15 if (socket.userId) { 16 userConnections[socket.userId].remove(socket) 17 } 18 }) 19 20 socket.on('message', async (message) => { 21 try { 22 message = JSON.parse(message) 23 } catch (error) { 24 return console.error(error) 25 } 26 27 try { 28 switch (message.command) { 29 case 'initialize': 30 // If a user connected (not a guest) 31 // then store `userId` for push notifications. 32 // Using an authentication token here 33 // instead of simply taking `userId` out of the `message` 34 // because the input can't be trusted (could be a hacker). 35 if (message.userAuthenticationToken) { 36 // (make sure `socket.userId` is a `String`) 37 // The token could be a JWT token (jwt.io) 38 // and `authenticateUserByToken` function could 39 // check the token's authenticity (by verifying its signature) 40 // and then extract `userId` out of the token payload. 41 socket.userId = authenticateUserByToken(message.userAuthenticationToken) 42 43 if (!userConnections[socket.userId]) { 44 userConnections[socket.userId] = [] 45 } 46 47 userConnections[socket.userId].push(socket) 48 } 49 50 return socket.sendMessage({ 51 command: 'initialized', 52 data: ... 53 }) 54 55 default: 56 return socket.sendMessage({ 57 status: 404, 58 error: `Unknown command: ${message.command}` 59 }) 60 } 61 } catch (error) { 62 console.error(error) 63 } 64 }) 65}) 66 67server.on('error', (error) => { 68 console.error(error) 69}) 70 71// Also an HTTP server is started and a REST API endpoint is exposed 72// which can be used for pushing notifications to clients via WebSocket. 73// The HTTP server must only be accessible from the inside 74// (i.e. not listening on an external IP address, not proxied to) 75// otherwise an attacker could push any notifications to all users. 76// Therefore, only WebSocket connections should be proxied (e.g. using NginX). 77httpServer().handle('POST', '/notification', ({ to, text }) => { 78 if (userConnections[to]) { 79 for (const socket of userConnections[to]) { 80 socket.sendMessage({ 81 command: 'notification', 82 text 83 }) 84 } 85 } 86})
Feature: upon receiving a message (on the client side) having a type property defined such a message is dispatch()ed as a Redux "action" (this can be disabled via autoDispatch option). For example, if { type: 'PRIVATE_MESSAGE', content: 'Testing', from: 123 } is received on a websocket connection then it is automatically dispatch()ed as a Redux "action". Therefore, the above example could be rewritten as
1// Server side (REST API endpoint) 2socket.sendMessage({ 3 type: 'DISPLAY_NOTIFICATION', 4 text 5}) 6 7// Client side (Redux reducer) 8function reducer(state, action) { 9 switch (action.type) { 10 case 'DISPLAY_NOTIFICATION': 11 return { 12 ...state, 13 notifications: state.notifications.concat([action.text]) 14 } 15 default: 16 return state 17 } 18}
Server-Side Rendering and bundlers
If the application is being built with a bundler (most likely Webpack) and Server-Side Rendering is enabled then make sure to build the server-side code with the bundler too so that require() calls for assets (images, styles, fonts, etc) inside React components don't break (see universal-webpack, for example).
Code splitting
Code splitting is supported. See README-CODE-SPLITTING
Get cookies and HTTP headers on server side
When server-side rendering is enabled, one can pass a getInitialState() function as an option to the server-side rendering function.
That function should return an object — the initial Redux state — based on its parameters:
cookies— Cookies JSON object.headers— HTTP request headers JSON object.locales— A list of locales parsed fromAccept-LanguageHTTP header and ordered by most-preferred ones first.
For example, the application could set defaultLocale initial state property based on the Accept-Language HTTP header value, or it could set device initial state property based on the User-Agent HTTP header value.
Known Issues
Same Route Navigation
Suppose there's a "forum" web application having <Thread/> pages with URLs like /thread/:id, and one thread could link to another thread. When a user navigates to a thread and clicks a link to another thread there, a navigation transition will start: the "current" thread page will still be rendered while the "new" thread page is loading. The issue is that both these URLs use the same Redux state subtree, so, after the "new" thread data has been loaded, but before the "new" thread page is rendered, the "current" thread page is gonna re-render with the updated Redux state subtree.
If a thread page doesn't use useState(), then it wouldn't be an issue. But if it does, it could result in weird bugs. For example, if a <Thread/> page had a fromIndex state variable that would control the first shown comment index, then, when the "current" page is re-rendered with the updated Redux state subtree for the "new" thread, the fromIndex might exceed the "new" thread's comments count resulting in an "out of bounds" exception and the page breaking.
To prevent such bugs, for all routes that could link to the same route, their page components should be rendered in a wrapper with a key corresponding to all URL parameters:
1function Thread() {
2 const [fromIndex, setFromIndex] = useState(0)
3 return ...
4}
5
6Thread.meta = ...
7Thread.load = async ({ dispatch, params }) => {
8 await dispatch(loadThreadData(params.id))
9}
10
11// This is a workaround for cases when navigating from one thread
12// to another thread in order to prevent bugs when the "new" thread data
13// has already been loaded and updated in Redux state but the "old" thread
14// page is still being rendered.
15// https://github.com/4Catalyzer/found/issues/639#issuecomment-567084189
16export default function Thread_() {
17 const thread = useSelector(state => state.thread.thread)
18 return <Thread key={thread.id}/>
19}
20Thread_.meta = Thread.meta
21Thread_.load = Thread.loadAdvanced
At some point in time this README became huge so I extracted some less relevant parts of it into README-ADVANCED (including the list of all possible settings and options). If you're a first timer then just skip that one - you don't need it for sure.
License
No vulnerabilities found.
No security vulnerabilities found.