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.

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(plugin-vercel-analytics): add new vercel analytics plugin #9687

Merged
merged 23 commits into from
Feb 14, 2024
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
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
3 changes: 3 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/.npmignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.tsbuildinfo*
tsconfig*
__tests__
7 changes: 7 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# `@docusaurus/plugin-vercel-analytics`

[Vercel analytics](https://vercel.com/docs/analytics) plugin for Docusaurus.

## Usage

See [plugin-vercel-analytics documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-vercel-analytics).
35 changes: 35 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"name": "@docusaurus/plugin-vercel-analytics",
"version": "3.0.0",
"description": "Global vercel analytics plugin for Docusaurus.",
"main": "lib/index.js",
"types": "lib/index.d.ts",
"publishConfig": {
"access": "public"
},
"scripts": {
"build": "tsc --build",
"watch": "tsc --build --watch"
},
"repository": {
"type": "git",
"url": "https://github.com/facebook/docusaurus.git",
"directory": "packages/docusaurus-plugin-vercel-analytics"
},
"license": "MIT",
"dependencies": {
"@docusaurus/core": "3.0.0",
"@docusaurus/types": "3.0.0",
"@docusaurus/utils-validation": "3.0.0",
"@docusaurus/utils": "3.0.0",
"@vercel/analytics": "^1.1.1",
"tslib": "^2.6.0"
},
"peerDependencies": {
"react": "^18.0.0",
"react-dom": "^18.0.0"
},
"engines": {
"node": ">=18.0"
}
}
17 changes: 17 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/src/analytics.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
/**
* 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 {inject} from '@vercel/analytics';
import globalData from '@generated/globalData';
import type {PluginOptions} from '@docusaurus/plugin-vercel-analytics';

const {debug, mode} = globalData['docusaurus-plugin-vercel-analytics']
?.default as PluginOptions;

slorber marked this conversation as resolved.
Show resolved Hide resolved
inject({
mode,
debug,
});
39 changes: 39 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/src/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/**
* 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 {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
import type {LoadContext, Plugin} from '@docusaurus/types';
import type {PluginOptions, Options} from './options';

export default function pluginVercelAnalytics(
context: LoadContext,
options: PluginOptions,
): Plugin {
if (options.id !== DEFAULT_PLUGIN_ID) {
throw new Error(
`You cannot use a custom plugin id option with the Vercel Analytics plugin`,
);
}

const isProd = process.env.NODE_ENV === 'production';

return {
name: 'docusaurus-plugin-vercel-analytics',

getClientModules() {
return isProd ? ['./analytics'] : [];
},

contentLoaded({actions}) {
actions.setGlobalData(options);
},
};
}

export {validateOptions} from './options';

export type {PluginOptions, Options};
35 changes: 35 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/src/options.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
/**
* 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 {Joi} from '@docusaurus/utils-validation';
import type {OptionValidationContext} from '@docusaurus/types';

export type PluginOptions = {
id: string;
mode: 'auto' | 'production' | 'development';
debug: boolean;
};

export type Options = Partial<PluginOptions>;

export const DEFAULT_OPTIONS: Partial<PluginOptions> = {
mode: 'production',
Copy link
Collaborator

Choose a reason for hiding this comment

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

I think undefined ("auto") makes more sense as a default

For example docusaurus build --dev builds the site with node env "development" and we probably want it to impact the vercel plugin env in that case.

See also:

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I don't understand what you mean with undefined ("auto") but I changed the default value to auto which makes more sense

debug: false,
Copy link
Collaborator

Choose a reason for hiding this comment

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

Also use undefined?

https://vercel.com/docs/analytics/package#debug

This option is automatically enabled if the NODE_ENV environment variable is available and either development or test.

Similarly I think using docusaurus build --dev should turn this plugin to debug mode

Copy link
Contributor Author

@OzakIOne OzakIOne Feb 12, 2024

Choose a reason for hiding this comment

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

Same, didn't understand the use of undefined however modified according to your comment

};

const pluginOptionsSchema = Joi.object<PluginOptions>({
mode: Joi.string()
.valid('auto', 'production', 'development')
.default(DEFAULT_OPTIONS.mode),
debug: Joi.boolean().default(DEFAULT_OPTIONS.debug),
});

export function validateOptions({
validate,
options,
}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
return validate(pluginOptionsSchema, options);
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
/**
* 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.
*/

