crossroad 0.14.0 → 0.16.0

package/index.min.js

@@ -1 +1 @@
-import e,{createContext as t,useContext as r,useState as n,useEffect as o}from"react";const i=e=>{if("string"!=typeof e)return e;const t={},r=new URL(e,"http://localhost:3000/");var n;(t.path=r.pathname.replace(/\/$/,"")||"/",r.hash)&&(t.hash=null===(n=r.hash)||void 0===n?void 0:n.replace(/^#/,""));t.query={};for(const[e,n]of r.searchParams)t.query[e]=n;return t};function a(e,t,r={}){if(e=JSON.parse(JSON.stringify(i(e))),(t=JSON.parse(JSON.stringify(i(t)))).path.endsWith("/")&&(t.path=t.path.slice(0,-1)||"/"),e.path.endsWith("/")&&(e.path=e.path.slice(0,-1)||"/"),e.path.endsWith("*")){e.path=e.path.replace(/\/?\*/,"")||"/";const r=e.path.slice(1).split("/").filter(Boolean).length;t.path="/"+t.path.slice(1).split("/").slice(0,r).join("/")}if(Object.entries(e.query).length)for(let r in e.query){if(!(r in t.query))return!1;if(e.query[r]&&e.query[r]!==t.query[r])return!1}if(t.path===e.path)return!0;if(!e.path.includes(":"))return e.path===t.path;if(e.path.split("/").length!==t.path.split("/").length)return!1;const n={},o=e.path.split("/").every((e,r)=>{const o=t.path.split("/")[r];return e.startsWith(":")?(n[e.slice(1)]=o,!0):o===e});return o&&Object.assign(r,n),o}var s=t();const l=()=>{const e=r(s);if(!e)throw new Error("Hooks should be used as children of <Router>");return e},u=()=>{const[e,t]=l();return[e.path,(r,n)=>t({...e,path:r},n)]},p=e=>{const[t,r]=l(),n=t.query,o=(e,n)=>r({...t,query:e},n);return e?[n[e],(t,r)=>o({...n,[e]:t},r)]:[n,o]},c=()=>{const[e,t]=l();return[e.hash,(r,n)=>t({...e,hash:r},n)]},h=e=>{const t=r(s),[n]=u();if(e){const t={};return a(e,n,t),t}return t[0].params},d=({path:t="*",exact:n=!0,component:o,render:i,children:u})=>{const p=r(s),[c,h]=l(),d={};if(!a(t,c,d))return null;const f=[{...p[0],params:d},p[1]];if(o){const t=o;return e.createElement(s.Provider,{value:f},e.createElement(t,d))}if(i)return e.createElement(s.Provider,{value:f},i(d));if(u)return e.createElement(s.Provider,{value:f},u);throw new Error("Route needs the prop `component`, `render` or `children`")},f=({redirect:e,children:t})=>{const[r,n]=l(),i=(e=>e?Array.isArray(e)?[...e]:[e]:[])(t).find(e=>a(e.props.path||"*",r))||null;return o(()=>{e&&!i&&n(e)},[e,Boolean(i)]),i};export default({url:t,children:r})=>{const a="undefined"==typeof window?"/":window.location.href,[l,u]=n(i(t||a)),p=(e,t={mode:"push"})=>{"string"==typeof e&&(e=i(e));const r=(({path:e,query:t,hash:r}={})=>{let n=e||"/";return t&&Object.keys(t).length&&(n+="?",n+=Object.entries(t).filter(([e,t])=>t||""===t).map(([e,t])=>e+"="+encodeURIComponent(t)).join("&")),r&&(n+="#"+r),n})(e);if(!["push","replace"].includes(t.mode))throw new Error(`Unrecognized mode "${t.mode}"`);"replace"===t.mode?history.replaceState({},null,r):history.pushState({},null,r),u(e)};return o(()=>{const e=e=>u(i(window.location.href)),t=e=>{const t=(e=>{if(!e)return null;const t=e.getAttribute("href");return t?/^https?:\/\//.test(t)||null!==e.getAttribute("target")?null:t:null})(e.target.closest("a"));t&&(e.preventDefault(),p(t))};return"undefined"!=typeof window&&window.addEventListener("popstate",e),"undefined"!=typeof document&&document.addEventListener("click",t),()=>{"undefined"!=typeof window&&window.removeEventListener("popstate",e),"undefined"!=typeof document&&document.removeEventListener("click",t)}},[]),e.createElement(s.Provider,{value:[l,p]},r)};export{s as Context,d as Route,f as Switch,c as useHash,h as useParams,u as usePath,p as useQuery,l as useUrl};
+import t,{createContext as e,useState as r,useEffect as n,useContext as a}from"react";var o=e();const s=t=>{if("string"!=typeof t)return t;const e={},r=new URL(t,"http://localhost:3000/");e.path=r.pathname.replace(/\/$/,"")||"/",e.query={};for(const[t]of r.searchParams)e.query[t]=(n=r.searchParams.getAll(t)).length>1?n:n[0];var n;return r.hash&&(e.hash=r.hash.replace(/^#/,"")),e},i=t=>{if("string"==typeof t)return t;const{path:e,query:r={},hash:n}=t||{};let a=e||"/";const o=new URLSearchParams(Object.entries(r).map(([t,e])=>(e.map?e:[e]).map(e=>[t,e])).flat()).toString();return o&&(a+="?"+o),n&&(a+="#"+n),a};var p=()=>"undefined"==typeof window;function l(t,e,r={}){if(t=JSON.parse(JSON.stringify(s(t))),(e=JSON.parse(JSON.stringify(s(e)))).path=e.path.replace(/\/$/,"")||"/",t.path=t.path.replace(/\/$/,"")||"/",t.path.endsWith("*")){t.path=t.path.replace(/\/?\*/,"")||"/";const r=t.path.split("/").filter(Boolean).length;e.path="/"+e.path.slice(1).split("/").slice(0,r).join("/")}if(Object.entries(t.query).length)for(let r in t.query){if(!(r in e.query))return!1;if(t.query[r]&&t.query[r]!==e.query[r])return!1}if(!t.path.includes(":"))return t.path===e.path&&r;if(t.path.split("/").length!==e.path.split("/").length)return!1;const n={},a=t.path.split("/").every((t,a)=>{const o=e.path.split("/")[a];return t.startsWith(":")?(n[t.slice(1)]=o,r):o===t});return a&&Object.assign(r,n),a&&r}var h=({path:e="*",exact:r=!0,component:n,render:s,children:i})=>{const p=a(o),h=l(e,p[0]);if(!h)return null;if(n){const e=n;i=t.createElement(e,h)}else if(s)i=s(h);else if(!i)throw new Error("Route needs prop `component`, `render` or `children`");return t.createElement(o.Provider,{value:[{...p[0],params:h},...p.slice(1)]},i)},c=()=>{const t=a(o);if(!t)throw new Error("Wrap your App with <Router>");return t};var u=({redirect:t,children:e})=>{const[r,a]=c(),o=(t=>(Array.isArray(t)||(t=[t]),t.filter(t=>t&&t.props)))(e).find(t=>l(t.props.path||"*",r))||null;return n(()=>{t&&(o||("function"==typeof t&&(t=t(r)),a(i(t))))},[t,o]),o},f=()=>{const[t,e]=c();return[t.path,(r,n)=>e({...t,path:r},n)]},d=t=>{const[e,r]=c(),n=e.query,a=(t,n)=>r({...e,query:t},n);return t?[n[t],(e,r)=>a({...n,[t]:e},r)]:[n,a]},y=()=>{const[t,e]=c();return[t.hash,(r,n)=>e({...t,hash:r},n)]},m=t=>{const e=a(o);return t?l(t,e[0].path)||{}:e[0].params};export default({url:e,children:a})=>{const l=e||(p()?"/":window.location.href),[h,c]=r(()=>s(l)),u=(t,{mode:e="push"}={})=>{if(!history[e+"State"])throw new Error(`Invalid mode "${e}"`);history[e+"State"]({},null,i(t)),c(s(t))};return n(()=>{if(p())return;const t=()=>u(window.location.href),e=t=>{const e=(t=>{if(!t)return null;const e=t.getAttribute("href");return e?/^https?:\/\//.test(e)||null!==t.getAttribute("target")?null:e:null})(t.target.closest("a"));e&&(t.preventDefault(),u(e))};return window.addEventListener("popstate",t),document.addEventListener("click",e),()=>{window.removeEventListener("popstate",t),document.removeEventListener("click",e)}},[]),t.createElement(o.Provider,{value:[h,u]},a)};export{o as Context,h as Route,u as Switch,y as useHash,m as useParams,f as usePath,d as useQuery,c as useUrl};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "crossroad",
-  "version": "0.14.0",
-  "description": "A React library to handle navigation in your webapp. Built with simple components and React Hooks.",
+  "version": "0.16.0",
+  "description": "A React library to handle navigation in your WebApp. Built with simple components and React Hooks so your code is cleaner.",
   "homepage": "https://crossroad.page/",
   "repository": "https://github.com/franciscop/crossroad.git",
   "bugs": "https://github.com/franciscop/crossroad/issues",

package/readme.md

@@ -1,9 +1,10 @@
 # Crossroad [![npm install crossroad](https://img.shields.io/badge/npm%20install-crossroad-blue.svg "install badge")](https://www.npmjs.com/package/crossroad) [![test badge](https://github.com/franciscop/crossroad/workflows/tests/badge.svg "test badge")](https://github.com/franciscop/crossroad/blob/master/.github/workflows/tests.yml) [![gzip size](https://img.badgesize.io/franciscop/crossroad/master/index.min.js.svg?compression=gzip "gzip badge")](https://github.com/franciscop/crossroad/blob/master/index.min.js)
 
-A React library to handle navigation in your webapp. Built with simple components and React Hooks. It has [some differences](#react-router-differences) with React Router so you write cleaner code:
+A React library to handle navigation in your WebApp. Built with simple components and React Hooks so you write cleaner code:
 
-- The links are plain `<a>` instead of custom components. [Read more](#a).
-- There are useful hooks like [`useUrl`](#useurl), [`useQuery`](#usequery), etc.
+- `<Router>`, `<Switch>` and `<Route>` inspired by React Router so it's easy to get started.
+- Very useful hooks like [`useUrl`](#useurl), [`useQuery`](#usequery), etc.
+- Links are plain `<a>` instead of custom components. [Read more](#a).
 - The `<Route>` path is `exact` by default and can match query parameters.
 - It's [just ~1.5kb](https://bundlephobia.com/package/crossroad) (min+gzip) instead of the 17kb of React Router(+Dom).
 
@@ -146,6 +147,15 @@ You might want to redirect the user to a specific route (like `/notfound`) when
 </Switch>
 ```
 
+The redirect parameter can be a plain string, an url-like object or a callback that returns any of the previous:
+
+```js
+<Switch redirect="/gohere?hello=world"></Switch>
+<Switch redirect={{ path: "/gohere", query: { hello: "world" } }}></Switch>
+<Switch redirect={() => "/gohere"}></Switch>
+<Switch redirect={url => ({ ...url, path: "/gohere" })}></Switch>
+```
+
 Or to keep it in the current route, whatever it is, you can render a component with no path (no path === `*`):
 
 ```js
@@ -292,6 +302,8 @@ Some examples:
 Read and set the full URL:
 
 ```js
+import { useUrl } from "crossroad";
+
 export default function Login() {
   const [url, setUrl] = useUrl();
 
@@ -307,7 +319,6 @@ export default function Login() {
 These are the structures of each:
 
 - `url`: an object with the properties, it's similar to the native URL:
-  - `url.href`: a string with the full URL (path + query + hash)
   - `url.path`: a string with the current pathname
   - `url.query`: an object with the keys and values. Example: `{ q: 'hello' }`, `{ q: 'hello', s: 'world' }`.
   - `url.hash`: the hashtag, without the "#"
@@ -332,21 +343,35 @@ You can also set it fully or partially:
 ```js
 const [url, setUrl] = useUrl();
 
-setUrl("/#firsttime"); // [Shorthand] Redirect to home with a hashtag
-setUrl({ path: "/", hash: "firsttime" }); // Same as above
-setUrl({ ...url, path: "/" }); // Keep everything the same except the path
-setUrl({ ...url, query: { search: myQuery } }); // Set a full search query
-setUrl({ ...url, query: { ...url.query, safe: 0 } }); // Modify only one query param
+// [Shorthand] Redirect to home with a hashtag
+setUrl("/#firsttime");
+
+// Same as above, but specifying the parts
+setUrl({ path: "/", hash: "firsttime" });
+
+// Keep everything the same except the path
+setUrl({ ...url, path: "/" });
+
+// Set a full search query
+setUrl({ ...url, query: { search: "hello" } });
+
+// Modify only one query param
+setUrl({ ...url, query: { ...url.query, safe: 0 } });
 ```
 
 `useUrl()` is powerful enough for all of your needs, but you might still be interested in other hooks to simplify situations where you do e.g. heavy query manipulation with `useQuery`.
 
-By default `setUrl()` will create a new entry in the browser history. If you want to instead replace the current entry you can pass a second parameter with `{ mode: 'replace' }`:
+#### New history entry
+
+By default `setUrl()` will create a new entry in the browser history. If you want to instead replace the current url you can pass a second parameter with `{ mode: 'replace' }`:
 
 ```js
 setUrl("/newurl", { mode: "replace" });
 ```
 
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/c` and then click on the back button, the browser will go back to `/b`.
+- `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/c` and then click on the back button, it'll go back to `/a`. This is because `/c` is overwriting `/b`, instead of adding a new entry.
+
 ### `usePath()`
 
 Read and set only the path(name) part of the URL:
@@ -366,36 +391,44 @@ const Login = () => {
 
 > Note: this _only_ modifies the path(name) and keeps the search query and hash the same, so if you want to modify the full URL you should instead utilize `useUrl()` and `setUrl('/welcome')`
 
-By default `setPath()` will create a new entry in the browser history. If you want to instead replace the current entry you can pass a second parameter with `{ mode: 'replace' }`:
+#### New history entry
+
+By default `setPath()` will create a new entry in the browser history. If you want to instead replace the current url you can pass a second parameter with `{ mode: 'replace' }`:
 
 ```js
-setPath("/newurl", { mode: "replace" });
+setPath("/newpath", { mode: "replace" });
 ```
 
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/c` and then click on the back button, the browser will go back to `/b`.
+- `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/c` and then click on the back button, it'll go back to `/a`. This is because `/c` is overwriting `/b`, instead of adding a new entry.
+
 ### `useQuery()`
 
 Read and set only the search query parameters from the URL:
 
 ```js
-// In /users?search=name&filter=new
-const [query, setQuery] = useQuery();
-// { search: 'name', filter: 'new' }
+import { useQuery } from "crossroad";
 
-setQuery({ search: "myname" }); // Remove the other query params
-// Goto /users?search=myname
+export default function SearchInput() {
+  // In /users?search=
+  const [query, setQuery] = useQuery();
+  // [{ search: "" }, fn]
 
-setQuery({ ...query, search: "myname" }); // Keep the other query params
-// Goto /users?search=myname&filter=new
+  // Goes to /users?search={value}
+  const onChange = e => setQuery({ search: e.target.value });
+
+  return <input value={query.search} onChange={onChange} />;
+}
 ```
 
-If you pass a parameter, it can read and modify that parameter while keeping the others the same. This is specially useful in e.g. a search form:
+If you pass a key, it can read and modify that parameter while keeping the others the same. This is specially useful in e.g. a search form:
 
 ```js
 // In /users?search=name&filter=new
 const [search, setSearch] = useQuery("search");
 // 'name'
 
-setQuery("myname");
+setSearch("myname");
 // Goto /users?search=myname&filter=new
 ```
 
@@ -405,30 +438,49 @@ When you update it, it will clean any parameter not passed, so make sure to pass
 // In /users?search=name&filter=new
 const [query, setQuery] = useQuery();
 
-setQuery({ search: "myname" }); // Goto /users?q=myname  (removes the filter)
-setQuery({ ...query, search: "myname" }); // Goto /users?q=myname&filter=new
-setQuery(prev => ({ ...prev, search: "myname" })); // Goto /users?q=myname&filter=new
+setQuery({ search: "myname" });
+// Goto /users?q=myname  (removes the filter)
+
+setQuery({ ...query, search: "myname" });
+// Goto /users?q=myname&filter=new
+
+setQuery(prev => ({ ...prev, search: "myname" }));
+// Goto /users?q=myname&filter=new
 ```
 
 `setQuery` only modifies the query string part of the URL, keeping the `path` and `hash` the same as they were previously.
 
-By default `setQuery()` will create a new entry in the browser history. If you want to instead replace the current entry, so that the "Back" button goes to the previous page, you can pass a second parameter with `{ mode: 'replace' }`:
+When you set a search query to `null` or `false`, it will be removed from the URL. However, empty strings are not removed. So if you want empty strings to also remove the parameter in the URL, please do this:
 
 ```js
-setQuery({ search: "abc" }, { mode: "replace" });
+const [myname, setMyname] = useQuery("myname");
+
+// ...
+
+setMyname(newName || null);
 ```
 
-When you set a search query to `null` or `false`, it will be removed from the URL. However, empty strings are not removed. So if you want empty strings to also remove the parameter in the URL, please do this:
+If you are using `react-query` and already have a bunch of `useQuery()` in your code and prefer to use other name, just rename this method when importing it:
 
 ```js
-const [myname, setMyname] = useQuery("myname");
-// ...
-setWord(newName || null);
+import { useQuery as useSearch } from 'crossroad';
+...
+```
+
+#### New history entry
+
+By default `setQuery()` will create a new entry in the browser history. If you want to instead replace the current entry, so that the "Back" button goes to the previous page, you can pass a second parameter with `{ mode: 'replace' }`:
+
+```js
+setQuery({ search: "abc" }, { mode: "replace" });
 ```
 
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/b?q=c` and then click on the back button, the browser will go back to `/b`.
+- `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/b?q=c` and then click on the back button, it'll go back to `/a`. This is because `/b?q=c` is overwriting `/b`, instead of adding a new entry.
+
 ### `useHash()`
 
-Read and set only the hash part of the URL:
+Read and set only the hash part of the URL (without the `"#"`):
 
 ```js
 // In /login#welcome
@@ -445,6 +497,19 @@ By default `setHash()` will create a new entry in the browser history. If you wa
 setHash("newhash", { mode: "replace" });
 ```
 
+If you want to remove the hash, pass a `null` or `undefined` to the setter.
+
+#### New history entry
+
+By default `setHash()` will create a new entry in the browser history. If you want to instead replace the current entry, so that the "Back" button goes to the previous page, you can pass a second parameter with `{ mode: 'replace' }`:
+
+```js
+setHash("newhash", { mode: "replace" });
+```
+
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/b#c` and then click on the back button, the browser will go back to `/b`.
+- `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/b#c` and then click on the back button, it'll go back to `/a`. This is because `/b#c` is overwriting `/b`, instead of adding a new entry.
+
 ### `useParams()`
 
 Parse the current URL against the given reference:
@@ -455,6 +520,8 @@ const params = useParams("/users/:id");
 // { id: '2' }
 ```
 
+> Note: this returns a plain object, not a [value, setter] array
+
 It's not this method responsibility to match the url, just to attempt to parse it, so if there's no good match it'll just return an empty object (use a `<Route />` for path matching):
 
 ```js
@@ -592,14 +659,269 @@ In here we can see that we are treating the output of `useQuery` in the sam way
 
 ### Query routing
 
+Some times you prefer the current page to be defined by the query, instead of by the pathname. This might be true for subpages, for tabs, or for other things depending on your app. With Crossroad it's easy to manage:
+
+[**Codesandbox**](https://codesandbox.io/s/white-moon-5q0hr)
+
+https://user-images.githubusercontent.com/2801252/132944863-3caf9399-d0c1-4cdc-86a0-dca1a6a4b4d1.mp4
+
+```js
+<Switch redirect="/?page=home">
+  <Route path="/?page=home" component={Tabs.Home} />
+  <Route path="/?page=product" component={Tabs.Product} />
+  <Route path="/?page=about" component={Tabs.About} />
+</Switch>
+```
+
+With the code above, it will match the given component when the path is exactly "/" and the query parameter is the given one. If no one is matched, then it'll redirect you to `/?page=home`, the main page.
+
+You can also use this for subpages, say if you were in a Dashboard:
+
+```js
+<Switch redirect="/dashboard?tab=home">
+  <Route path="/dashboard?tab=home" component={Tabs.Home} />
+  <Route path="/dashboard?tab=product" component={Tabs.Product} />
+  <Route path="/dashboard?tab=about" component={Tabs.About} />
+</Switch>
+```
+
 ### Not found
 
+We have already seen in different examples how to do simple redirects with a single `<Switch redirect="">`, so now let's create a page for whenever the switch is not found:
+
+```js
+<Switch>
+  <Route path="/" component={Home} />
+  <Route path="/users" component={Users} />
+
+  {/* Not found page */}
+  <Route component={NotFound} />
+</Switch>
+```
+
+This page will maintain the url in the browser, but render the NotFound component. Notice how we didn't write any `path=""`, omitting the `path` is the same as writing it as `path="*"`, which will catch everything.
+
+So the way this Switch works here, it will try to match the URL against `"/"`, then against `"/users"`, and if it's none of those it'll match it against `"*"` (since that's always a match) and render the NotFound component.
+
+We can also have different not found pages. Let's say we have a specific "documentation page not found" with helpful documentation links and a general one for the rest of the website, we can manage them this way then:
+
+```js
+<Switch>
+  <Route path="/" component={Home} />
+  <Route path="/docs/abc" component={DocsAbc} />
+  <Route path="/docs/def" component={DocsDef} />
+
+  {/* Not found page only for the docs */}
+  <Route path="/docs/*" component={NotFoundDocs} />
+
+  {/* Not found page only for everything else */}
+  <Route component={NotFound} />
+</Switch>
+```
+
+In this case the order matters, because the generic NotFound will be matched with any route (since it's `"*"`), so we need to match first the docs that is not found and then, even if that fails (e.g. on the path `/hello`) we can render the generic NotFound component.
+
 ### Github hosting
 
-> NOTE: this is a bad idea for SEO, but if that doesn't matter much for you...
+> NOTE: this is a bad idea for SEO, but if that doesn't matter much for you go ahead and host your webapp in Github Pages
+
+Github pages is a bit particular in that as of this writing it does not allow for a generic redirect like most other static website servers, so we need to do a workaround with the `404.html` page.
+
+This is because any of your visitors landing on `https://example.com/` will see the proper website (since that'll be directed to `docs/index.html`), but when the user lands on other paths like `https://example.com/info` it'll not find `docs/info.html` and thus render `404.html`.
+
+So let's save the url and setup a redirect in `404.html`:
+
+```html
+<!-- 404.html -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+    <title>Redirecting...</title>
+  </head>
+  <body>
+    <script>
+      const url = JSON.stringify(location.pathname + location.search);
+      localStorage.url = url;
+      location.replace("/");
+    </script>
+  </body>
+</html>
+```
+
+Then in your index.html, or in almost anywhere else, you can overwrite the URL:
+
+```js
+if (localStorage.url) {
+  history.replaceState({}, null, JSON.decode(localStorage.url));
+  delete localStorage.url;
+}
+```
 
 ### Testing routes
 
+When testing a route, we can do it mainly in two different ways. The recommended one in general is that you pass a `url` prop straight into your `<Router>` component, which will force the Router to behave like the browser is in that route.
+
+Let's see first a very simple App example, noting that for this case we are passing the `url` from App to Router:
+
+```js
+// App.js
+import Router, { Switch, Route } from "crossroad";
+
+// Imagine these are your apps and components:
+const Home = () => <div>Home</div>;
+const Users = () => <div>Users</div>;
+const NotFound = () => <div>Website not found</div>;
+
+export default function App({ url }) {
+  return (
+    <Router url={url}>
+      <Switch>
+        <Route path="/" component={Home} />
+        <Route path="/users" component={Users} />
+        <Route component={NotFound} />
+      </Switch>
+    </Router>
+  );
+}
+```
+
+How does it work? The `url` prop will be undefined when a user loads the app (since we **don't** add it to index.js), so it is only being written for testing. On the users' browser, since it's undefinde Crossroad will use `window.location.href` instead.
+
+```js
+// App.test.js
+import React from "react";
+import $ from "react-test";
+
+import App from "./App";
+
+describe("use the url prop", () => {
+  it("renders the home component on /", () => {
+    const $home = $(<App url="/" />);
+    expect($home.text()).toBe("Home");
+  });
+
+  it("renders the user list on /users", () => {
+    const $home = $(<App url="/users" />);
+    expect($home.text()).toBe("Users");
+  });
+
+  it("renders not found when in another route", () => {
+    const $home = $(<App url="/bla" />);
+    expect($home.text()).toContain("not found");
+  });
+});
+```
+
+This method is the simplest to get started, but some people don't like having to add code to the production website only for the testing environment. That's all fine, there's another way that is a bit harder to setup but it's also more accurate to the browser's real behavior.
+
+#### Mock window.location
+
+The previous method has **a big limitation**: it doesn't allow you to navigate within your app for a test, since it's always forcing the same url. To avoid this and be able to test better the real-world behavior, use this method.
+
+When you are running Jest, it creates a fake `window` already, so you can plug into that to mock the behavior for the duration of the test. Doing it with a React component makes it even smoother:
+
+```js
+// Mock.js
+import React, { useEffect } from "react";
+
+export default function Mock({ url, children }) {
+  const href = "http://localhost:3000" + url;
+  const oldLocation = { value: window.location };
+  delete global.window.location;
+  Object.defineProperty(global.window, "location", {
+    value: new URL(href),
+    configurable: true
+  });
+
+  // Undo the setup when the component unmounts
+  useEffect(() => {
+    return () => Object.defineProperty(window, "location", oldLocation);
+  });
+  return <div>{children}</div>;
+}
+```
+
+With this Mock component, then you can wrap your normal application into working with routes:
+
+```js
+import React from "react";
+import $ from "react-test";
+
+import App from "./App";
+import Mock from "./Mock";
+
+describe("use the Mock component", () => {
+  it("renders the home component on /", () => {
+    const $home = $(
+      <Mock url="/">
+        <App />
+      </Mock>
+    );
+    expect($home.text()).toBe("Home");
+  });
+
+  it("renders the user list on /users", () => {
+    const $home = $(
+      <Mock url="/users">
+        <App />
+      </Mock>
+    );
+    expect($home.text()).toBe("Users");
+  });
+
+  it("renders not found when in another route", () => {
+    const $home = $(
+      <Mock url="/bla">
+        <App />
+      </Mock>
+    );
+    expect($home.text()).toContain("not found");
+  });
+});
+```
+
+### Server Side Render
+
+Crossroad has been tested with these libraries/frameworks for SSR:
+
+- ✅ [Razzle](https://razzlejs.org/): it works adding a bit of config; Razzle bundles React Router Dom by default, so you need to install Crossroad, remove React Router Dom and add the code mentioned below.
+- ⚠️ [Next.js](https://nextjs.org/): it works, but is generally not needed since Next.js include its own router and file-based routing.
+- ❌ [Babel-Node](https://babeljs.io/docs/en/babel-node): BabelNode [doesn't support ECMAScript modules (ESM)](https://babeljs.io/docs/en/babel-node#es6-style-module-loading-may-not-function-as-expected), but you are **also** [not supposed to use `babel-node` for production anyway](https://babeljs.io/docs/en/babel-node#not-meant-for-production-use) so this is not a real framework for SSR.
+- Others? I couldn't find many other ways that people are running SSR that I could test.
+
+For Razzle (based on [these docs FaQ](https://razzlejs.org/docs/customization#transpilation-of-external-modules)):
+
+```js
+// razzle.config.js
+module.exports = {
+  modifyWebpackOptions({ options: { webpackOptions } }) {
+    webpackOptions.notNodeExternalResMatch = req => /crossroad/.test(req);
+    webpackOptions.babelRule.include.push(/crossroad/);
+    return webpackOptions;
+  }
+};
+```
+
+When working on the server, and similar to [how we saw in testing](#testing-routes), we can overload the current url:
+
+```js
+// An express example
+const App = ({ url }) => <Router url={url}>...</Router>;
+
+app.get("/users", (req, res) => {
+  res.render(<App url="/users" />);
+});
+
+app.get("/users/:id", (req, res) => {
+  // {...} validate the `id` it here!
+
+  res.render(<App url={req.url} />);
+});
+```
+
 ## React Router diff
 
 This part of the documentation tries to explain in detail the differences between Crossroad and React Router (Dom). Crossroad goal is to build a modern Router API from scratch, removing the legacy code and using Hooks natively.
@@ -675,6 +997,12 @@ const [search, setSearch] = useQuery("search");
 setSearch("myname2");
 ```
 
+See a video and a demo of how useful and easy it is to use `useQuery()`:
+
+[**Codesandbox demo**](https://codesandbox.io/s/festive-murdock-1ctv6?file=/src/SearchForm.js)
+
+https://user-images.githubusercontent.com/2801252/132189338-e09aa220-b773-43ed-803b-fa6c7449bf44.mp4
+
 ### Plain Links
 
 To add a link in your application, you use the native `<a>` element instead of having to import a different component. What's more, this makes links a lot more consistent than in React Router. Some examples:
@@ -710,10 +1038,3 @@ The same in React Router are like this, note the inconsistencies of some times u
 <a href="https://example.com/" target="_blank">Hello</Link>
 <Link to="https://example.com/">Hello</Link>  // Broken
 ```
-
-## TODO
-
-This library is pretty much complete, but as always help with the documentation and test would be greatly appreciated. In particular:
-
-- There are some skipped tests because they are logging to the console and I haven't found a way to avoid that, see `src/index.test.js` and search for "skip".
-- More examples would be amazing.