Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(v2): site client modules #3545

Merged
merged 2 commits into from
Oct 7, 2020
Merged

feat(v2): site client modules #3545

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef363c3
site client modules
slorber Oct 6, 2020
2f835d6
Update website/docs/api/docusaurus.config.js.md
slorber Oct 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/docusaurus-types/src/index.d.ts
View file
Open in desktop
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
8 changes: 5 additions & 3 deletions packages/docusaurus/src/client/client-lifecycles-dispatcher.ts
View file
Open in desktop
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 =
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not familiar with this code, but surely removing the clientModule.__esModule won't affect it in any way? It was kind of related to Yarn 2 support (not sure)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a behavior change that shouldn't break anything, but allows you to write client lifecycle methods as named exports.

Before we had to use this syntax to add the lifecycle to default expor

export default {
    onRouteUpdate({location}) {
      console.log('onRouteUpdate', {location});
    },
};

Now we can also write the following:

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

Note it's not a documented feature (yet) and kind of broken, so I plan to improve this as part of #3399

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW both versions still work, and it's the default export that is picked in priority if both are used, so it should be retrocompatible in all cases even if it's not very likely that such code exist in userland

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

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the explanation, so this is safe for merge.

clientModule?.default?.[lifecycleAction] ?? clientModule[lifecycleAction];

if (lifecycleFunction) {
lifecycleFunction(...args);
}
});
}
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus/src/server/configValidation.ts
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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');
}