Skip to content

Commit 0a75f47

Browse files
BioPhotonBioPhoton
committed
feat: add TypeScript plugin
1 parent 2a05a16 commit 0a75f47

18 files changed

+1019
-2
lines changed

‎code-pushup.config.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import {
55
eslintCoreConfigNx,
66
jsPackagesCoreConfig,
77
lighthouseCoreConfig,
8+
typescriptPluginConfigNx,
89
} from './code-pushup.preset.js';
910
import type { CoreConfig } from './packages/models/src/index.js';
1011
import { mergeConfigs } from './packages/utils/src/index.js';
@@ -33,10 +34,15 @@ const config: CoreConfig = {
3334

3435
export default mergeConfigs(
3536
config,
36-
await coverageCoreConfigNx(),
37+
/*await coverageCoreConfigNx(),
3738
await jsPackagesCoreConfig(),
3839
await lighthouseCoreConfig(
3940
'https://github.com/code-pushup/cli?tab=readme-ov-file#code-pushup-cli/',
4041
),
41-
await eslintCoreConfigNx(),
42+
await eslintCoreConfigNx(),*/
43+
await typescriptPluginConfigNx({
44+
tsConfigPath:
45+
'packages/plugin-typescript/mocks/fixtures/basic-setup/tsconfig.json',
46+
onlyAudits: ['noimplicitany', 'strictnullchecks'],
47+
}),
4248
);

‎code-pushup.preset.ts‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import type {
2+
Audit,
23
CategoryConfig,
4+
CategoryRef,
35
CoreConfig,
46
} from './packages/models/src/index.js';
57
import coveragePlugin, {
@@ -13,6 +15,14 @@ import jsPackagesPlugin from './packages/plugin-js-packages/src/index.js';
1315
import lighthousePlugin, {
1416
lighthouseGroupRef,
1517
} from './packages/plugin-lighthouse/src/index.js';
18+
import { typescriptPlugin } from './packages/plugin-typescript/src';
19+
import { audits as tsAudits } from './packages/plugin-typescript/src/lib/constants';
20+
import {
21+
filterAuditsByOnlyAudits,
22+
filterCategoryRefsByOnlyAudits,
23+
filterDiagnisticsByOnlyAudits,
24+
} from './packages/plugin-typescript/src/lib/runner/runner';
25+
import { TypescriptPluginOptions } from './packages/plugin-typescript/src/lib/typescript-plugin';
1626

1727
export const jsPackagesCategories: CategoryConfig[] = [
1828
{
@@ -129,6 +139,33 @@ export const eslintCoreConfigNx = async (
129139
};
130140
};
131141

142+
export const typescriptPluginConfigNx = async (
143+
options: TypescriptPluginOptions,
144+
): Promise<CoreConfig> => {
145+
const supportedAuditSlugs = tsAudits
146+
.filter(filterAuditsByOnlyAudits(options.onlyAudits))
147+
.map(({ slug }) => slug);
148+
149+
return {
150+
plugins: [await typescriptPlugin(options)],
151+
/*...(supportedAuditSlugs.length > 0 ? {
152+
categories: [
153+
{
154+
slug: 'typescript',
155+
title: 'Typescript',
156+
refs: supportedAuditSlugs
157+
.map(({slug}) => ({
158+
plugin: 'typescript',
159+
type: 'audit' as const,
160+
slug,
161+
weight: 1
162+
}))
163+
}
164+
]
165+
} : {})*/
166+
};
167+
};
168+
132169
export const coverageCoreConfigNx = async (
133170
projectName?: string,
134171
): Promise<CoreConfig> => {

‎packages/plugin-typescript/README.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# @code-pushup/typescript-plugin
2+
3+
[![npm](https://img.shields.io/npm/v/%40code-pushup%2Ftypescript-plugin.svg)](https://www.npmjs.com/package/@code-pushup/typescript-plugin)
4+
[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Ftypescript-plugin)](https://npmtrends.com/@code-pushup/typescript-plugin)
5+
[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/typescript-plugin)](https://www.npmjs.com/package/@code-pushup/typescript-plugin?activeTab=dependencies)
6+
7+
🕵️ **Code PushUp plugin for measuring web performance and quality with Lighthouse.** 🔥
8+
9+
---
10+
11+
The plugin parses your Lighthouse configuration and lints all audits of the official [Lighthouse](https://github.com/GoogleChrome/typescript/blob/main/readme.md#typescript-------) CLI.
12+
13+
Detected Lighthouse audits are mapped to Code PushUp audits. Audit reports are calculated based on the [original implementation](https://googlechrome.github.io/typescript/scorecalc/).
14+
Additionally, Lighthouse categories are mapped to Code PushUp groups which can make it easier to assemble the categories.
15+
16+
For more infos visit the [official docs](https://developer.chrome.com/docs/typescript/overview).
17+
18+
## Getting started
19+
20+
1. If you haven't already, install [@code-pushup/cli](../cli/README.md) and create a configuration file.
21+
22+
2. Install as a dev dependency with your package manager:
23+
24+
```sh
25+
npm install --save-dev @code-pushup/typescript-plugin
26+
```
27+
28+
```sh
29+
yarn add --dev @code-pushup/typescript-plugin
30+
```
31+
32+
```sh
33+
pnpm add --save-dev @code-pushup/typescript-plugin
34+
```
35+
36+
3. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.ts`).
37+
38+
Pass in the URL you want to measure, along with optional [flags](#flags) and [config](#config) data.
39+
40+
```ts
41+
import typescriptPlugin from '@code-pushup/typescript-plugin';
42+
43+
export default {
44+
// ...
45+
plugins: [
46+
// ...
47+
await typescriptPlugin('https://example.com'),
48+
],
49+
};
50+
```
51+
52+
4. Run the CLI with `npx code-pushup collect` and view or upload the report (refer to [CLI docs](../cli/README.md)).
53+
54+
### Optionally set up categories
55+
56+
Reference audits (or groups) which you wish to include in custom categories (use `npx code-pushup print-config --onlyPlugins=typescript` to list audits and groups).
57+
58+
Assign weights based on what influence each Lighthouse audit has on the overall category score (assign weight 0 to only include as extra info, without influencing category score).
59+
The plugin exports the helper `typescriptAuditRef` and `typescriptGroupRef` to reference Lighthouse category references for audits and groups.
60+
61+
#### Reference audits directly with `typescriptGroupRef`
62+
63+
```ts
64+
import { typescriptGroupRef } from './utils';
65+
66+
export default {
67+
// ...
68+
categories: [
69+
{
70+
slug: 'performance',
71+
title: 'Performance',
72+
refs: [typescriptGroupRef('performance')],
73+
},
74+
{
75+
slug: 'a11y',
76+
title: 'Accessibility',
77+
refs: [typescriptGroupRef('accessibility')],
78+
},
79+
{
80+
slug: 'best-practices',
81+
title: 'Best Practices',
82+
refs: [typescriptGroupRef('best-practices')],
83+
},
84+
{
85+
slug: 'seo',
86+
title: 'SEO',
87+
refs: [typescriptGroupRef('seo')],
88+
},
89+
{
90+
slug: 'pwa',
91+
title: 'PWA',
92+
isBinary: true,
93+
refs: [typescriptGroupRef('pwa')],
94+
},
95+
],
96+
};
97+
```
98+
99+
#### Reference groups with `typescriptAuditRef`
100+
101+
The Lighthouse categories are reflected as groups.
102+
Referencing individual audits offers more granularity. However, keep maintenance costs of a higher number of audits in mind as well.
103+
104+
```ts
105+
import { typescriptAuditRef } from './utils';
106+
107+
export default {
108+
// ...
109+
categories: [
110+
{
111+
slug: 'pwa',
112+
title: 'PWA',
113+
isBinary: true,
114+
refs: [typescriptAuditRef('installable-manifest', 2), typescriptAuditRef('splash-screen', 1), typescriptAuditRef('themed-omnibox', 1), typescriptAuditRef('content-width', 1), typescriptAuditRef('themed-omnibox', 2), typescriptAuditRef('viewport', 2), typescriptAuditRef('maskable-icon', 1), typescriptAuditRef('pwa-cross-browser', 0), typescriptAuditRef('pwa-page-transitions', 0), typescriptAuditRef('pwa-each-page-has-url', 0)],
115+
},
116+
],
117+
};
118+
```
119+
120+
## Flags
121+
122+
The plugin accepts an optional second argument, `flags`.
123+
124+
`flags` is a JavaScript object containing Lighthouse [CLI flags](https://github.com/GoogleChrome/typescript/blob/7d80178c37a1b600ea8f092fc0b098029799a659/cli/cli-flags.js#L80).
125+
126+
Within the `flags` object, external configuration files can be referenced using options like `configPath` , `preset`, or `budgetPath`. These options allow Lighthouse to load custom configurations, audit presets, or performance budgets from external `json` or JavaScript files.
127+
128+
For a complete list of available options, refer to [the official Lighthouse documentation](https://github.com/GoogleChrome/typescript/blob/main/readme.md#cli-options).
129+
130+
> [!TIP]
131+
> If you are new to working with the Lighthouse CLI, flags can be passed like this:
132+
> `typescript https://example.com --output=json --chromeFlags='--headless=shell'`
133+
>
134+
> With the plugin, the configuration would be:
135+
>
136+
> ```ts
137+
> // code-pushup.config.ts
138+
> ...
139+
> typescriptPlugin('https://example.com', {
140+
> output: 'json',
141+
> chromeFlags: ['--headless=shell'],
142+
> });
143+
> ```
144+
145+
> [!note]
146+
> The following flags are **not supported** in the current implementation:
147+
>
148+
> - `list-all-audits` - Prints a list of all available audits and exits. Alternative: `npx code-pushup print-config --onlyPlugins typescript`
149+
> - `list-locales` - Prints a list of all supported locales and exits.
150+
> - `list-trace-categories` - Prints a list of all required trace categories and exits.
151+
> - `view` - Open HTML report in your browser
152+
153+
## Chrome Flags for Tooling
154+
155+
We recommend using Chrome flags for more stable runs in a tooling environment. The [`chrome-launcher`](https://www.npmjs.com/package/chrome-launcher) package offers a well-documented set of flags specifically designed to ensure reliable execution.
156+
157+
The latest version of `@code-pushup/typescript-plugin` provides `DEFAULT_CHROME_FLAGS`, a pre-configured constant that includes Chrome’s default flags for stable, headless execution out of the box. This means you do not need to specify `chromeFlags` manually unless you want to modify them.
158+
159+
### Default Usage
160+
161+
If no `chromeFlags` are provided, the plugin automatically applies the default configuration:
162+
163+
> ```ts
164+
> import typescriptPlugin from '@code-pushup/typescript-plugin';
165+
>
166+
> typescriptPlugin('https://example.com', {
167+
> output: 'json',
168+
> // Defaults to DEFAULT_CHROME_FLAGS internally
169+
> });
170+
> ```
171+
172+
### Adding Extra Flags
173+
174+
If additional Chrome flags are required (e.g., verbose logging or debugging), they can be appended to the default flags:
175+
176+
> ```ts
177+
> import typescriptPlugin, { DEFAULT_CHROME_FLAGS } from '@code-pushup/typescript-plugin';
178+
>
179+
> typescriptPlugin('https://example.com', {
180+
> output: 'json',
181+
> chromeFlags: DEFAULT_CHROME_FLAGS.concat(['--verbose']),
182+
> });
183+
> ```
184+
185+
### Overriding Default Flags
186+
187+
To completely override the default flags and provide a custom configuration:
188+
189+
> ```ts
190+
> import typescriptPlugin from '@code-pushup/typescript-plugin';
191+
>
192+
> typescriptPlugin('https://example.com', {
193+
> output: 'json',
194+
> chromeFlags: ['--verbose'],
195+
> });
196+
> ```
197+
198+
## Config
199+
200+
The plugin accepts a third optional argument, `config`.
201+
202+
`config` is the Lighthouse [configuration](https://github.com/GoogleChrome/typescript/blob/7d80178c37a1b600ea8f092fc0b098029799a659/types/config.d.ts#L21) as a JS object.
203+
204+
For a complete guide on Lighthouse configuration read the [official documentation on configuring](https://github.com/GoogleChrome/typescript/blob/main/docs/configuration.md)
205+
206+
> [!TIP]
207+
> If you are not used to work with the Lighthouse CLI you would pass a config like this:
208+
> `typescript --config-path=path/to/custom-config.js https://example.com`
209+
>
210+
> And in a separate file you would place the following object:
211+
>
212+
> ```typescript
213+
> // custom-config.js file
214+
> export default {
215+
> extends: 'typescript:default',
216+
> settings: {
217+
> onlyAudits: ['first-meaningful-paint', 'speed-index', 'interactive'],
218+
> },
219+
> };
220+
> ```
221+
>
222+
> Now with the plugin it would look like this:
223+
>
224+
> ```ts
225+
> // code-pushup.config.ts
226+
> ...
227+
> typescriptPlugin('https://example.com', undefined, {
228+
> extends: 'typescript:default',
229+
> settings: {
230+
> onlyAudits: [
231+
> 'first-meaningful-paint',
232+
> 'speed-index',
233+
> 'interactive',
234+
> ],
235+
> }
236+
> })
237+
> ```
238+
239+
If you want to contribute, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md).

‎packages/plugin-typescript/eslint.config.js‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import tseslint from 'typescript-eslint';
2+
import baseConfig from '../../eslint.config.js';
3+
4+
export default tseslint.config(
5+
...baseConfig,
6+
{
7+
files: ['**/*.ts'],
8+
languageOptions: {
9+
parserOptions: {
10+
projectService: true,
11+
tsconfigRootDir: import.meta.dirname,
12+
},
13+
},
14+
},
15+
{
16+
files: ['**/*.json'],
17+
rules: {
18+
'@nx/dependency-checks': 'error',
19+
},
20+
},
21+
);

0 commit comments

Comments
 (0)