Migrate to Vue 3

.editorconfig

@@ -1,15 +1,8 @@
-# This source file is part of the Swift.org open source project
-#
-# Copyright (c) 2021 Apple Inc. and the Swift project authors
-# Licensed under Apache License v2.0 with Runtime Library Exception
-#
-# See https://swift.org/LICENSE.txt for license information
-# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
-
-[*.{js,jsx,ts,tsx,vue,scss}]
-indent_style = space
+[*.{js,jsx,mjs,cjs,ts,tsx,mts,cts,vue,css,scss,sass,less,styl}]
+charset = utf-8
 indent_size = 2
-end_of_line = lf
-trim_trailing_whitespace = true
+indent_style = space
 insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf
 max_line_length = 100

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.gitignore

@@ -6,30 +6,52 @@
 # See https://swift.org/LICENSE.txt for license information
 # See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 
-.DS_Store
-node_modules
-/dist
-/docs
-/tmp
-
-# local env files
-.env.local
-.env.*.local
-
-# Log files
+# Logs
+logs
+*.log
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.DS_Store
+dist
+dist-ssr
+coverage
+*.local
 
 # Editor directories and files
+.vscode/*
+!.vscode/extensions.json
 .idea
-.vscode
 *.suo
 *.ntvs*
 *.njsproj
 *.sln
-*.sw*
+*.sw?
+
+*.tsbuildinfo
+
+.eslintcache
+
+# Cypress
+/cypress/videos/
+/cypress/screenshots/
+
+# Vitest
+__screenshots__/
+
+# Vite
+*.timestamp-*-*.mjs
+
+# local env files
+.env.local
+.env.*.local
 
 __pycache__
 
 .docc-build
+/docs
+/tmp

.nvmrc

@@ -1 +1 @@
-22.17.0
+24

.oxlintrc.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "ignorePatterns": [
+    "coverage/**",
+    "dist/**",
+    "docs/**",
+    "node_modules/**",
+    "tmp/**"
+  ],
+  "plugins": ["eslint", "unicorn", "oxc", "vue", "vitest"],
+  "env": {
+    "browser": true,
+    "node": true
+  },
+  "categories": {
+    "correctness": "error"
+  },
+  "rules": {
+    "no-unused-vars": "off",
+    "unicorn/no-thenable": "off",
+    "vitest/expect-expect": "off",
+    "vitest/no-conditional-expect": "off",
+    "vitest/require-to-throw-message": "off",
+    "vitest/valid-expect": "off",
+    "vitest/valid-title": "off",
+    "vue/no-reserved-component-names": "off"
+  }
+}

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "Vue.volar",
+    "vitest.explorer",
+    "dbaeumer.vscode-eslint",
+    "EditorConfig.EditorConfig",
+    "oxc.oxc-vscode"
+  ]
+}

CONTRIBUTING.md

@@ -50,8 +50,8 @@ more details.
 
 ### Run Steps
 
-> Note: requires [Node.js](https://nodejs.org/en/download/) v18
-> and [npm](https://www.npmjs.com/package/npm) v9.5. An easy way to set these up is to install
+> Note: requires [Node.js](https://nodejs.org/en/download/) v24
+> and [npm](https://www.npmjs.com/package/npm) v11.19. An easy way to set these up is to install
 > [nvm](https://github.com/nvm-sh/nvm) and run `nvm install` from within the Swift-DocC-Render
 > repository. To use these versions as the default, add `--default` to the installation command.
 
@@ -73,15 +73,15 @@ more details.
     npm install
     ```
 
-4. Run a local server with hot reload at [localhost:8080](http://localhost:8080/)
+4. Run a local server with hot reload at [localhost:5173](http://localhost:5173/)
 
     You may want to set an http endpoint as a proxy to handle data requests while developing locally.
 
     ```shell
-    VUE_APP_DEV_SERVER_PROXY=https://localhost:8000 npm run serve
+    VITE_DEV_SERVER_PROXY=https://localhost:8000 npm run dev
     ```
 
-    As an alternative you can just create a `.env.development.local` file on the root of the project to add the `VUE_APP_DEV_SERVER_PROXY` env varible so you don't have to set it in the `npm run serve` script each time.
+    As an alternative you can just create a `.env.development.local` file on the root of the project to add the `VITE_DEV_SERVER_PROXY` environment variable so you don't have to set it in the `npm run dev` script each time.
 
 ### Build Steps
 
@@ -149,7 +149,7 @@ Before opening a pull request, we ask that you:
 ### Tests and linting
 
 Run the following script to:
-- Run unit tests with [Jest](https://jestjs.io/)
+- Run unit tests with [Vitest](https://vitest.dev/)
 - Find syntax errors with [ESLint](https://eslint.org/)
 - Check that all files have license headers
 

NOTICE.txt

@@ -39,15 +39,6 @@ This product depends on vue-router.
 
 ---
 
-This product depends on core-js.
-
-  * LICENSE (MIT):
-    * https://github.com/zloirock/core-js/blob/master/LICENSE
-  * HOMEPAGE:
-    * https://github.com/zloirock/core-js
-
----
-
 This product depends on Highlight.js.
 
   * LICENSE (BSD-3-Clause):
@@ -57,15 +48,6 @@ This product depends on Highlight.js.
 
 ---
 
-This product depends on the IntersectionObserver polyfill.
-
-  * LICENSE (W3C Software and Document):
-    * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document
-  * HOMEPAGE:
-    * https://github.com/w3c/IntersectionObserver/tree/main/polyfill
-
----
-
 This product depends on PortalVue.
 
   * LICENSE (MIT):

README.md

@@ -7,8 +7,8 @@ SPAs are web apps that render dynamically at runtime entirely in the browser, us
 
 ## Getting Started
 
-> Note: requires [Node.js](https://nodejs.org/en/download/) v22.17.0
-> and [npm](https://www.npmjs.com/package/npm) v10.9.2. An easy way to set these up is to install
+> Note: requires [Node.js](https://nodejs.org/en/download/) v24.12.0
+> and [npm](https://www.npmjs.com/package/npm) v11.19. An easy way to set these up is to install
 > [nvm](https://github.com/nvm-sh/nvm) and run `nvm install` from within the Swift-DocC-Render
 > repository. To use these versions as the default, add `--default` to the installation command.
 
@@ -25,15 +25,26 @@ SPAs are web apps that render dynamically at runtime entirely in the browser, us
     npm install
     ```
 
-3. **Run a local server with hot reload at [localhost:8080](http://localhost:8080/)**
+3. **Run a local server with hot reload at [localhost:5173](http://localhost:5173/)**
 
-    You may want to set a proxy to handle data requests while developing locally by setting the VUE_APP_DEV_SERVER_PROXY env variable to a documentation archive (.doccarchive or .docc-build) on your disk or served in a HTTP endpoint:
+    You may want to set a proxy to handle data requests while developing locally by setting the VITE_DEV_SERVER_PROXY environment variable to a documentation archive (.doccarchive or .docc-build) on your disk or served at an HTTP endpoint:
 
     ```shell
-    VUE_APP_DEV_SERVER_PROXY=[path to documentation archive] npm run serve
+    VITE_DEV_SERVER_PROXY=[path to documentation archive] npm run dev
     ```
 
-    As an alternative you can just create a `.env.development.local` file on the root of the project to add the `VUE_APP_DEV_SERVER_PROXY` env variable so you don't have to set it in the `npm run serve` script each time.
+    As an alternative you can just create a `.env.development.local` file on the root of the project to add the `VITE_DEV_SERVER_PROXY` env variable so you don't have to set it in the `npm run dev` script each time.
+
+    `SwiftDocCRender.docc` is a source catalog, not a rendered documentation archive.
+    To use this repository's documentation while developing the renderer, generate its
+    data first and open the documentation route rather than the site root:
+
+    ```shell
+    npm run docs:build
+    VITE_DEV_SERVER_PROXY=docs npm run dev
+    ```
+
+    Then visit [localhost:5173/documentation/swiftdoccrender](http://localhost:5173/documentation/swiftdoccrender).
 
 ## Using Swift-DocC-Render to render documentation
 

SwiftDocCRender.docc/contributing/Internals.md

@@ -146,13 +146,13 @@ If you need access to a global mixin or var, from `_core.scss` you have to impor
 
 #### Unit tests
 
-DocC-Render is unit tested, using the [Jest](https://jestjs.io/) testing framework. All components and utilities strive to have a corresponding test file inside the  `tests` folder, mirroring the file's location.
+DocC-Render is unit tested using the [Vitest](https://vitest.dev/) testing framework. All components and utilities strive to have a corresponding test file inside the `tests` folder, mirroring the file's location.
 
 Unit tests can be run via:
 
-* `npm run test:unit`  - run all unittests
+* `npm run test:unit`  - run all unit tests
 * `npm run test:unit:watch`  - run only the modified files and watch for changes
-* `npx run test:unit tests/unit/path/to/spec.js`  - run an individual test file
+* `npm run test:unit tests/unit/path/to/spec.js`  - run an individual test file
 
 #### Code style
 
@@ -166,23 +166,23 @@ To automatically fix any error, run:
 
 `npm run lint:fix`
 
-If you use the development server via `npm run serve`, files are linted on each change. Read more about configuring your linter [here](https://cli.vuejs.org/core-plugins/eslint.html#configuration).
+Read more about configuring the linter in the [ESLint configuration documentation](https://eslint.org/docs/latest/use/configure/).
 
 #### Environment flags
 
-DocC-Render has a few build-time environment flags, that allow you to set configuration parameters before building. Read [How to set Environment Variables in Vue CLI](https://cli.vuejs.org/guide/mode-and-env.html#environment-variables).
+DocC-Render has a few build-time environment flags that allow you to set configuration parameters before building. Read [Vite's environment variable documentation](https://vite.dev/guide/env-and-mode.html).
 
 **List of env variables:**
 
-* **VUE_APP_DEV_SERVER_PROXY** - The HTTP endpoint or  local filepath to read render JSON from when using the development server
-* **VUE_APP_TITLE** - An optional default page title to apply to pages
-* **VUE_APP_HLJS_LANGUAGES** - An optional comma-separated list of highlight.js languages to include in the build
+* **VITE_DEV_SERVER_PROXY** - The HTTP endpoint or local filepath to read render JSON from when using the development server
+* **VITE_APP_TITLE** - An optional default page title to apply to pages
+* **VITE_APP_HLJS_LANGUAGES** - An optional comma-separated list of highlight.js languages to include in the build
 
 #### Available Scripts
 
 These are the most commonly used npm scripts you would need to develop DocC-Render:
 
-* **serve** - used while developing DocC-Render or a theme. Starts up a custom live-reloading server, which serves a local DocC-Render instance.
+* **dev** - used while developing DocC-Render or a theme. Starts up a custom live-reloading server, which serves a local DocC-Render instance.
 * **build** - builds DocC-Render, in a state ready for `docc`.
 * **test** - run the entire DocC-Render test suite.
 * **lint** - run the linter, to check for code styling errors.