declare module '@docusaurus/plugin-vercel-analytics' {
OzakIOne marked this conversation as resolved.
Show resolved Hide resolved
export type PluginOptions = {
/**
* Turn debug mode on
*/
debug?: boolean;
/**
* TODO add description
*/
mode: 'auto' | 'development' | 'production';
};

export type Options = Partial<PluginOptions>;
}
8 changes: 8 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/src/types.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
/**
* 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.
*/

/// <reference types="@docusaurus/module-type-aliases" />
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"noEmit": false,
"composite": true,
"incremental": true,
"tsBuildInfoFile": "./lib/.tsbuildinfo-client",
"moduleResolution": "bundler",
"module": "esnext",
"target": "esnext",
"rootDir": "src",
"outDir": "lib"
},
"include": ["src/analytics.ts", "src/*.d.ts"],
"exclude": ["**/__tests__/**"]
}
13 changes: 13 additions & 0 deletions packages/docusaurus-plugin-vercel-analytics/tsconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"extends": "../../tsconfig.json",
"references": [{"path": "./tsconfig.client.json"}],
"compilerOptions": {
"noEmit": false,
"incremental": true,
"tsBuildInfoFile": "./lib/.tsbuildinfo",
"rootDir": "src",
"outDir": "lib"
},
"include": ["src"],
"exclude": ["src/analytics.ts", "**/__tests__/**"]
}
57 changes: 57 additions & 0 deletions website/docs/api/plugins/plugin-vercel-analytics.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
sidebar_position: 11
slug: /api/plugins/@docusaurus/plugin-vercel-analytics
---

# 📦 plugin-vercel-analytics

import APITable from '@site/src/components/APITable';

[Vercel Analytics](https://vercel.com/docs/analytics) provides comprehensive insights into your website's visitors, tracking top pages, referrers, and demographics like location, operating systems, and browser info.

:::warning production only

This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics.

:::

## Installation {#installation}

```bash npm2yarn
npm install --save @docusaurus/plugin-vercel-analytics
```

## Configuration {#configuration}

Accepted fields:

```mdx-code-block
<APITable>
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | string | 'production' | Sets the environment mode ('auto' or 'development' or 'production') |
| `debug` | `boolean` | `false` | Enable debug logging |
OzakIOne marked this conversation as resolved.
Show resolved Hide resolved

```mdx-code-block
</APITable>
```

### Example configuration {#ex-config}

You can configure this plugin through plugin options.

```js title="docusaurus.config.js"
export default {
plugins: [
[
'vercel-analytics',
{
debug: true,
mode: 'auto',
},
],
],
};
```
12 changes: 12 additions & 0 deletions yarn.lock
Original file line number Diff line number Diff line change
Expand Up @@ -3863,6 +3863,13 @@
resolved "https://registry.yarnpkg.com/@ungap/structured-clone/-/structured-clone-1.2.0.tgz#756641adb587851b5ccb3e095daf27ae581c8406"
integrity sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==

"@vercel/analytics@^1.1.1":
version "1.1.1"
resolved "https://registry.yarnpkg.com/@vercel/analytics/-/analytics-1.1.1.tgz#2a712378a95014a548b4f9d2ae1ea0721433908d"
integrity sha512-+NqgNmSabg3IFfxYhrWCfB/H+RCUOCR5ExRudNG2+pcRehq628DJB5e1u1xqwpLtn4pAYii4D98w7kofORAGQA==
dependencies:
server-only "^0.0.1"

"@webassemblyjs/ast@1.11.6", "@webassemblyjs/ast@^1.11.5":
version "1.11.6"
resolved "https://registry.yarnpkg.com/@webassemblyjs/ast/-/ast-1.11.6.tgz#db046555d3c413f8966ca50a95176a0e2c642e24"
Expand Down Expand Up @@ -14718,6 +14725,11 @@ serve-static@1.15.0:
parseurl "~1.3.3"
send "0.18.0"

server-only@^0.0.1:
version "0.0.1"
resolved "https://registry.yarnpkg.com/server-only/-/server-only-0.0.1.tgz#0f366bb6afb618c37c9255a314535dc412cd1c9e"
integrity sha512-qepMx2JxAa5jjfzxG79yPPq+8BuFToHd1hm7kI+Z4zAq1ftQiP7HcxMhDDItrbtwVeLg/cY2JnKnrcFkmiswNA==

set-blocking@^2.0.0:
version "2.0.0"
resolved "https://registry.yarnpkg.com/set-blocking/-/set-blocking-2.0.0.tgz#045f9782d011ae9a6803ddd382b24392b3d890f7"
Expand Down
Loading