obsidian-plugin-dev-kit 0.0.0-stage → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +223 -2
- package/bin/opdk.js +34 -0
- package/dist/build/args.d.ts +10 -0
- package/dist/build/args.js +45 -0
- package/dist/build/bundle-check.d.ts +17 -0
- package/dist/build/bundle-check.js +42 -0
- package/dist/build/bundle-file.d.ts +4 -0
- package/dist/build/bundle-file.js +29 -0
- package/dist/build/commands.d.ts +5 -0
- package/dist/build/commands.js +109 -0
- package/dist/build/config.d.ts +3 -0
- package/dist/build/config.js +103 -0
- package/dist/build/css-imports.d.ts +23 -0
- package/dist/build/css-imports.js +50 -0
- package/dist/build/css-step.d.ts +10 -0
- package/dist/build/css-step.js +27 -0
- package/dist/build/css.d.ts +24 -0
- package/dist/build/css.js +47 -0
- package/dist/build/options.d.ts +55 -0
- package/dist/build/options.js +70 -0
- package/dist/build/release.d.ts +5 -0
- package/dist/build/release.js +34 -0
- package/dist/build/report.d.ts +7 -0
- package/dist/build/report.js +16 -0
- package/dist/build/vault.d.ts +26 -0
- package/dist/build/vault.js +290 -0
- package/dist/build-info.json +1 -0
- package/dist/cli/argv.d.ts +14 -0
- package/dist/cli/argv.js +18 -0
- package/dist/cli/commands.d.ts +3 -0
- package/dist/cli/commands.js +7 -0
- package/dist/cli/main.d.ts +2 -0
- package/dist/cli/main.js +23 -0
- package/dist/cli/process-reporter.d.ts +5 -0
- package/dist/cli/process-reporter.js +15 -0
- package/dist/cli/registry.d.ts +4 -0
- package/dist/cli/registry.js +15 -0
- package/dist/cli/reporter.d.ts +53 -0
- package/dist/cli/reporter.js +100 -0
- package/dist/cli/run.d.ts +9 -0
- package/dist/cli/run.js +61 -0
- package/dist/cli/types.d.ts +27 -0
- package/dist/cli/types.js +1 -0
- package/dist/cli/version.d.ts +13 -0
- package/dist/cli/version.js +61 -0
- package/dist/config/define-config.d.ts +3 -0
- package/dist/config/define-config.js +4 -0
- package/dist/config/load-config.d.ts +6 -0
- package/dist/config/load-config.js +70 -0
- package/dist/config/manifest.d.ts +3 -0
- package/dist/config/manifest.js +72 -0
- package/dist/config/types.d.ts +146 -0
- package/dist/config/types.js +23 -0
- package/dist/demo/args.d.ts +4 -0
- package/dist/demo/args.js +13 -0
- package/dist/demo/checks.d.ts +56 -0
- package/dist/demo/checks.js +124 -0
- package/dist/demo/commands.d.ts +3 -0
- package/dist/demo/commands.js +65 -0
- package/dist/demo/config.d.ts +57 -0
- package/dist/demo/config.js +337 -0
- package/dist/demo/ffmpeg-run.d.ts +18 -0
- package/dist/demo/ffmpeg-run.js +59 -0
- package/dist/demo/ffmpeg.d.ts +63 -0
- package/dist/demo/ffmpeg.js +111 -0
- package/dist/demo/films.d.ts +46 -0
- package/dist/demo/films.js +134 -0
- package/dist/demo/phone-layout.d.ts +38 -0
- package/dist/demo/phone-layout.js +98 -0
- package/dist/demo/phone-render.d.ts +28 -0
- package/dist/demo/phone-render.js +124 -0
- package/dist/demo/published.d.ts +16 -0
- package/dist/demo/published.js +72 -0
- package/dist/demo/run.d.ts +31 -0
- package/dist/demo/run.js +397 -0
- package/dist/demo/stills.d.ts +21 -0
- package/dist/demo/stills.js +62 -0
- package/dist/e2e/artifacts.d.ts +27 -0
- package/dist/e2e/artifacts.js +90 -0
- package/dist/e2e/cleanup.d.ts +54 -0
- package/dist/e2e/cleanup.js +109 -0
- package/dist/e2e/config.d.ts +9 -0
- package/dist/e2e/config.js +42 -0
- package/dist/e2e/create-test.d.ts +37 -0
- package/dist/e2e/create-test.js +109 -0
- package/dist/e2e/demo/clip.d.ts +21 -0
- package/dist/e2e/demo/clip.js +44 -0
- package/dist/e2e/demo/create-demo.d.ts +42 -0
- package/dist/e2e/demo/create-demo.js +439 -0
- package/dist/e2e/demo/manifest.d.ts +76 -0
- package/dist/e2e/demo/manifest.js +168 -0
- package/dist/e2e/demo/names.d.ts +18 -0
- package/dist/e2e/demo/names.js +44 -0
- package/dist/e2e/demo/options.d.ts +22 -0
- package/dist/e2e/demo/options.js +59 -0
- package/dist/e2e/demo/ownership.d.ts +27 -0
- package/dist/e2e/demo/ownership.js +65 -0
- package/dist/e2e/demo/page-scripts.d.ts +82 -0
- package/dist/e2e/demo/page-scripts.js +250 -0
- package/dist/e2e/demo/png.d.ts +8 -0
- package/dist/e2e/demo/png.js +23 -0
- package/dist/e2e/demo/presets.d.ts +43 -0
- package/dist/e2e/demo/presets.js +20 -0
- package/dist/e2e/demo/privacy.d.ts +18 -0
- package/dist/e2e/demo/privacy.js +30 -0
- package/dist/e2e/demo/still-options.d.ts +22 -0
- package/dist/e2e/demo/still-options.js +68 -0
- package/dist/e2e/demo/types.d.ts +184 -0
- package/dist/e2e/demo/types.js +1 -0
- package/dist/e2e/electron-binary.d.ts +15 -0
- package/dist/e2e/electron-binary.js +30 -0
- package/dist/e2e/fixtures.d.ts +62 -0
- package/dist/e2e/fixtures.js +68 -0
- package/dist/e2e/gate.d.ts +4 -0
- package/dist/e2e/gate.js +8 -0
- package/dist/e2e/global-setup.d.ts +11 -0
- package/dist/e2e/global-setup.js +17 -0
- package/dist/e2e/helpers/commands.d.ts +14 -0
- package/dist/e2e/helpers/commands.js +56 -0
- package/dist/e2e/helpers/create-helpers.d.ts +24 -0
- package/dist/e2e/helpers/create-helpers.js +582 -0
- package/dist/e2e/helpers/device-metrics.d.ts +21 -0
- package/dist/e2e/helpers/device-metrics.js +25 -0
- package/dist/e2e/helpers/ime.d.ts +13 -0
- package/dist/e2e/helpers/ime.js +19 -0
- package/dist/e2e/helpers/layout-page-scripts.d.ts +103 -0
- package/dist/e2e/helpers/layout-page-scripts.js +224 -0
- package/dist/e2e/helpers/layout.d.ts +83 -0
- package/dist/e2e/helpers/layout.js +148 -0
- package/dist/e2e/helpers/mobile.d.ts +31 -0
- package/dist/e2e/helpers/mobile.js +26 -0
- package/dist/e2e/helpers/page-scripts.d.ts +194 -0
- package/dist/e2e/helpers/page-scripts.js +467 -0
- package/dist/e2e/helpers/settings.d.ts +8 -0
- package/dist/e2e/helpers/settings.js +16 -0
- package/dist/e2e/helpers/settle.d.ts +28 -0
- package/dist/e2e/helpers/settle.js +33 -0
- package/dist/e2e/helpers/types.d.ts +193 -0
- package/dist/e2e/helpers/types.js +1 -0
- package/dist/e2e/helpers/view-mode.d.ts +23 -0
- package/dist/e2e/helpers/view-mode.js +35 -0
- package/dist/e2e/index.d.ts +14 -0
- package/dist/e2e/index.js +4 -0
- package/dist/e2e/internals.d.ts +155 -0
- package/dist/e2e/internals.js +8 -0
- package/dist/e2e/obsidian-path.d.ts +17 -0
- package/dist/e2e/obsidian-path.js +31 -0
- package/dist/e2e/options.d.ts +123 -0
- package/dist/e2e/options.js +244 -0
- package/dist/e2e/page-scripts.d.ts +45 -0
- package/dist/e2e/page-scripts.js +53 -0
- package/dist/e2e/peers.d.ts +9 -0
- package/dist/e2e/peers.js +19 -0
- package/dist/e2e/plugins.d.ts +32 -0
- package/dist/e2e/plugins.js +119 -0
- package/dist/e2e/process-tree.d.ts +33 -0
- package/dist/e2e/process-tree.js +133 -0
- package/dist/e2e/readiness.d.ts +23 -0
- package/dist/e2e/readiness.js +63 -0
- package/dist/e2e/seed.d.ts +34 -0
- package/dist/e2e/seed.js +122 -0
- package/dist/e2e/session.d.ts +71 -0
- package/dist/e2e/session.js +266 -0
- package/dist/e2e/vault.d.ts +52 -0
- package/dist/e2e/vault.js +146 -0
- package/dist/e2e/version.d.ts +25 -0
- package/dist/e2e/version.js +40 -0
- package/dist/eslint/index.d.ts +2 -0
- package/dist/eslint/index.js +1 -0
- package/dist/eslint/obsidian-plugin.d.ts +49 -0
- package/dist/eslint/obsidian-plugin.js +115 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1 -0
- package/dist/kit/args.d.ts +7 -0
- package/dist/kit/args.js +21 -0
- package/dist/kit/commands.d.ts +3 -0
- package/dist/kit/commands.js +52 -0
- package/dist/kit/files.d.ts +3 -0
- package/dist/kit/files.js +24 -0
- package/dist/kit/pins.d.ts +89 -0
- package/dist/kit/pins.js +178 -0
- package/dist/kit/remote.d.ts +13 -0
- package/dist/kit/remote.js +33 -0
- package/dist/kit/runners.d.ts +11 -0
- package/dist/kit/runners.js +53 -0
- package/dist/kit/terminal-text.d.ts +6 -0
- package/dist/kit/terminal-text.js +20 -0
- package/dist/kit/upgrade.d.ts +26 -0
- package/dist/kit/upgrade.js +162 -0
- package/dist/peers/resolve.d.ts +8 -0
- package/dist/peers/resolve.js +28 -0
- package/dist/peers/versions.d.ts +30 -0
- package/dist/peers/versions.js +32 -0
- package/dist/release/api-check.d.ts +27 -0
- package/dist/release/api-check.js +119 -0
- package/dist/release/args.d.ts +40 -0
- package/dist/release/args.js +120 -0
- package/dist/release/assets.d.ts +21 -0
- package/dist/release/assets.js +35 -0
- package/dist/release/build-check.d.ts +43 -0
- package/dist/release/build-check.js +184 -0
- package/dist/release/build-script.d.ts +12 -0
- package/dist/release/build-script.js +30 -0
- package/dist/release/build-tagged.d.ts +26 -0
- package/dist/release/build-tagged.js +52 -0
- package/dist/release/bump.d.ts +24 -0
- package/dist/release/bump.js +58 -0
- package/dist/release/changelog.d.ts +25 -0
- package/dist/release/changelog.js +148 -0
- package/dist/release/check.d.ts +38 -0
- package/dist/release/check.js +150 -0
- package/dist/release/commands.d.ts +3 -0
- package/dist/release/commands.js +154 -0
- package/dist/release/committed-tree.d.ts +63 -0
- package/dist/release/committed-tree.js +118 -0
- package/dist/release/config.d.ts +3 -0
- package/dist/release/config.js +28 -0
- package/dist/release/gh-access.d.ts +14 -0
- package/dist/release/gh-access.js +45 -0
- package/dist/release/gh.d.ts +10 -0
- package/dist/release/gh.js +33 -0
- package/dist/release/git.d.ts +49 -0
- package/dist/release/git.js +111 -0
- package/dist/release/interrupt.d.ts +30 -0
- package/dist/release/interrupt.js +60 -0
- package/dist/release/json.d.ts +33 -0
- package/dist/release/json.js +81 -0
- package/dist/release/kit-check.d.ts +8 -0
- package/dist/release/kit-check.js +51 -0
- package/dist/release/manifest-rules.d.ts +23 -0
- package/dist/release/manifest-rules.js +255 -0
- package/dist/release/preflight.d.ts +10 -0
- package/dist/release/preflight.js +65 -0
- package/dist/release/problems.d.ts +24 -0
- package/dist/release/problems.js +11 -0
- package/dist/release/project-files.d.ts +14 -0
- package/dist/release/project-files.js +16 -0
- package/dist/release/publish-command.d.ts +21 -0
- package/dist/release/publish-command.js +83 -0
- package/dist/release/publish-git.d.ts +37 -0
- package/dist/release/publish-git.js +108 -0
- package/dist/release/publish-state.d.ts +29 -0
- package/dist/release/publish-state.js +70 -0
- package/dist/release/publish-verify.d.ts +41 -0
- package/dist/release/publish-verify.js +112 -0
- package/dist/release/publish-wait.d.ts +25 -0
- package/dist/release/publish-wait.js +56 -0
- package/dist/release/publish.d.ts +35 -0
- package/dist/release/publish.js +181 -0
- package/dist/release/release-assets.d.ts +39 -0
- package/dist/release/release-assets.js +68 -0
- package/dist/release/release.d.ts +37 -0
- package/dist/release/release.js +179 -0
- package/dist/release/remote.d.ts +12 -0
- package/dist/release/remote.js +15 -0
- package/dist/release/reproducible.d.ts +16 -0
- package/dist/release/reproducible.js +34 -0
- package/dist/release/run-tests.d.ts +5 -0
- package/dist/release/run-tests.js +17 -0
- package/dist/release/semver.d.ts +8 -0
- package/dist/release/semver.js +60 -0
- package/dist/release/version-rules.d.ts +28 -0
- package/dist/release/version-rules.js +63 -0
- package/dist/release/versions-json.d.ts +15 -0
- package/dist/release/versions-json.js +88 -0
- package/dist/release/workflow-run.d.ts +44 -0
- package/dist/release/workflow-run.js +71 -0
- package/dist/scanner/code-checks.d.ts +41 -0
- package/dist/scanner/code-checks.js +82 -0
- package/dist/scanner/commands.d.ts +3 -0
- package/dist/scanner/commands.js +43 -0
- package/dist/scanner/config.d.ts +7 -0
- package/dist/scanner/config.js +25 -0
- package/dist/scanner/css-check.d.ts +26 -0
- package/dist/scanner/css-check.js +63 -0
- package/dist/scanner/eslint-nesting.d.ts +16 -0
- package/dist/scanner/eslint-nesting.js +45 -0
- package/dist/scanner/findings.d.ts +23 -0
- package/dist/scanner/findings.js +21 -0
- package/dist/scanner/git-files.d.ts +16 -0
- package/dist/scanner/git-files.js +73 -0
- package/dist/scanner/lint.d.ts +47 -0
- package/dist/scanner/lint.js +163 -0
- package/dist/scanner/meta-checks.d.ts +8 -0
- package/dist/scanner/meta-checks.js +22 -0
- package/dist/scanner/outside-project.d.ts +19 -0
- package/dist/scanner/outside-project.js +20 -0
- package/dist/scanner/run.d.ts +19 -0
- package/dist/scanner/run.js +78 -0
- package/dist/scanner/scanner-config.d.ts +114 -0
- package/dist/scanner/scanner-config.js +207 -0
- package/dist/scanner/typescript-gate.d.ts +30 -0
- package/dist/scanner/typescript-gate.js +73 -0
- package/dist/vitest/build-config.d.ts +17 -0
- package/dist/vitest/build-config.js +106 -0
- package/dist/vitest/define-unit-config.d.ts +27 -0
- package/dist/vitest/define-unit-config.js +45 -0
- package/dist/vitest/dom/elements.d.ts +87 -0
- package/dist/vitest/dom/elements.js +291 -0
- package/dist/vitest/dom/index.d.ts +1 -0
- package/dist/vitest/dom/index.js +1 -0
- package/dist/vitest/dom/install.d.ts +8 -0
- package/dist/vitest/dom/install.js +261 -0
- package/dist/vitest/dom/setup.d.ts +1 -0
- package/dist/vitest/dom/setup.js +3 -0
- package/dist/vitest/index.d.ts +3 -0
- package/dist/vitest/index.js +2 -0
- package/dist/vitest/options.d.ts +92 -0
- package/dist/vitest/options.js +136 -0
- package/dist/vitest/peers.d.ts +10 -0
- package/dist/vitest/peers.js +51 -0
- package/dist/vitest/workspace-root.d.ts +7 -0
- package/dist/vitest/workspace-root.js +39 -0
- package/docs/build.md +232 -0
- package/docs/ci.md +182 -0
- package/docs/demo.md +364 -0
- package/docs/e2e.md +563 -0
- package/docs/release.md +374 -0
- package/docs/scanner.md +204 -0
- package/docs/unit.md +291 -0
- package/package.json +100 -4
- package/plugins/opdk/skills/audit/SKILL.md +81 -0
- package/plugins/opdk/skills/build/SKILL.md +79 -0
- package/plugins/opdk/skills/demo/SKILL.md +102 -0
- package/plugins/opdk/skills/e2e/SKILL.md +132 -0
- package/plugins/opdk/skills/release/SKILL.md +84 -0
- package/plugins/opdk/skills/scanner/SKILL.md +60 -0
- package/plugins/opdk/skills/unit/SKILL.md +90 -0
package/docs/unit.md
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# Unit tests
|
|
2
|
+
|
|
3
|
+
`obsidian-plugin-dev-kit/vitest` exports `defineUnitConfig()`, the Vitest config Obsidian plugins tend to copy from one another: tests in `src/**/*.test.ts`, v8 coverage with a gate of 90 percent (80 for branches), an `obsidian` alias, and a split between test files that run in node and files that need a DOM. `obsidian-plugin-dev-kit/vitest/dom` installs Obsidian's DOM helpers (`createDiv`, `setText`, `addClass`, `activeDocument` and the rest) on jsdom. The kit adds no command: you keep `vitest run --coverage` as your `test` script.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
- **The same config gets copied between plugins.** The copies differ in coverage lists and the stub path, and each one tracks by hand that `vitest` and `@vitest/coverage-v8` move together (otherwise `ERESOLVE`) and which Node version Vitest 5 needs (jsdom 30 failed on Node 20 in CI).
|
|
8
|
+
- **Hand-written copies of Obsidian's DOM helpers drift.** Two plugins each had their own polyfill (97 and 274 lines), and they disagreed. In one, `setText`, and `createEl({ text })` in both, turned a `DocumentFragment` into a string, while Obsidian appends the fragment. The kit's version follows the behaviour of the shipped app (Obsidian 1.14.5) and is tested.
|
|
9
|
+
- **jsdom starts for every test file.** In a trial on a plugin with 85 test files and 3,271 tests, the run took 30.3 s, 85 percent of it starting jsdom. With the 32 files that need a DOM in the `dom` list and the other 53 in node, the same tests ran in 15.0 s.
|
|
10
|
+
- **A file nobody imports escapes the coverage gate.** Vitest 4 and later report only files a test imported, unless `coverage.include` says which files count. The preset makes `coverage.include` required.
|
|
11
|
+
|
|
12
|
+
## Quick start
|
|
13
|
+
|
|
14
|
+
Install what the preset runs on next to the kit (the same version of `vitest` and `@vitest/coverage-v8`, and `jsdom` only if some tests need a DOM), then add `vitest.config.ts`. The kit does not declare these as peer dependencies: `defineUnitConfig()` checks their versions when it runs ([Required versions](#required-versions-checked-at-run-time)).
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install --save-dev vitest@^5 @vitest/coverage-v8@^5 vite@^8 jsdom@^30
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
// vitest.config.ts
|
|
22
|
+
import { defineUnitConfig } from "obsidian-plugin-dev-kit/vitest";
|
|
23
|
+
|
|
24
|
+
export default defineUnitConfig({
|
|
25
|
+
rootDir: import.meta.dirname,
|
|
26
|
+
obsidian: "./src/test/stubs/obsidian.ts",
|
|
27
|
+
dom: ["src/ui/**/*.test.ts"],
|
|
28
|
+
coverage: {
|
|
29
|
+
include: ["src/**/*.ts"],
|
|
30
|
+
exclude: ["src/main.ts", "src/types.ts"],
|
|
31
|
+
},
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{ "scripts": { "test": "vitest run --coverage" } }
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Only `coverage.include` is required. Coverage is switched on in the config, so a plain `vitest run` also collects it; `vitest run --coverage.enabled=false` turns it off for a quick run. The config is plain data: spread it, or pass it to `mergeConfig` from `vitest/config`, to add whatever is yours (`test.setupFiles`, `test.testTimeout`, `resolve.alias`).
|
|
40
|
+
|
|
41
|
+
Vitest 5 needs Node 22.12 or newer (22.22.2 with jsdom). It declares `vite` (`^6.4 || ^7 || ^8`) as a peer dependency, which npm 7 and newer install automatically. List `vite` in your `devDependencies` anyway, so your `package.json` pins the version your tests run on.
|
|
42
|
+
|
|
43
|
+
## Options
|
|
44
|
+
|
|
45
|
+
All keys of the object passed to `defineUnitConfig()`. An unknown key, or a value of the wrong type, throws and names the option.
|
|
46
|
+
|
|
47
|
+
| Option | Type | Default | What it does |
|
|
48
|
+
|---|---|---|---|
|
|
49
|
+
| `coverage` | object | required | See the next table |
|
|
50
|
+
| `obsidian` | string or `{ node, dom }` | no alias | How `import "obsidian"` resolves in tests: a path to your own stub (relative to `rootDir`), `"obsidian-test-mocks"`, or one of each per project: `{ node: "<stub path>", dom: "obsidian-test-mocks" \| "<stub path>" }` |
|
|
51
|
+
| `dom` | string[] or `"all"` | `[]` | Test files that need a DOM, as globs relative to the folder of `vitest.config.ts`. `"all"` puts every test file in jsdom; omitted or `[]` runs everything in node |
|
|
52
|
+
| `include` | string[] | `["src/**/*.test.ts"]` | Test file globs, relative to the folder of `vitest.config.ts` |
|
|
53
|
+
| `rootDir` | string | `process.cwd()` | The folder the `obsidian` stub path is resolved against. Pass `import.meta.dirname` so the config works from any working directory |
|
|
54
|
+
|
|
55
|
+
`coverage`:
|
|
56
|
+
|
|
57
|
+
| Option | Type | Default | What it does |
|
|
58
|
+
|---|---|---|---|
|
|
59
|
+
| `include` | string[] | required | Globs of the files the gate counts, for example `["src/**/*.ts"]` |
|
|
60
|
+
| `exclude` | string[] | `[]` | Added to the base list `**/*.test.ts`, `src/test/**`, `**/*.d.ts`, which is always excluded |
|
|
61
|
+
| `thresholds` | object | `{ lines: 90, functions: 90, statements: 90, branches: 80 }` | Raise individual values. Each key is `lines`, `functions`, `statements` or `branches`, a number from 0 to 100 |
|
|
62
|
+
| `allowLowerThresholds` | boolean | `false` | Lets a value in `thresholds` go below the default. Without it a lower value throws |
|
|
63
|
+
| `extraReporters` | `("lcov" \| "html")[]` | `[]` | Reports written next to `text` and `json-summary`. The report folder is `coverage` |
|
|
64
|
+
|
|
65
|
+
What the config sets besides these: the v8 provider, `coverage.enabled: true`, the `text` and `json-summary` reporters, the environment `node` (jsdom for the files in `dom`).
|
|
66
|
+
|
|
67
|
+
### The coverage list and the floor
|
|
68
|
+
|
|
69
|
+
Vitest 4 removed `coverage.all`, and Vitest 5 keeps it that way: without `coverage.include`, a source file that no test imports is not in the report, so the gate cannot fail for it. The config throws when `coverage.include` is missing instead of letting that through. List what the gate must count. One way is an allow-list (`src/core/**/*.ts`, `src/api/**/*.ts`) when the UI is left to the end-to-end tests; the other is `src/**/*.ts` with an `exclude` for the files tested elsewhere, each with a comment saying why.
|
|
70
|
+
|
|
71
|
+
The defaults are a floor, not a goal: bugs have shipped on fully covered lines, so the number says little about test quality. Raising a value is fine (`thresholds: { branches: 85 }`). Lowering one needs `allowLowerThresholds: true`, so it is a visible, reviewed decision:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
coverage: { include: ["src/**/*.ts"], thresholds: { branches: 70 }, allowLowerThresholds: true },
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### lcov for a coverage service
|
|
78
|
+
|
|
79
|
+
`extraReporters: ["lcov"]` writes `coverage/lcov.info`, the file a service like Codecov reads. `"html"` writes `coverage/index.html` for reading locally. `json-summary` is always on, so scripts can read `coverage/coverage-summary.json`. When Vitest detects an AI coding agent it hides fully covered files in the `text` table, which does not change the files in `coverage/`.
|
|
80
|
+
|
|
81
|
+
### `obsidian`: your own stub or obsidian-test-mocks
|
|
82
|
+
|
|
83
|
+
The `obsidian` package contains types only, so `import { Notice } from "obsidian"` fails at run time unless tests resolve it somewhere.
|
|
84
|
+
|
|
85
|
+
- **A path** (`"./src/test/stubs/obsidian.ts"`): the kit aliases `obsidian` to that file in every project, node and DOM. The stub is yours and stays in the plugin.
|
|
86
|
+
- **`"obsidian-test-mocks"`**: the [obsidian-test-mocks](https://www.npmjs.com/package/obsidian-test-mocks) package. The kit uses that package's `vitest-setup` file as the setup file of the DOM tests and does not install its own polyfill, because the package installs the same helpers (and patches more, among them some JavaScript built-ins). The kit also aliases `obsidian` to the package's own `obsidian` module, because the types package has no JavaScript entry. It needs a DOM: `dom` must list files or be `"all"`, or the config throws. The alias and the setup file belong to the `dom` project only, so a node test that imports `obsidian` cannot resolve it. Use the `{ node, dom }` form below when the plugin has such tests.
|
|
87
|
+
- **`{ node, dom }`**: one value per project. `node` is a path to your own stub, used by the files that run in node. `dom` is `"obsidian-test-mocks"` or another stub path, used by the files in the `dom` list. Both are required, unknown keys throw, and `node` cannot be `"obsidian-test-mocks"` (the package needs a DOM). With `dom: "all"` there is no node project, so only the `dom` side is used.
|
|
88
|
+
- **Omitted**: no alias. Fine for tests of code that never imports `obsidian`.
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
export default defineUnitConfig({
|
|
92
|
+
rootDir: import.meta.dirname,
|
|
93
|
+
obsidian: { node: "./src/test/stubs/obsidian.ts", dom: "obsidian-test-mocks" },
|
|
94
|
+
dom: ["src/ui/**/*.test.ts"],
|
|
95
|
+
coverage: { include: ["src/**/*.ts"] },
|
|
96
|
+
});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### obsidian-test-mocks for settings tabs and modals
|
|
100
|
+
|
|
101
|
+
The kit has no mock of its own and recommends obsidian-test-mocks for UI tests of settings tabs and modals, where a hand-written stub grows quickly.
|
|
102
|
+
|
|
103
|
+
- **Pin an exact version** (`"obsidian-test-mocks": "8.0.0"`, no `^`). The package ships a new major every few weeks, and a major can change what a test sees. Tell Dependabot to ignore major updates for it, and bump it on purpose.
|
|
104
|
+
- **Install it in the plugin, use it in the `dom` project only.** The `{ node, dom }` form above does that: node tests keep the stub they have.
|
|
105
|
+
- **Peer dependencies**: `obsidian`, `moment`, `@codemirror/view` and `@codemirror/state` (jest or vitest, optional). The `dom` project also needs `jsdom` in the plugin.
|
|
106
|
+
- **Known gaps in 8.0.0.** Check the package README before you rely on a behaviour; they may be fixed later:
|
|
107
|
+
- Declarative `control` setting rows are not modelled, so `renderTab` throws on a tab that uses them.
|
|
108
|
+
- `SettingTab.update()` does not redraw.
|
|
109
|
+
- `Modal.open()` closes on the next tick. Call `onOpen()` directly in the test.
|
|
110
|
+
- The mock app is a strict proxy: reading a private app property the package does not model throws. Assign it on the mock in the test.
|
|
111
|
+
|
|
112
|
+
## Running DOM tests in jsdom only where needed
|
|
113
|
+
|
|
114
|
+
With `dom: [...]` globs, the config has two Vitest projects. `unit` runs every test file that matches `include` and is not in the `dom` list, in node. `dom` runs the listed files in jsdom, with the Obsidian DOM helpers installed by a setup file. The coverage gate stays at the root, so it counts both projects. With `dom: "all"` there is one project, in jsdom with the setup file; with `dom` omitted, one project in node.
|
|
115
|
+
|
|
116
|
+
**Linked installs.** The setup file of the `dom` project lives in the kit's folder. With `npm link` or `file:../obsidian-plugin-dev-kit`, `node_modules/obsidian-plugin-dev-kit` is a symlink, so the file's real path is outside your plugin, and Vite's `server.fs.strict` would refuse to serve it (`Cannot find module '/@fs/.../dist/vitest/dom/setup.js'`). The preset handles it: when the kit's folder is outside `rootDir`, it sets `server.fs.allow` to your workspace root (the folder Vite allows by default: the nearest parent with `pnpm-workspace.yaml`, `lerna.json` or `workspaces` in `package.json`, else the nearest `package.json`) and the kit's `dist/vitest/dom` folder. `fs.strict` stays on. Installs from a git tag are copies inside `node_modules` and usually get no `server` key (when your plugin's path goes through a symlink, an extra entry inside the plugin may appear; it is harmless). `mergeConfig` appends your own `server.fs.allow` entries to these; a plain spread (`server: { fs: { allow: [...] } }` after `...defineUnitConfig()`) replaces them, so list the workspace root and the kit's folder yourself or use `mergeConfig`.
|
|
117
|
+
|
|
118
|
+
Finding the files that need a DOM: start with `dom: []`, run the tests, and look at the failures. A file that needs a DOM fails in node with one of these errors, the first being `document is not defined`:
|
|
119
|
+
|
|
120
|
+
- `ReferenceError: document is not defined`
|
|
121
|
+
- `ReferenceError: window is not defined`
|
|
122
|
+
- `ReferenceError: DOMParser is not defined`
|
|
123
|
+
- `ReferenceError: createDiv is not defined` (or `createEl`, `createSpan`, `createFragment`, `activeDocument`, `activeWindow`)
|
|
124
|
+
|
|
125
|
+
To list the failing files in one go:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
npx vitest run --no-color --coverage.enabled=false 2>&1 | grep -E "^ FAIL " | sed 's/^ FAIL //; s/^|[^|]*| //; s/ \[.*//; s/ >.*//' | sort -u
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
It needs a POSIX shell. It prints every failing file, not only the ones that lack a DOM, so read the error of each before listing it. Add the globs of those files to `dom` and run again. Directory globs (`src/ui/**/*.test.ts`) cover most of it; single files cover the rest. The shape of such a list:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
dom: [
|
|
135
|
+
"src/ui/**/*.test.ts",
|
|
136
|
+
"src/views/**/*.test.ts",
|
|
137
|
+
"src/core/render.test.ts",
|
|
138
|
+
"src/settings/tab.test.ts",
|
|
139
|
+
],
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Notes:
|
|
143
|
+
|
|
144
|
+
- **A per-file `// @vitest-environment jsdom` comment still works.** In a file of the `unit` project it gives that file jsdom, but not the polyfill, because the setup file belongs to the `dom` project. Such a file calls `installObsidianDom()` itself, or moves to the `dom` list, which is simpler.
|
|
145
|
+
- **Globs are relative to the folder of `vitest.config.ts`**, and a file matching both lists runs only in `dom`.
|
|
146
|
+
- **Vitest 5 appends a project's `include` to the root one.** The config therefore sets the root `include` only when there are no projects, and puts `include` inside each project otherwise.
|
|
147
|
+
|
|
148
|
+
## `isolate: false` for jsdom-heavy suites
|
|
149
|
+
|
|
150
|
+
By default Vitest gives every test file a fresh module registry and global scope. That is what costs time in a jsdom-heavy suite. `test.isolate: false` lets the files that share a worker share their modules and globals, which is faster and unsafe: it is an option to try, never a default, and the preset does not set it. Add it with `mergeConfig` (the projects extend the root config):
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
export default mergeConfig(defineUnitConfig({ /* ... */ }), { test: { isolate: false } });
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Three plugins tried it. One jsdom-heavy suite went from 20.6 s to 6.7 s (3x) after four leaks were fixed first. One gained nothing. One ran 1.8x faster and was green on two and three workers, but six tests failed on one worker in default order, and between six and 37 failed in every shuffled seed. The same switch is a gain for one suite and a source of failures for the next.
|
|
157
|
+
|
|
158
|
+
A leak is state one file leaves behind and a later file in the same worker reads. Typical ones:
|
|
159
|
+
|
|
160
|
+
- a `vi.mock` of a module that another file already loaded: the mock never reaches that module, or reaches it for the files that run after it;
|
|
161
|
+
- the `moment` locale, and date or locale overrides (`Intl`, a patched `Date`, a timezone) that one file sets and never restores;
|
|
162
|
+
- DOM left in `document` (a modal, a container appended to `body`) that a later file queries;
|
|
163
|
+
- globals a test sets (`window.app`, `globalThis` fields, a patched `console`, fake timers) and does not restore.
|
|
164
|
+
|
|
165
|
+
Prove the suite before relying on it, on one worker, in shuffled order, for several seeds, because with many workers each worker gets few files and the leaks stay hidden:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
# The subshell stops at the first failing run and leaves your terminal open.
|
|
169
|
+
(
|
|
170
|
+
set -e
|
|
171
|
+
for seed in 1 2 3 4 5; do npx vitest run --maxWorkers=1 --sequence.shuffle --sequence.seed=$seed --coverage.enabled=false; done
|
|
172
|
+
npx vitest run --maxWorkers=1 --coverage.enabled=false
|
|
173
|
+
npx vitest run --maxWorkers=2 --coverage.enabled=false
|
|
174
|
+
npx vitest run --maxWorkers=3 --coverage.enabled=false
|
|
175
|
+
)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Every run has to pass: the shuffled ones, the default order on one worker, and the default order on two and three workers. A failure names a file that leaks into the next one: fix it with `afterEach` cleanup (`vi.restoreAllMocks()`, `document.body.replaceChildren()`, restoring the global) and run the loop again. If the suite does not gain, or the fixes cost more than the saved time, leave `isolate` on.
|
|
179
|
+
|
|
180
|
+
## The DOM polyfill
|
|
181
|
+
|
|
182
|
+
`installObsidianDom()` and `uninstallObsidianDom()` come from `obsidian-plugin-dev-kit/vitest/dom`. The `dom` project runs the setup file `obsidian-plugin-dev-kit/vitest/dom/setup`, which calls `installObsidianDom()` once per test file, so you rarely call it yourself. For hand use, in a test file that runs under jsdom:
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
import { installObsidianDom, uninstallObsidianDom } from "obsidian-plugin-dev-kit/vitest/dom";
|
|
186
|
+
|
|
187
|
+
beforeAll(installObsidianDom);
|
|
188
|
+
afterAll(uninstallObsidianDom);
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
Install twice is a no-op. Install without a DOM throws: "installObsidianDom() needs a DOM and this test runs in the node environment. Add `// @vitest-environment jsdom` to the top of the test file, or list the file in the `dom` option of defineUnitConfig()." `uninstallObsidianDom()` puts back what was there before and removes what was added.
|
|
192
|
+
|
|
193
|
+
The behaviour of each helper was read from the shipped Obsidian app (1.14.5, the code in `app.asar`, never by running the app) and has unit tests in the kit. Covered, and nothing else:
|
|
194
|
+
|
|
195
|
+
- **Create:** `createEl`, `createDiv`, `createSpan`, `createSvg` and `createFragment` as globals; `createEl`, `createDiv`, `createSpan`, `createSvg` on every node. The info object takes `cls`, `text` (a string or a fragment), `attr` (a `null` value removes the attribute), `title`, `value`, `type`, `placeholder`, `href`, `parent`, `prepend` and `on*` listeners, and the callback argument works. The info can also be a plain string, which is the class. `createSvg` makes an element in the SVG namespace and takes only `cls`, `attr`, `parent` and `prepend`.
|
|
196
|
+
- **Node:** `appendText`, `empty`, `detach`, `insertAfter`, `indexOf`, `setChildrenInPlace`, `instanceOf`, `doc`, `win`, `constructorWin`.
|
|
197
|
+
- **Element:** `setText` (a string or a node or fragment, which replaces the children), `getText`, `setAttr`, `setAttrs`, `getAttr`, `addClass`, `addClasses`, `removeClass`, `removeClasses`, `toggleClass`, `hasClass`, `find`, `findAll`, `findAllSelf`, `matchParent`, `getCssPropertyValue`, `isActiveElement`; `find` and `findAll` on fragments.
|
|
198
|
+
- **HTMLElement:** `show`, `hide`, `toggle`, `isShown`, `toggleVisibility`, `innerWidth`, `innerHeight`, `setCssStyles`, `setCssProps`, `addEventListeners`, `trigger`, `onClickEvent` (`setCssStyles` and `setCssProps` also on SVG elements); `on` and `off` for delegated listeners (`el.on("click", ".item", (event, matchedElement) => ...)`), also on `document`.
|
|
199
|
+
- **UIEvent:** `targetNode`, `win`, `doc`, `instanceOf`.
|
|
200
|
+
- **Globals:** `activeWindow`, `activeDocument`, `fish`, `fishAll`, `ready`, `sleep`, `nextFrame`.
|
|
201
|
+
|
|
202
|
+
An existing `show`, `hide`, `toggle`, `toggleVisibility`, `activeWindow` or `activeDocument` is left alone.
|
|
203
|
+
|
|
204
|
+
Not installed:
|
|
205
|
+
|
|
206
|
+
- The app's extensions to `Array`, `String`, `Number`, `Math` and `Object` (`first`, `last`, `contains`, `unique`, `clamp`, ...), and the globals `isBoolean` and `globalEnhance`.
|
|
207
|
+
- `ajax` and `ajaxPromise`.
|
|
208
|
+
- `onNodeInserted` and `onWindowMigrated`: they wait for a CSS animation event, which jsdom never fires.
|
|
209
|
+
- The app's `ResizeObserver` stub (empty `observe`, `unobserve` and `disconnect`) and its `matchMedia` wrapper (adds `addEventListener` to a query object that lacks it). jsdom has neither `ResizeObserver` nor `matchMedia`, so code that calls them fails with a `ReferenceError` or `TypeError`. A test stubs them itself, for example `vi.stubGlobal("ResizeObserver", class { observe() {} unobserve() {} disconnect() {} })` and `vi.stubGlobal("matchMedia", (media: string): MediaQueryList => ({ matches: false, media, onchange: null, addListener() {}, removeListener() {}, addEventListener() {}, removeEventListener() {}, dispatchEvent: () => false }))` (both undone by `vi.unstubAllGlobals()`).
|
|
210
|
+
- The app's stubs for `TouchEvent`, `prepend` and `Object.hasOwn`: jsdom already has all three, so there is nothing to add.
|
|
211
|
+
|
|
212
|
+
`innerWidth` and `innerHeight` are installed with the app's formula, `scrollWidth` (`scrollHeight`) minus padding. jsdom has no layout and reports a scroll size of 0, so they are 0 minus the padding unless a test defines `scrollWidth` or `scrollHeight` on the element.
|
|
213
|
+
|
|
214
|
+
Three deviations from the app, two forced by jsdom and one a design choice:
|
|
215
|
+
|
|
216
|
+
- **`isShown`** is true for an element that is in the document with no inline `display: none` on itself or an ancestor. The app returns `!!offsetParent`, which jsdom, having no layout, always reports as `null`.
|
|
217
|
+
- **`scrollIntoView`** is added as a no-op when jsdom lacks it. The app has no such helper; browsers do, and code that scrolls an element into view fails without it.
|
|
218
|
+
- **Delegated `on` and `off`** keep their listeners in a `WeakMap` keyed by the element, where the app uses an `_EVENTS` property on the element. The behaviour is the same; the kit does not add a property to the element.
|
|
219
|
+
|
|
220
|
+
The helpers call each other through the public methods, as the app does: `createDiv` and `createSpan` go through `this.createEl`, the global `createDiv` through the global `createEl`, `addClass` through `addClasses`, `removeClass` through `removeClasses` and `toggle` through `show` and `hide`. A test that spies on `createEl` therefore sees the calls of `createDiv`. Like the app, `createEl` on a node writes `parent` into the info object it was given; the global `createEl` does not mutate it.
|
|
221
|
+
|
|
222
|
+
## Required versions, checked at run time
|
|
223
|
+
|
|
224
|
+
The kit declares no peer dependency on `vitest`, `@vitest/coverage-v8` or `jsdom`. npm checks even an optional peer when the package is installed, so a plugin still on Vitest 3 or jsdom 26 could not install the kit at all (`ERESOLVE`), although it never uses the unit preset. `defineUnitConfig()` looks the packages up from `rootDir` instead, the way the plugin's own code resolves them, and throws before building the config when a version does not fit:
|
|
225
|
+
|
|
226
|
+
| Package | Required | When | Notes |
|
|
227
|
+
|---|---|---|---|
|
|
228
|
+
| `vitest` | major 5 (`^5.0.0`) | always | Node 22.12 or newer (22.22.2 with jsdom). The kit's own tests run on it |
|
|
229
|
+
| `@vitest/coverage-v8` | the same version as `vitest` | always | Two versions of the pair fail with `ERESOLVE` in the plugin and are rejected here |
|
|
230
|
+
| `jsdom` | 30 or newer (`>=30.0.0`) | `dom` globs or `"all"` | The version the `dom` project and the kit's own tests run on, and the lowest one tested. Needs Node 22.22.2+, 24.15+ or 26+; older Node fails with `webidl.util.markAsUncloneable is not a function` |
|
|
231
|
+
| `vite` | `^6.4 \|\| ^7 \|\| ^8` | not checked | A peer of Vitest 5 that npm 7 and newer install automatically; list it in your dev dependencies to pin the version |
|
|
232
|
+
|
|
233
|
+
Every problem is reported in one error, with the command that fixes all of them:
|
|
234
|
+
|
|
235
|
+
```
|
|
236
|
+
defineUnitConfig(): "vitest" 3.2.4 is installed; the kit needs ^5.0.0.
|
|
237
|
+
defineUnitConfig(): "@vitest/coverage-v8" 3.2.4 is installed; the kit needs ^5.0.0.
|
|
238
|
+
defineUnitConfig(): "jsdom" 26.1.0 is installed; the kit needs >=30.0.0.
|
|
239
|
+
Run: npm install --save-dev vitest@^5.0.0 @vitest/coverage-v8@^5.0.0 "jsdom@>=30.0.0"
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
A package that is not installed gives `"<name>" is not installed; the kit needs <range>.` With `vitest` 5 present and a different `@vitest/coverage-v8`, the message names both versions and installs the coverage package at the version of `vitest`. `jsdom` is not checked when every test runs in node.
|
|
243
|
+
|
|
244
|
+
## Type-check the tests
|
|
245
|
+
|
|
246
|
+
Recommended, not required: let `tsc --noEmit` cover the test files. Many plugins exclude `*.test.ts` from `tsconfig.json`, so a type error in a test is found only when the test fails at run time. The preset does not check types. Tests often need more than the plugin's build does: they spread a `NodeList` (`[...container.querySelectorAll("li")]`, which needs `DOM.Iterable`) or use ES2022 features that the plugin's `lib` leaves out on purpose. Do not widen the plugin's own `tsconfig.json` for that; add a `tsconfig.test.json` and point a script at it:
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"extends": "./tsconfig.json",
|
|
251
|
+
"compilerOptions": { "lib": ["ES2022", "DOM", "DOM.Iterable"], "noEmit": true },
|
|
252
|
+
"include": ["src/**/*.ts"],
|
|
253
|
+
"exclude": ["node_modules", "dist"]
|
|
254
|
+
}
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
```json
|
|
258
|
+
"typecheck:tests": "tsc -p tsconfig.test.json"
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
The plugin keeps its target `lib`, so `tsc` on the build config still rejects an API the plugin must not call. (TypeScript 6 includes `DOM.Iterable` in `DOM`; listing it is harmless.) `src/**/*.ts` already covers the tests and `src/test`; take the `include` globs from where your tests and their helpers live if they sit elsewhere.
|
|
262
|
+
|
|
263
|
+
Two things show up when a plugin first type-checks its tests:
|
|
264
|
+
|
|
265
|
+
- **A test that reaches the bundled `main.js` gets `any`.** Where `main.ts` and `main.js` sit in one folder, TypeScript prefers `main.ts`, so that is not the trap. The trap is a relative path that climbs one level too far, to the plugin root, where only the bundle lives: `../main` from `src/test/` is `src/main`, but from `src/` it is the root `main.js`. With `strict`, `tsc -p tsconfig.test.json` reports TS7016 (no declaration file) there, while Vitest runs the import as `any` and the test checks nothing. Import from the source file through the right relative path (for example `src/main.ts`), never from the root bundle.
|
|
266
|
+
- **The preset's lint does not read `*.test.ts`.** `obsidianPlugin()` ignores `src/**/*.test.ts` (it is in `DEFAULT_IGNORES`), so a test is never linted by `eslint .`. Helpers are different: a file such as `src/test/helpers.ts` is linted like any source file unless the plugin lists it in `ignores`. Keep helpers out of `ignores` so they are linted, and name them without `.test.ts`. The type check above is what covers the test files themselves.
|
|
267
|
+
|
|
268
|
+
## Migrating a plugin
|
|
269
|
+
|
|
270
|
+
List each change a plugin makes while adopting the module in its changelog, and run its end-to-end tests afterwards.
|
|
271
|
+
|
|
272
|
+
1. **On Vitest 3 or older, bump to 5 first**, with `@vitest/coverage-v8` and `jsdom`, as a change of its own. Expect failures from mocks written for older versions: `vi.fn(arrow)` used as a constructor (a mock of `Notice`, for example) does not work on Vitest 5. Use a `class` or a `function` in the mock.
|
|
273
|
+
2. **Delete your own copy of Obsidian's DOM helpers** and remove `environment`, `coverage.reportsDirectory` and the setup file of the old DOM polyfill (the preset adds its own to the `dom` project, or to the root with `dom: "all"`). Keep other setup files and add them with `mergeConfig`. Remove calls such as `installObsidianDomHelpers()` from `beforeAll`. The files that needed them go into `dom`. A test that relied on a fragment becoming a string in `setText` output was asserting a bug.
|
|
274
|
+
3. **Replace `vitest.config.ts`** with `defineUnitConfig()`. Point `obsidian` at the plugin's existing stub, and copy its coverage lists into `coverage.include` and `coverage.exclude`. Reporters other than `text` and `json-summary` go into `extraReporters`.
|
|
275
|
+
4. **Find the `dom` globs** with the method above. If the plugin ran every test file in jsdom, the files that do not need it now run in node: a visible change, list it in the changelog.
|
|
276
|
+
5. **A plugin with no DOM tests** has nothing to split: leave `dom` out.
|
|
277
|
+
|
|
278
|
+
## Reading a run
|
|
279
|
+
|
|
280
|
+
A trial on a plugin with 85 test files, with the split in place (Vitest 5.1.0):
|
|
281
|
+
|
|
282
|
+
```text
|
|
283
|
+
RUN v5.1.0 /path/to/your-plugin
|
|
284
|
+
Coverage enabled with v8
|
|
285
|
+
|
|
286
|
+
Test Files 85 passed (85)
|
|
287
|
+
Tests 3271 passed (3271)
|
|
288
|
+
Duration 15.02s (environment 65%, import 17%, tests 8%, transform 7%, worker 3%)
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
`environment` is the time spent starting jsdom and node workers. Before the split it was 85 percent of 30.27 s. When a threshold fails, Vitest prints which one and exits non-zero, in a line of the form `ERROR: Coverage for branches (78.4%) does not meet global threshold (80%)`. The threshold error of the kit itself is different and comes before any test runs: `defineUnitConfig(): threshold "branches: 70" is below the default 80. The default is a floor. Raise the coverage, or set allowLowerThresholds: true to lower it on purpose.`
|
package/package.json
CHANGED
|
@@ -1,6 +1,102 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "obsidian-plugin-dev-kit",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.3.2",
|
|
4
|
+
"description": "Build, lint, release, test and film Obsidian plugins from one shared dev dependency.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"obsidian",
|
|
7
|
+
"obsidian-plugin",
|
|
8
|
+
"obsidian-md",
|
|
9
|
+
"esbuild",
|
|
10
|
+
"eslint",
|
|
11
|
+
"playwright",
|
|
12
|
+
"vitest",
|
|
13
|
+
"release",
|
|
14
|
+
"cli"
|
|
15
|
+
],
|
|
16
|
+
"homepage": "https://github.com/Dimagious/obsidian-plugin-dev-kit#readme",
|
|
17
|
+
"bugs": {
|
|
18
|
+
"url": "https://github.com/Dimagious/obsidian-plugin-dev-kit/issues"
|
|
19
|
+
},
|
|
20
|
+
"type": "module",
|
|
21
|
+
"license": "MIT",
|
|
22
|
+
"author": "Dmitriy Yurkin",
|
|
23
|
+
"repository": {
|
|
24
|
+
"type": "git",
|
|
25
|
+
"url": "git+https://github.com/Dimagious/obsidian-plugin-dev-kit.git"
|
|
26
|
+
},
|
|
27
|
+
"bin": {
|
|
28
|
+
"opdk": "./bin/opdk.js"
|
|
29
|
+
},
|
|
30
|
+
"exports": {
|
|
31
|
+
".": {
|
|
32
|
+
"types": "./dist/index.d.ts",
|
|
33
|
+
"default": "./dist/index.js"
|
|
34
|
+
},
|
|
35
|
+
"./eslint": {
|
|
36
|
+
"types": "./dist/eslint/index.d.ts",
|
|
37
|
+
"default": "./dist/eslint/index.js"
|
|
38
|
+
},
|
|
39
|
+
"./e2e": {
|
|
40
|
+
"types": "./dist/e2e/index.d.ts",
|
|
41
|
+
"default": "./dist/e2e/index.js"
|
|
42
|
+
},
|
|
43
|
+
"./vitest": {
|
|
44
|
+
"types": "./dist/vitest/index.d.ts",
|
|
45
|
+
"default": "./dist/vitest/index.js"
|
|
46
|
+
},
|
|
47
|
+
"./vitest/dom": {
|
|
48
|
+
"types": "./dist/vitest/dom/index.d.ts",
|
|
49
|
+
"default": "./dist/vitest/dom/index.js"
|
|
50
|
+
},
|
|
51
|
+
"./vitest/dom/setup": {
|
|
52
|
+
"types": "./dist/vitest/dom/setup.d.ts",
|
|
53
|
+
"default": "./dist/vitest/dom/setup.js"
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
"engines": {
|
|
57
|
+
"node": "^22.13.0 || >=24"
|
|
58
|
+
},
|
|
59
|
+
"files": [
|
|
60
|
+
"bin",
|
|
61
|
+
"dist",
|
|
62
|
+
"docs/*.md",
|
|
63
|
+
"plugins/opdk/skills"
|
|
64
|
+
],
|
|
65
|
+
"scripts": {
|
|
66
|
+
"build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node scripts/write-build-info.mjs",
|
|
67
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
68
|
+
"lint": "eslint . --max-warnings=0",
|
|
69
|
+
"test": "vitest run --coverage",
|
|
70
|
+
"smoke": "bash scripts/pack-smoke.sh",
|
|
71
|
+
"plugin:validate": "node scripts/plugin-validate.mjs",
|
|
72
|
+
"e2e:smoke": "playwright test -c test/e2e-fixture/playwright.config.ts",
|
|
73
|
+
"prepare": "npm run build",
|
|
74
|
+
"docs:media": "vhs docs/media/build.tape && vhs docs/media/build-check-fails.tape && vhs docs/media/scan.tape && vhs docs/media/scan-fails.tape",
|
|
75
|
+
"docs:media:e2e": "bash scripts/docs-media-e2e.sh",
|
|
76
|
+
"docs:media:demo": "bash scripts/docs-media-demo.sh"
|
|
77
|
+
},
|
|
78
|
+
"dependencies": {
|
|
79
|
+
"doiuse": "6.0.6",
|
|
80
|
+
"esbuild": "0.28.2",
|
|
81
|
+
"eslint-plugin-obsidianmd": "0.5.1",
|
|
82
|
+
"postcss": "8.5.32",
|
|
83
|
+
"typescript-eslint": "8.72.2"
|
|
84
|
+
},
|
|
85
|
+
"peerDependencies": {
|
|
86
|
+
"eslint": "^9.19.0 || ^10.0.0",
|
|
87
|
+
"typescript": ">=6.0.0 <6.1.0"
|
|
88
|
+
},
|
|
89
|
+
"devDependencies": {
|
|
90
|
+
"@eslint/js": "10.0.1",
|
|
91
|
+
"@playwright/test": "1.65.0",
|
|
92
|
+
"@types/node": "22.20.5",
|
|
93
|
+
"@vitest/coverage-v8": "5.1.0",
|
|
94
|
+
"electron": "45.2.3",
|
|
95
|
+
"eslint": "10.14.0",
|
|
96
|
+
"jsdom": "30.1.1",
|
|
97
|
+
"obsidian": "1.14.4",
|
|
98
|
+
"typescript": "6.0.3",
|
|
99
|
+
"vitest": "5.1.0",
|
|
100
|
+
"yaml": "2.9.1"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: audit
|
|
3
|
+
description: Audit how well an Obsidian plugin that already uses obsidian-plugin-dev-kit (opdk) takes advantage of it, then make the changes its author picks. Finds what the plugin still does by hand next to a kit command or helper, pictures and films nothing in the repo can retake or that are stale, code outside the coverage gate, untyped tests, unit runs that only pass in parallel, fixed sleeps in specs, workflow steps the kit's reusable workflows already do, and gaps in the kit itself, each with file:line evidence or a measured value and a triage (KIT, KIT-GENERIC, PLUGIN-ONLY, KNOWN). Use it for "audit this plugin against the kit", "what can we still take from opdk", "what did the migration miss", or a review after a kit upgrade. Not for moving a plugin onto the kit in the first place (build, scanner, e2e, demo, unit, release skills) or for one failing command.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opdk audit
|
|
7
|
+
|
|
8
|
+
Two phases with a stop between them. Phase 1 reads and measures and changes nothing. The author picks items from its report. Phase 2 does only those items, one branch per coherent change. When the author wants an audit only, phase 1 ends with backlog-ready items instead of branches.
|
|
9
|
+
|
|
10
|
+
The plugin must already build, scan, test and release through the kit. If it does not, say so and stop: that is a migration, not an audit.
|
|
11
|
+
|
|
12
|
+
## Safety
|
|
13
|
+
|
|
14
|
+
- Never start the Obsidian app or binary yourself, not even `--version`: it opens the user's real config and last vault and runs their plugins. Read the version from the app bundle (`Info.plist` on macOS, `resources/app.asar` `package.json`). Obsidian runs only through the kit's e2e fixture, which uses a temp vault and user-data dir.
|
|
15
|
+
- No `opdk build --vault` into a real vault. If the shell exports a vault path the plugin's scripts read, unset it for every command (`env -u NAME`).
|
|
16
|
+
- Work in a separate worktree. Never change the main clone's remotes, branches or config. If the repo has git hooks that write outside it, pass `git -c core.hooksPath=<empty dir>` on every command that checks out files or commits (read-only git runs no hooks). Never `git config` from a worktree: it writes the main clone's shared config.
|
|
17
|
+
- Never `git stash`, `git checkout` or `git reset` over uncommitted work. Do not kill processes or interrupt e2e. Never delete shared temp globs such as `opdk-e2e-*`: every plugin on the kit uses that prefix, and another run may be live.
|
|
18
|
+
- Tests never reach real services. Use the plugin's fakes; a live mode stays behind its own opt-in variable.
|
|
19
|
+
- Kit findings are reported, never edited from the plugin's repo.
|
|
20
|
+
|
|
21
|
+
## Phase 1: read
|
|
22
|
+
|
|
23
|
+
Read in full: the plugin's `CLAUDE.md` or `AGENTS.md`, `CONTRIBUTING.md` and backlog if present (a local-only backlog may be missing from a worktree: ask where it is or skip it), the `[Unreleased]` section of `CHANGELOG.md`, `package.json` scripts, `opdk.config.*`, the workflows, fixtures, the unit config and test helpers. Read the kit's backlog or issue list, so items already filed are marked KNOWN instead of raised again.
|
|
24
|
+
|
|
25
|
+
From the kit's docs at the pinned tag, read in full the e2e helpers table, demo stills, presets and checks, the unit options and known mock gaps, and the inputs of the reusable workflows. Skim the build, scanner and release internals.
|
|
26
|
+
|
|
27
|
+
For specs, grep before reading: fixed sleeps (`waitForTimeout`, `setTimeout`), casts to reach Obsidian internals (`as unknown as`, `globalThis`), `evaluate(` and raw `keyboard.press(`, then read each hit in context. Grep the site and README tooling; do not read it unless a finding points there.
|
|
28
|
+
|
|
29
|
+
Check the plugin's own claims about the kit against the kit: in the CHANGELOG, the last migration PR's body, and any updated local docs a migration left for the author to apply (diff those against the live file).
|
|
30
|
+
|
|
31
|
+
## Phase 1: measure
|
|
32
|
+
|
|
33
|
+
Reading alone misses most picture, coverage and test-isolation findings. Run each once. In zsh, unquoted `$args` do not split: write measurement loops as a bash script or use arrays.
|
|
34
|
+
|
|
35
|
+
- **Gates, warm.** typecheck, lint, unit with coverage, build, `opdk scan`, `opdk release check`, and every other check the plugin's own CI runs. Time the second run, not the first.
|
|
36
|
+
- **Coverage over all of `src`.** Run the unit suite with coverage over every source file and thresholds at 0. A command-line `--coverage.exclude` replaces the config's list, so pass the base excludes (`**/*.test.ts`, `src/test/**`, `**/*.d.ts`) explicitly. Compare the totals with the gate: an exclusion the gate does not need is a finding.
|
|
37
|
+
- **Tests type-check.** A scratch tsconfig that includes the test files (with `typeRoots` pointing into the plugin's `node_modules`): count the errors and look for imports that resolve to the built `main.js`, which types the plugin as `any`.
|
|
38
|
+
- **Shared-worker runs.** If the suite is slow, time `vitest run --no-isolate`. Then, before calling it safe, run it on ONE worker in default order and with a few shuffled seeds (`--maxWorkers=1 --sequence.shuffle --sequence.seed=N`). On many workers each worker gets a few files and leaks between files hide; CI runners have two to four cores. Report failures, never the speed alone.
|
|
39
|
+
- **Pictures.** For every image in the screens, listing and site folders: pixel size (`sips -g pixelWidth -g pixelHeight` or `identify`), a hash for duplicates, and a grep of README, site and listing sources for which files are used. Record who makes each one (a kit `demo.still` or film, a plugin script, a composer that reads other pictures, or nothing in the repo). Find every script that reads the screens folder and what pixel density it assumes. Check each `width`/`height` attribute against its file's aspect ratio (display sizes, not pixel sizes) and each alt text against what the picture shows.
|
|
40
|
+
- **Films.** A contact sheet per GIF that always includes the last frame (the loop seam is at the end), and look at it for cut-off modals, a stray cursor, a moving clock, private data and a stale UI:
|
|
41
|
+
```bash
|
|
42
|
+
N=$(ffprobe -v error -count_frames -select_streams v:0 -show_entries stream=nb_read_frames -of csv=p=0 film.gif)
|
|
43
|
+
K=$(( (N + 14) / 15 )); LAST=$(( N - 1 )) # at most 15 frames plus the last fit the 4x4 grid
|
|
44
|
+
ffmpeg -v error -y -i film.gif -vf "select='not(mod(n\,$K))+eq(n\,$LAST)',scale=320:-1,tile=4x4" -fps_mode vfr -frames:v 1 sheet.png
|
|
45
|
+
```
|
|
46
|
+
- **e2e timings.** Do not run e2e, films or `opdk demo` in phase 1. Use the last Playwright report or the migration log; compare wall time with the summed test time (a suite that spends most of its time launching Obsidian is a finding).
|
|
47
|
+
- **A second plugin.** A KIT-GENERIC claim needs two plugins. A read-only grep in a sibling plugin checkout is allowed; name the file.
|
|
48
|
+
|
|
49
|
+
## Phase 1: what to look for
|
|
50
|
+
|
|
51
|
+
1. **Still hand-made.** Fixed sleeps where `obsidian.settle()` or a wait on what the test asserts fits; own settings, command, editor, IME, mobile, theme or notice helpers next to the e2e helpers; own Obsidian launchers outside the fixture; own DOM polyfills or Vitest config; own scripts next to an `opdk` command; lint rules the kit's preset dropped that the plugin used to enforce.
|
|
52
|
+
2. **Pictures and films.** Pictures nothing can retake, at mixed density, with window chrome, on a moving date, showing private data or a stale UI; films that drift from their narration or captions; files nobody embeds; text around a picture (alt, captions, guide steps, generated pages) that describes a screen which no longer exists.
|
|
53
|
+
3. **Test gaps.** Files outside the coverage gate, UI the unit mocks or e2e helpers now make testable, untyped or unlinted tests, order-dependent tests, slow or launch-bound specs, specs that do not test what their name says.
|
|
54
|
+
4. **Release and CI.** Steps the plugin's workflows or scripts still duplicate, kit workflow inputs it should set, kit pins (tag, lockfile, workflow SHAs) that do not name one commit, a missing Dependabot config.
|
|
55
|
+
5. **Kit gaps.** What the plugin needs that the kit lacks, gets wrong or documents wrongly.
|
|
56
|
+
|
|
57
|
+
## Phase 1: report
|
|
58
|
+
|
|
59
|
+
One section per module. A module with nothing to report gets one line, not an empty table. Otherwise a table: finding, evidence (file:line or the measured value), proposed change, effort (S/M/L), risk. Mark the findings a user of the plugin would notice.
|
|
60
|
+
|
|
61
|
+
Triage every finding:
|
|
62
|
+
- **KIT**: a kit bug or a false statement in its docs.
|
|
63
|
+
- **KIT-GENERIC**: needed by two or more plugins (name them), or plain Obsidian behaviour. A one-plugin case that looks generic is a "KIT-GENERIC candidate".
|
|
64
|
+
- **PLUGIN-ONLY**: this plugin's own work.
|
|
65
|
+
- **KNOWN**: already in the kit's backlog; give its id, and "now N plugins" when this plugin adds one.
|
|
66
|
+
|
|
67
|
+
End with numbered questions the author can answer in a word, then either suggested batches (one branch each) or, for an audit only, backlog-ready items (area, size, priority, one line each). Stop there.
|
|
68
|
+
|
|
69
|
+
## Phase 2: do the chosen items
|
|
70
|
+
|
|
71
|
+
- One branch per batch, named and titled by the plugin's conventions; every change listed in the plugin's CHANGELOG. Nothing changes silently.
|
|
72
|
+
- **Retaken pictures.** Freeze the date (`demo.freezeTime`), keep the composers that read the stills working at the new density, and show a contact sheet, old next to new, before committing; commit pictures only on the author's yes. Name what changes in the look, not only the density (a clean UI may drop a title or widen the content), and check the crop at the edges. In the same branch update every place that describes them: `width`/`height` ratios, alt texts, captions, guide steps, CHANGELOG sizes. Fix generated pages in their generator, then run its check.
|
|
73
|
+
- **Shared-worker runs.** Turn `isolate` off only after the one-worker runs above are green; fix the leaks first (mocks of modules another file already loaded, locales, globals, DOM left behind).
|
|
74
|
+
- **New tests** must test behaviour: break the code on purpose a few times and report that the tests fail. Restore from a backup copy, never with git.
|
|
75
|
+
- **Gates** before each PR: typecheck, lint, unit with the coverage gate, build, `opdk scan`, `opdk release check`, and every check of the plugin's own CI. Run the full e2e once at the end of the batch. In a worktree, check that the e2e config finds sibling plugins it loads (relative paths break there).
|
|
76
|
+
- **PRs.** One per batch. Before pushing a follow-up commit, check the PR is still open; if it was merged, the follow-up is a new PR. Merge, tag or release only when the author says so.
|
|
77
|
+
- **Directory pictures.** A community directory listing is not updated by a merge. Tell the author which files changed and that the listing needs a manual upload, or do it in the author's signed-in browser only when asked. A site that deploys on a published release needs a manual run to show new pictures before then.
|
|
78
|
+
|
|
79
|
+
## End of each phase
|
|
80
|
+
|
|
81
|
+
Phase 1: the report, the questions, the batches or backlog items. Phase 2: branches, PR URLs, gate results, the deliberate failures and how the tests caught them, and what is left for the author (listing upload, site deploy, release, a phone check).
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: build
|
|
3
|
+
description: Build, bundle or watch an Obsidian plugin that uses obsidian-plugin-dev-kit (opdk) with `opdk build`, `opdk build-css`, `opdk assert-bundle` or `opdk build --vault`. Use it when the build or the bundle check fails, when a plugin works on desktop but breaks on mobile ("process is not defined", Node-only code in main.js), or when replacing a plugin's own esbuild, build-css or build-vault scripts. Not for lint or scorecard warnings (scanner), tagging and publishing a release (release), Playwright specs (e2e) or films and screenshots (demo).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# opdk build module
|
|
7
|
+
|
|
8
|
+
Run all commands from the plugin root. The plugin id and name always come from `manifest.json`. Full docs: `node_modules/obsidian-plugin-dev-kit/docs/build.md`
|
|
9
|
+
|
|
10
|
+
## Commands
|
|
11
|
+
|
|
12
|
+
- `opdk build`: CSS, then esbuild, then the bundle check. Exits 1 on esbuild errors or a failed check.
|
|
13
|
+
- `opdk build --vault [dir]` (also `--vault=<dir>`): unminified `main.js` in `dir` (default `$VAULT_PLUGIN`), then rebuilds `styles.css` and copies `styles.css` and `manifest.json` there. No bundle check. Without `dir` and `VAULT_PLUGIN` it fails and prints the example with the plugin id. With `build.css: false` it copies a `styles.css` from the plugin root if there is one.
|
|
14
|
+
- Caution: `VAULT_PLUGIN` is usually exported in your shell and points at a real dev vault. The command logs `vault target <dir> (from --vault | from VAULT_PLUGIN)` and refuses (exit 1, nothing written) a `dir` whose `manifest.json` holds another plugin id. `--force` overrides that. It also refuses a `dir` that resolves to the plugin root or starts with `~` (not expanded), even with `--force`. When testing or demoing, pass an explicit temp dir or run with `env -u VAULT_PLUGIN`; never use `--force` against a real vault.
|
|
15
|
+
- `opdk build --vault [dir] --watch`: the same, rebuilt on changes to the sources, the CSS entry and every file it imports (polled every 300 ms), and `manifest.json`. If the CSS entry is missing at start it prints `no <entry>, CSS not watched` once. Ctrl+C stops it. `opdk.config.mjs` is read once, so restart watch after editing it. `--watch` without `--vault` is an error.
|
|
16
|
+
- `opdk build-css`: only the CSS step. Exits 1 when the CSS entry does not exist. With `css: false` it prints that CSS is disabled and exits 0.
|
|
17
|
+
- `opdk assert-bundle [file]`: only the check. `file` defaults to the build outfile.
|
|
18
|
+
|
|
19
|
+
## Not configurable
|
|
20
|
+
|
|
21
|
+
Platform `browser`, format `cjs`, the footer `module.exports = module.exports.default || module.exports;`, externals `obsidian`, `electron`, `@codemirror/state`, `@codemirror/view`.
|
|
22
|
+
|
|
23
|
+
## Config (`opdk.config.mjs`, `build` section, all optional)
|
|
24
|
+
|
|
25
|
+
| Key | Default |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `entry` | `src/main.ts` |
|
|
28
|
+
| `outfile` | `main.js` |
|
|
29
|
+
| `minify` | `true` |
|
|
30
|
+
| `target` | `es2020` |
|
|
31
|
+
| `external` | `[]` (added to the externals above) |
|
|
32
|
+
| `loader` | `{ ".css": "text" }`; your entries merge over it, for example `{ ".png": "dataurl" }` |
|
|
33
|
+
| `css` | `{ entry: "src/styles/main.css", outfile: "styles.css" }`, or `false` to skip. |
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
import { defineConfig } from "obsidian-plugin-dev-kit";
|
|
37
|
+
export default defineConfig({ build: { loader: { ".png": "dataurl" } } });
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
If the CSS entry does not exist (a hand-written CSS script may fail with ENOENT here), `opdk build` prints a `·` line "no src/styles/main.css, keeping styles.css as is" (once per `--watch` run) and keeps a hand-written `styles.css`; with no `styles.css` either it prints `!` and the plugin ships no stylesheet. A plugin with only a hand-written `styles.css` can set `css: false` to skip the step. Watch survives a compile error or a broken CSS `@import` and recovers when the file is fixed or a missing `@import` target is created. A missing `@import` or an import cycle in CSS is an error naming the files.
|
|
41
|
+
|
|
42
|
+
## The mobile-bundle failure
|
|
43
|
+
|
|
44
|
+
Phones have no Node: no `process`, `require("node:...")`, `__dirname`. Desktop Obsidian does, so a bundle with Node-only code works on the developer's machine and fails on mobile. Usually it comes from esbuild running with `--platform=node`, which picks the `node` branch of a dependency's `exports` map (this is how a plugin broke on every phone with `yaml`).
|
|
45
|
+
|
|
46
|
+
`opdk build` ends with the check. A failure looks like this:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
✗ bundle main.js cannot run on mobile:
|
|
50
|
+
- a `process` reference: "process.env"
|
|
51
|
+
- `LOG_TOKENS`, which only the Node build of a dependency contains
|
|
52
|
+
Check the esbuild platform: an Obsidian plugin bundles as `browser`.
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The `✗` marks the step that failed (it is on stderr, and the exit code is 1); the last line is the hint. Read the lines with `✓` above it as steps that passed. Colour appears in a terminal, with `FORCE_COLOR` (except `0` and `false`), or on GitHub Actions; a non-empty `NO_COLOR` or `TERM=dumb` (without `FORCE_COLOR`) turns it off, and in a plain log you read the same symbols without it. Do not parse this text, use the exit code.
|
|
56
|
+
|
|
57
|
+
How to read it:
|
|
58
|
+
|
|
59
|
+
- A `process` / `node:` / `__dirname` line means the bundle reaches for Node. Find which dependency: search `main.js` for the text, or bundle without minify (`build.minify: false`) and read around the match.
|
|
60
|
+
- A marker line (`LOG_TOKENS`, `LOG_STREAM`, `emitWarning`) means a dependency's Node build got in. Check that nothing sets the platform to `node` (old scripts, `esbuild.config.mjs`), that the dependency has a `browser` or `default` export condition, or replace it.
|
|
61
|
+
- If the plugin really is desktop only, set `"isDesktopOnly": true` in `manifest.json`; the check is then skipped.
|
|
62
|
+
|
|
63
|
+
## Migrating a plugin's build scripts
|
|
64
|
+
|
|
65
|
+
1. `npm install --save-dev github:Dimagious/obsidian-plugin-dev-kit#v0.3.2` (pin an exact tag).
|
|
66
|
+
2. Replace the scripts:
|
|
67
|
+
|
|
68
|
+
| Before | After |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `"build": "npm run build:css && esbuild src/main.ts --bundle ... && node scripts/assert-bundle.cjs"` | `"build": "opdk build"` |
|
|
71
|
+
| `"build": "esbuild src/main.ts --bundle ... --loader:.png=dataurl ..."` (a bundle with no CSS build) | `"build": "opdk build"` plus `build: { loader: { ".png": "dataurl" } }` in `opdk.config.mjs`; no `src/styles` is fine; with a hand-written `styles.css` you can add `css: false` |
|
|
72
|
+
| `"build:vault": "node scripts/build-vault.cjs"` / `"dev:vault": "... --watch"` | `"build:vault": "opdk build --vault"`, `"dev:vault": "opdk build --vault --watch"` |
|
|
73
|
+
| `"build:css": "node scripts/build-css.cjs"` | `"build:css": "opdk build-css"` |
|
|
74
|
+
|
|
75
|
+
3. Delete `scripts/assert-bundle.cjs`, `scripts/build-css.cjs` and `scripts/build-vault.cjs` only when nothing else requires them. Run `grep -rn "assert-bundle\|build-css\|build-vault" scripts/ package.json` first. A preview script that requires `build-css.cjs` (`npm run preview`, `preview:watch`) is one case, and the kit exports no programmatic CSS build, so keep `build-css.cjs` while another script requires it, or change that script to spawn `opdk build-css`.
|
|
76
|
+
4. Differences to expect: the build minifies by default (if your esbuild command has no `--minify`, set `minify: false` or check the output first), platform is always `browser` (a script that passed `node` changes the bundle), and no plugin id is hardcoded in a script because the id is read from `manifest.json`. A vault build that copied the root `styles.css` is replaced by one that rebuilds it from `src/styles` on every sync, so do not hand-edit the root file during `dev:vault`.
|
|
77
|
+
5. If your current `main.js` fails the bundle check (`LOG_TOKENS`, `LOG_STREAM`, `emitWarning`, from `--platform=node` plus `yaml`), it passes with the kit because the platform becomes `browser`, which swaps in yaml's browser build. That is a runtime change: smoke-test the migrated plugin on a phone.
|
|
78
|
+
6. If a plugin script still calls esbuild directly (a preview script, for example), keep its `esbuild` devDependency at the version the kit pins (0.28.2); drop the `esbuild` devDependency once no script calls it directly (`opdk build` brings its own).
|
|
79
|
+
7. Run `opdk build` and test the plugin in Obsidian before releasing.
|