Migrate to Vue 3

[mchoo7]

Bug/issue #976 #977, if applicable:

Summary

As mentioned in #976, this project is currently using Vue 2. Not only this leaves bugs from dependencies (unless we patch against individual deps), using EOL-ed software leaves security holes that can be exploited in many ways, especially in these days where LLM can find dozens of security flaws in a few hours. After this change, pnpm outdated will show nothing (there is deprecated package warning from js-beautify, but it's not our responsibility).

Screenshot:

Notes

• For dependency-specific notes, see Dependencies section
• The best way to test this on your machine is 1) clone my fork and 2) run pnpm instsall && pnpm run docs
• Every JS scripts are now in ESM. package.json now sees .js files as ESM files not CJS. ("type": "module")
• The best way to review this work is reviewing commit-by-commit.
• 3a0c7d5 has patch for tree-sitter because of C++ build issue and they had problem with publishing 0.25.1 which had the fix. 0.25.1 was published after i made the commit, so the patch was reverted and tree-sitter was upgraded to 0.25.1.
• The copyright banner in .editorconfig is removed because 1) it's functionally identical to vue template and 2) I don't think it's creative enough to be copyrighted (I'm not a lawyer though).
• This patch was driven by GPT 5.6 Sol through Codex. I tried this migration three times by myself more than a year ago and failed. In February I tried again twice with Claude Opus 4.6, but failed. GPT did this work without much problem but this PR still needs to be reviewed cautiously.

Breaking Changes

For Users

There is no breaking changes for users at least according to the spec. The only pitfall here is the browerlist. Vite 8 has stricter browser compatibility then our current browserlist, but I'm pretty sure for generated code the old code is more compatible for (very) legacy browsers. For example, support for Internet Explorer is now fully dropped.

For Developers

• Node 24 (or 22, see Dependencies section) is required.
• pnpm is required. (good balance between niche features and stability)
• serve is renamed to dev to follow vite convention
• Default port for dev (previously serve) is now 5173 (vite's default)
• VUE_APP_* is now VITE_* (this is what vite expects)

Future plans

I will do the following:

• Remove some of the turned-off eslint rules
• Introduce prettier (from Vue 3 template)
• Introduce typescript (from Vue 3 template)

This PR is groundwork for the following optional improvements, but I won't or currently have no plan to do:

• Use Pinia (default store for Vue 3) for stores. However I don't know if Pinia is a good solution for this project.
• Introduce vapor mode for Vue 3.6 (requires rewrite in composition api, might not worth)
• SSG (probably through Nuxt), requires major architecture overhaul

Dependencies

• npm is replaced by pnpm
• Node 24 (latest lts) is now default. package.json will allow Node 22, but if your node version manager(s) read .nvmrc, they will complain about it because .nvmrc cannot store multiple major versions.
• jest is replaced by vitest
• babel is removed as it's not necessary anymore
• postcss and autoprefixer are removed (vite ships lightningcss by default)
• oxlint is added. eslint covers what oxlint can't yet (this is from Vue 3 template)
• Vue-related deps are upgraded for Vue 3
• intersection-observer is dropped
• Some eslint plugins are removed and added, mostly due to eslint 10 compatibility
• tree-sitter is upgraded to 0.25. tree-sitter-vue was dropped because it was Vue 2-only and @vue/compiler-sfc is added to replace its functionality.
• See diff for package.json for minor changes.

Testing

Invoking test is same as before, except that vitest is now the backend (it's easier to sync with vite and vue). However, changes to test files need to be reviewed for sure.

This needs to be tested with other documentations such as the Swift documentation or the Apple documentation. However, I don't know how to test against these and don't have time for that, so I hope Swift/Apple devs can do this for me.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran pnpm test, and it succeeded
• Updated documentation if necessary

Fixes: #976
Fixes: #977

[heckj]

Lots of lifting in this - I'm likely the last to provide useful feedback, but I went ahead and asked an LLM to look over the PR for any low-hanging fruit feedback that might help improve this if the DocC render maintainers are so inclined.

From that output:

• OverviewCard's "head" slot looks like it was dropped.
• BreakpointEmitter.spec.js looks like the test was gutted, not actually updated.
• The LLM asserted that Accessibility linting was added, then more or less shut down/neutered. My personal take is leaning more heavily into active linting to guide feedback on the migration, so from my point view, I'd re-enable all the base linting it disabled, and consider adding more were relevant, and let the agents churn on resolving and fixing.
• vitest expect-expect and valid-expect are apparently also disabled.

I stumbled over pnpm test not passing as well, but didn't dig into that detail at any level.

(note: I am not a maintainer on this project, more a very interested consumer of it)

[mchoo7]

OverviewCard's "head" slot looks like it was dropped.

I don't see any change made to OverviewCard.
https://github.com/mchoo7/swift-docc-render/blob/vue3/src/components/ContentNode/OverviewCard.vue

BreakpointEmitter.spec.js looks like the test was gutted, not actually updated.

Updated

The LLM asserted that Accessibility linting was added, then more or less shut down/neutered. My personal take is leaning more heavily into active linting to guide feedback on the migration, so from my point view, I'd re-enable all the base linting it disabled, and consider adding more were relevant, and let the agents churn on resolving and fixing.
vitest expect-expect and valid-expect are apparently also disabled.

I was going to do ESLint (and Prettier) in a follow-up PR.

I stumbled over pnpm test not passing as well, but didn't dig into that detail at any level.

I don't see any failures. Could you share the error message please?