|
| 1 | +--- |
| 2 | +description: How the Docusaurus client is structured |
| 3 | +--- |
| 4 | + |
| 5 | +# Client architecture |
| 6 | + |
| 7 | +## Theme aliases {/* #theme-aliases */} |
| 8 | + |
| 9 | +A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias: |
| 10 | + |
| 11 | +```js |
| 12 | +import Navbar from '@theme/Navbar'; |
| 13 | +``` |
| 14 | + |
| 15 | +The alias `@theme` can refer to a few directories, in the following priority: |
| 16 | + |
| 17 | +1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence. |
| 18 | +2. A Docusaurus theme package's `theme` directory. |
| 19 | +3. Fallback components provided by Docusaurus core (usually not needed). |
| 20 | + |
| 21 | +This is called a _layered architecture_: a higher-priority layer providing the component would shadow a lower-priority layer, making swizzling possible. Given the following structure: |
| 22 | + |
| 23 | +``` |
| 24 | +website |
| 25 | +├── node_modules |
| 26 | +│ └── @docusaurus/theme-classic |
| 27 | +│ └── theme |
| 28 | +│ └── Navbar.js |
| 29 | +└── src |
| 30 | + └── theme |
| 31 | + └── Navbar.js |
| 32 | +``` |
| 33 | + |
| 34 | +`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. If you are familiar with Objective C where a function's implementation can be swapped during runtime, it's the exact same concept here with changing the target `@theme/Navbar` is pointing to! |
| 35 | + |
| 36 | +We already talked about how the "userland theme" in `src/theme` can re-use a theme component through the [`@theme-original`](../swizzling.mdx#wrapping) alias. One theme package can also wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import. |
| 37 | + |
| 38 | +Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature. |
| 39 | + |
| 40 | +```js |
| 41 | +import InitialCodeBlock from '@theme-init/CodeBlock'; |
| 42 | +import React from 'react'; |
| 43 | + |
| 44 | +export default function CodeBlock(props) { |
| 45 | + return props.live ? ( |
| 46 | + <ReactLivePlayground {...props} /> |
| 47 | + ) : ( |
| 48 | + <InitialCodeBlock {...props} /> |
| 49 | + ); |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +Check the code of `@docusaurus/theme-live-codeblock` for details. |
| 54 | + |
| 55 | +:::warning |
| 56 | + |
| 57 | +Unless you want to publish a re-usable "theme enhancer" (like `@docusaurus/theme-live-codeblock`), you likely don't need `@theme-init`. |
| 58 | + |
| 59 | +::: |
| 60 | + |
| 61 | +It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup with three themes/plugins and the site itself all trying to define the same component. Internally, Docusaurus loads these themes as a "stack". |
| 62 | + |
| 63 | +```text |
| 64 | ++-------------------------------------------------+ |
| 65 | +| `website/src/theme/CodeBlock.js` | <-- `@theme/CodeBlock` always points to the top |
| 66 | ++-------------------------------------------------+ |
| 67 | +| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component |
| 68 | ++-------------------------------------------------+ |
| 69 | +| `plugin-awesome-codeblock/theme/CodeBlock.js` | |
| 70 | ++-------------------------------------------------+ |
| 71 | +| `theme-classic/theme/CodeBlock/index.js` | <-- `@theme-init/CodeBlock` always points to the bottom |
| 72 | ++-------------------------------------------------+ |
| 73 | +``` |
| 74 | + |
| 75 | +The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last. |
| 76 | + |
| 77 | +`@theme/*` always points to the topmost component—when `CodeBlock` is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version. |
| 78 | + |
| 79 | +`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import. |
| 80 | + |
| 81 | +`@theme-init/*` always points to the bottommost component—usually, this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases! |
| 82 | + |
| 83 | +## Client modules {/* #client-modules */} |
| 84 | + |
| 85 | +Client modules are part of your site's bundle, just like theme components. However, they are usually side-effect-ful. Client modules are anything that can be `import`ed by Webpack—CSS, JS, etc. JS scripts usually work on the global context, like registering event listeners, creating global variables... |
| 86 | + |
| 87 | +These modules are imported globally before React even renders the initial UI. |
| 88 | + |
| 89 | +```js title="@docusaurus/core/App.tsx" |
| 90 | +// How it works under the hood |
| 91 | +import '@generated/client-modules'; |
| 92 | +``` |
| 93 | + |
| 94 | +Plugins and sites can both declare client modules, through [`getClientModules`](../api/plugin-methods/lifecycle-apis.mdx#getClientModules) and [`siteConfig.clientModules`](../api/docusaurus.config.js.mdx#clientModules), respectively. |
| 95 | + |
| 96 | +Client modules are called during server-side rendering as well, so remember to check the [execution environment](./ssg.mdx#escape-hatches) before accessing client-side globals. |
| 97 | + |
| 98 | +```js title="mySiteGlobalJs.js" |
| 99 | +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; |
| 100 | + |
| 101 | +if (ExecutionEnvironment.canUseDOM) { |
| 102 | + // As soon as the site loads in the browser, register a global event listener |
| 103 | + window.addEventListener('keydown', (e) => { |
| 104 | + if (e.code === 'Period') { |
| 105 | + location.assign(location.href.replace('.com', '.dev')); |
| 106 | + } |
| 107 | + }); |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +CSS stylesheets imported as client modules are [global](../styling-layout.mdx#global-styles). |
| 112 | + |
| 113 | +```css title="mySiteGlobalCss.css" |
| 114 | +/* This stylesheet is global. */ |
| 115 | +.globalSelector { |
| 116 | + color: red; |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +### Client module lifecycles {/* #client-module-lifecycles */} |
| 121 | + |
| 122 | +Besides introducing side-effects, client modules can optionally export two lifecycle functions: `onRouteUpdate` and `onRouteDidUpdate`. |
| 123 | + |
| 124 | +Because Docusaurus builds a single-page application, `script` tags will only be executed the first time the page loads, but will not re-execute on page transitions. These lifecycles are useful if you have some imperative JS logic that should execute every time a new page has loaded, e.g., to manipulate DOM elements, to send analytics data, etc. |
| 125 | + |
| 126 | +For every route transition, there will be several important timings: |
| 127 | + |
| 128 | +1. The user clicks a link, which causes the router to change its current location. |
| 129 | +2. Docusaurus preloads the next route's assets, while keeping displaying the current page's content. |
| 130 | +3. The next route's assets have loaded. |
| 131 | +4. The new location's route component gets rendered to DOM. |
| 132 | + |
| 133 | +`onRouteUpdate` will be called at event (2), and `onRouteDidUpdate` will be called at (4). They both receive the current location and the previous location (which can be `null`, if this is the first screen). |
| 134 | + |
| 135 | +`onRouteUpdate` can optionally return a "cleanup" callback, which will be called at (3). For example, if you want to display a progress bar, you can start a timeout in `onRouteUpdate`, and clear the timeout in the callback. (The classic theme already provides an `nprogress` integration this way.) |
| 136 | + |
| 137 | +Note that the new page's DOM is only available during event (4). If you need to manipulate the new page's DOM, you'll likely want to use `onRouteDidUpdate`, which will be fired as soon as the DOM on the new page has mounted. |
| 138 | + |
| 139 | +```js title="myClientModule.js" |
| 140 | +export function onRouteDidUpdate({location, previousLocation}) { |
| 141 | + // Don't execute if we are still on the same page; the lifecycle may be fired |
| 142 | + // because the hash changes (e.g. when navigating between headings) |
| 143 | + if (location.pathname !== previousLocation?.pathname) { |
| 144 | + const title = document.getElementsByTagName('h1')[0]; |
| 145 | + if (title) { |
| 146 | + title.innerText += '❤️'; |
| 147 | + } |
| 148 | + } |
| 149 | +} |
| 150 | + |
| 151 | +export function onRouteUpdate({location, previousLocation}) { |
| 152 | + if (location.pathname !== previousLocation?.pathname) { |
| 153 | + const progressBarTimeout = window.setTimeout(() => { |
| 154 | + nprogress.start(); |
| 155 | + }, delay); |
| 156 | + return () => window.clearTimeout(progressBarTimeout); |
| 157 | + } |
| 158 | + return undefined; |
| 159 | +} |
| 160 | +``` |
| 161 | +
|
| 162 | +Or, if you are using TypeScript and you want to leverage contextual typing: |
| 163 | +
|
| 164 | +```ts title="myClientModule.ts" |
| 165 | +import type {ClientModule} from '@docusaurus/types'; |
| 166 | + |
| 167 | +const module: ClientModule = { |
| 168 | + onRouteUpdate({location, previousLocation}) { |
| 169 | + // ... |
| 170 | + }, |
| 171 | + onRouteDidUpdate({location, previousLocation}) { |
| 172 | + // ... |
| 173 | + }, |
| 174 | +}; |
| 175 | +export default module; |
| 176 | +``` |
| 177 | +
|
| 178 | +Both lifecycles will fire on first render, but they will not fire on server-side, so you can safely access browser globals in them. |
| 179 | +
|
| 180 | +:::tip Prefer using React |
| 181 | +
|
| 182 | +Client module lifecycles are purely imperative, and you can't use React hooks or access React contexts within them. If your operations are state-driven or involve complicated DOM manipulations, you should consider [swizzling components](../swizzling.mdx) instead. |
| 183 | +
|
| 184 | +::: |
0 commit comments