Skip to content

Commit

Permalink
feat(v2): site client modules (#3545)
Browse files Browse the repository at this point in the history
* site client modules

* Update website/docs/api/docusaurus.config.js.md

Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>

Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>
  • Loading branch information
slorber and lex111 authored Oct 7, 2020
1 parent 9ba28a3 commit 5b79f2e
Show file tree
Hide file tree
Showing 8 changed files with 52 additions and 7 deletions.
1 change: 1 addition & 0 deletions packages/docusaurus-types/src/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ export interface DocusaurusConfig {
[key: string]: unknown;
}
)[];
clientModules?: string[];
ssrTemplate?: string;
stylesheets?: (
| string
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,11 @@ function dispatchLifecycleAction(
...args: any[]
) {
clientModules.forEach((clientModule) => {
const mod = clientModule.__esModule ? clientModule.default : clientModule;
if (mod && mod[lifecycleAction]) {
mod[lifecycleAction](...args);
const lifecycleFunction =
clientModule?.default?.[lifecycleAction] ?? clientModule[lifecycleAction];

if (lifecycleFunction) {
lifecycleFunction(...args);
}
});
}
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus/src/server/configValidation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ const ConfigSchema = Joi.object({
type: Joi.string().required(),
}).unknown(),
),
clientModules: Joi.array().items(Joi.string()),
tagline: Joi.string().allow(''),
titleDelimiter: Joi.string().default('|'),
});
Expand Down
9 changes: 8 additions & 1 deletion packages/docusaurus/src/server/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -104,11 +104,18 @@ export async function load(
// Make a fake plugin to:
// - Resolve aliased theme components
// - Inject scripts/stylesheets
const {stylesheets = [], scripts = []} = siteConfig;
const {
stylesheets = [],
scripts = [],
clientModules: siteConfigClientModules = [],
} = siteConfig;
plugins.push({
name: 'docusaurus-bootstrap-plugin',
options: {},
version: {type: 'synthetic'},
getClientModules() {
return siteConfigClientModules;
},
configureWebpack: () => ({
resolve: {
alias,
Expand Down
17 changes: 17 additions & 0 deletions website/docs/api/docusaurus.config.js.md
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,23 @@ module.exports = {
};
```

### `clientModules`

An array of client modules to load globally on your site:

Example:

```js title="docusaurus.config.js"
module.exports = {
clientModules: [
require.resolve('./mySiteGlobalJs.js'),
require.resolve('./mySiteGlobalCss.css'),
],
};
```

See also: [`getClientModules()`](lifecycle-apis.md#getclientmodules).

### `ssrTemplate`

An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview) that will be used to render your application. This can be used to set custom attributes on the `body` tags, additional `meta` tags, customize the `viewport`, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from `upstream`.
Expand Down
6 changes: 3 additions & 3 deletions website/docs/lifecycle-apis.md
Original file line number Diff line number Diff line change
Expand Up @@ -531,17 +531,17 @@ module.exports.getSwizzleComponentList = () => swizzleAllowedComponents;

Returns an array of paths to the modules that are to be imported in the client bundle. These modules are imported globally before React even renders the initial UI.

As an example, to make your theme load a `customCss` object from `options` passed in by the user:
As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user:

```js {7-9} title="my-theme/src/index.js"
const path = require('path');

module.exports = function (context, options) {
const {customCss} = options || {};
const {customCss, customJs} = options || {};
return {
name: 'name-of-my-theme',
getClientModules() {
return [customCss];
return [customCss, customJs];
},
};
};
Expand Down
1 change: 1 addition & 0 deletions website/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ module.exports = {
description:
'An optimized site generator in React. Docusaurus helps you to move fast and write content. Build documentation websites, blogs, marketing pages, and more.',
},
clientModules: [require.resolve('./dogfooding/clientModuleExample.ts')],
themes: ['@docusaurus/theme-live-codeblock'],
plugins: [
[
Expand Down
16 changes: 16 additions & 0 deletions website/dogfooding/clientModuleExample.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
/**
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

export function onRouteUpdate({location}: {location: Location}) {
console.log('onRouteUpdate', {location});
}

if (ExecutionEnvironment.canUseDOM) {
console.log('client module example log');
}

0 comments on commit 5b79f2e

Please sign in to comment.