Skip to content

BUILD.md

Latest commit

 

History

History
114 lines (65 loc) · 6.1 KB

BUILD.md

File metadata and controls

114 lines (65 loc) · 6.1 KB
Raw

Build Considerations: Project Root

package.json

Dependencies (dev and otherwise)

eslint-plugin-react-x

Used by Oxlint (via jsPlugins) to enforce React hooks rules (react-x/rules-of-hooks, react-x/exhaustive-deps). Oxlint does not have a native implementation of hooks rules and delegates to this ESLint plugin.

typescript

In the project root, typescript is used to bolster the linting of TypeScript files. tsc catches quite a few issues that ESLint does not pick up on.

In ./packages/plexus, typescript is used to generate type declarations for the ES module build. See ./packages/plexus/BUILD.md for details.

Scripts

build

pnpm run build executes the build in each of ./packages/* sub-packages.

oxlint

Runs Oxlint (via vp lint) on all packages and scripts. Oxlint is the linting component of Vite+; it replaces ESLint.

lint

This is an amalgamation of linting scripts that run to make sure things are all-good. It's run in CI and as part of a pre-commit hook.

  • fmt-lint
  • tsc-lint
  • oxlint
  • check-license
  • check-copyright-year
  • check-tsx-naming
  • check-overrides
  • knip

prepare

Runs after the top-level pnpm install. Sets up husky pre-commit hooks.

fmt, fmt-lint

fmt formats the code using Oxfmt (via vp fmt).

fmt-lint checks formatting without writing changes. If any files would be reformatted, the program exits with a non-zero code. This blocks CI and pre-commits.

tsc-lint, tsc-lint-debug

tsc is run with the --noEmit option to bolster linting of TypeScript files. See TypeScript, above.

tsc-lint-debug is for diagnosing problems with linking, resolving files, or aliases in TypeScript code. It lists the files involved in the compilation.

test

test runs tests for all packages.

Both ./packages/jaeger-ui and ./packages/plexus use Vitest for testing. It can be useful to directly run tests for a package by running pnpm test from its directory, rather than the repository root. To run an individual test file specify the file name, e.g. pnpm test src/utils/readJsonFile.test.js.

Snapshots

Tests for React components in ./packages/jaeger-ui make extensive use of Vitest's snapshot testing functionality. These snapshots can be regenerated by running pnpm run update-snapshots to regenerate all snapshots, or pnpm test -- -u -t <regex> from the package directory to regenerate snapshots for a subset of tests only (<regex> matches against the full test name, i.e. the test name and all surrounding describe blocks).

husky . hooks . pre-commit

Runs the lint and test scripts.

knip.config.ts

Dead-code analysis configuration for Knip. Knip runs as part of pnpm run lint in warning-only mode (knip || true — non-zero exit is suppressed). It reports unused files, exports, and dependencies.

Each ignoreDependencies entry in the config includes an inline comment explaining why it cannot be auto-detected. Before adding a new exclusion, verify the reason is still valid; before removing one, check that knip truly reports no false positive without it.

vite.config.ts — lint field

Oxlint configuration lives in the lint field of the root vite.config.ts. To change linting rules, edit that field. See ADR-0007 for the resulting toolchain and RFC 0005 for the ESLint → Oxlint rule mapping table.

vite.config.ts — fmt field

Oxfmt configuration lives in the fmt field of the root vite.config.ts (exported as a named fmt export consumed by vp fmt). To change formatting rules, edit that field. The file was originally generated via oxfmt --migrate=prettier from the prettier config block in package.json and was later moved from a standalone .oxfmtrc.json into vite.config.ts when upgrading to vite-plus 0.1.17 (oxfmt 0.45.0), which reads formatter config from the Vite config rather than a separate RC file.

.github/workflows

Holds GitHub Actions workflows used in CI and in release.

CodeCov is integrated into the unit tests workflow to report coverage data from ./packages/jaeger-ui. When unit tests are added to Plexus, this integration will need to be updated to gather coverage data for Plexus as well.

pnpm install --frozen-lockfile ensures installs in CI fail if they would typically mutate the lockfile.

tsconfig.json

Used to configure the tsc-lint script and, in theory, the IDE (such as VS Code).

A few notable compiler settings:

  • lib
  • skipLibCheck - Maybe worth reevaluating in the future
  • strict - Important
  • noEmit - We're using this for linting, after all
  • include - We've included ./typgings here because it turned out to be a lot simpler than configuring types, typeRoots and paths

typings/{custom.d.ts, index.d.ts}

This is relevant for ./packages/plexus/src/LayoutManager/getLayout.tsx and the viz.js package.

I wasn't able to get much in the line of error messaging, so I'm pretty vague on this.

The version of viz.js in use (1.8.1) ships with an index.d.ts file, but it has some issues. ./typings/custom.d.ts defines an alternate type declaration for viz.js by targeting viz.js/viz.js. It was necessary use ./typings/index.d.ts to refer to ./typings/custom.d.ts. Then, importing the modules main file, which is viz.js/viz.js, will use the alternate type declaration.