docs: add a section about augmenting types with TS project references #32843
Conversation
|
|
WalkthroughThe documentation has been updated to clarify the handling of TypeScript type augmentation files in Nuxt 4 projects using project references. The upgrade guide now includes an explicit step instructing users to relocate type augmentation files into the appropriate directories ( Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
docs/1.getting-started/18.upgrade.md (1)
1074-1108: Fix ordered-list numbering & trailing whitespace – breaks CI
markdownlint(see pipeline failure) rejects the current numbering after the warning box: the list restarts but continues with5.and6.instead of1./2., and there’s stray trailing spaces at Line 1074.- ```diff - - "typecheck": "nuxt prepare && vue-tsc --noEmit" - + "typecheck": "nuxt prepare && vue-tsc -b --noEmit" - ``` - -4. **Move all type augmentations into their appropriate context**: + ```diff + - "typecheck": "nuxt prepare && vue-tsc --noEmit" + + "typecheck": "nuxt prepare && vue-tsc -b --noEmit" + ``` + +4. **Move all type augmentations into their appropriate context**: @@ -5. **Configure Node.js TypeScript options** if needed: +1. **Configure Node.js TypeScript options** if needed: @@ -6. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach. +2. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.Changes applied:
- Removes two trailing spaces after the code-block fence (MD009).
- Keeps Step 4 intact, then restarts numbering at
1./2.to comply with MD029ol-prefix.This should make
autofix.cihappy and unblock the pipeline.
🧹 Nitpick comments (1)
docs/2.guide/1.concepts/8.typescript.md (1)
111-126: Tighten copy & fix markdown-lint issues in the new augmentation sectionMinor wording / formatting tweaks will silence the current markdown-lint/LanguageTool warnings and make the text a little crisper.
-### Augmenting Types with Project References - -Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they are properly recognized. +### Augmenting Types with Project References + +Because a Nuxt project is split into **multiple type contexts**, you must **augment types in the correct context** so that TypeScript can detect them. -For example, if you want to augment types for the `app` context, the augmentation file should be placed in the `app/` directory. +For example, to augment types for the `app` context, place the augmentation file in the `app/` directory. -Similarly: -- For the `server` context, place the augmentation file in the `server/` directory. -- For types that are **shared between the app and server**, place the file in the `shared/` directory. +Similarly: +* For the **server** context, place the file in the `server/` directory. +* For types **shared** between app and server, place the file in the `shared/` directory. ::warning -Augmenting types outside of these directories will not be recognized by TypeScript. +Augmenting types outside these directories will not be recognised by TypeScript. :: - -This:
- Removes redundant “of”, tightens sentences.
- Switches dash lists to asterisk to match repo style.
- Clears double blank lines and trailing spaces that trigger MD009/MD012.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/1.getting-started/18.upgrade.md(2 hunks)docs/2.guide/1.concepts/8.typescript.md(1 hunks)
🧰 Additional context used
🧠 Learnings (8)
📓 Common learnings
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.{ts,tsx} : Follow standard TypeScript conventions and best practices
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.vue : Use `<script setup lang="ts">` and the composition API when creating Vue components
Learnt from: GalacticHypernova
PR: nuxt/nuxt#26468
File: packages/nuxt/src/components/plugins/loader.ts:24-24
Timestamp: 2024-11-05T15:22:54.759Z
Learning: In `packages/nuxt/src/components/plugins/loader.ts`, the references to `resolve` and `distDir` are legacy code from before Nuxt used the new unplugin VFS and will be removed.
Learnt from: GalacticHypernova
PR: nuxt/nuxt#29661
File: packages/kit/src/template.ts:227-229
Timestamp: 2024-11-28T21:22:40.496Z
Learning: In `packages/kit/src/template.ts`, when updating the `EXTENSION_RE` regular expression for TypeScript configuration, avoid using patterns like `(\.\w+)+$` as they can result in catastrophic backtracking.
Learnt from: TheAlexLichter
PR: nuxt/nuxt#31812
File: packages/nuxt/src/components/plugins/islands-transform.ts:202-202
Timestamp: 2025-04-18T18:33:41.753Z
Learning: In Nuxt, using `rolldownVersion` (not `rollupVersion`) is intentional when detecting if rolldown-vite is being used, even though TypeScript may show an error because the property isn't in standard type definitions yet.
📚 Learning: applies to **/*.{ts,tsx} : follow standard typescript conventions and best practices...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.{ts,tsx} : Follow standard TypeScript conventions and best practices
Applied to files:
docs/2.guide/1.concepts/8.typescript.mddocs/1.getting-started/18.upgrade.md
📚 Learning: ensure that ai-generated summaries accurately reflect the key changes in the pr, focusing on notable...
Learnt from: Tofandel
PR: nuxt/nuxt#0
File: :0-0
Timestamp: 2024-11-11T12:34:22.648Z
Learning: Ensure that AI-generated summaries accurately reflect the key changes in the PR, focusing on notable changes such as the removal of unused imports and variables starting with underscores.
Applied to files:
docs/2.guide/1.concepts/8.typescript.mddocs/1.getting-started/18.upgrade.md
📚 Learning: in `packages/kit/src/template.ts`, when updating the `extension_re` regular expression for typescrip...
Learnt from: GalacticHypernova
PR: nuxt/nuxt#29661
File: packages/kit/src/template.ts:227-229
Timestamp: 2024-11-28T21:22:40.496Z
Learning: In `packages/kit/src/template.ts`, when updating the `EXTENSION_RE` regular expression for TypeScript configuration, avoid using patterns like `(\.\w+)+$` as they can result in catastrophic backtracking.
Applied to files:
docs/2.guide/1.concepts/8.typescript.mddocs/1.getting-started/18.upgrade.md
📚 Learning: applies to **/*.vue : use `<script setup lang="ts">` and the composition api when creating vue compo...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.vue : Use `<script setup lang="ts">` and the composition API when creating Vue components
Applied to files:
docs/2.guide/1.concepts/8.typescript.mddocs/1.getting-started/18.upgrade.md
📚 Learning: applies to **/*.{test,spec}.{ts,tsx,js,jsx} : write unit tests for core functionality using `vitest`...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.{test,spec}.{ts,tsx,js,jsx} : Write unit tests for core functionality using `vitest`
Applied to files:
docs/2.guide/1.concepts/8.typescript.mddocs/1.getting-started/18.upgrade.md
📚 Learning: in nuxt, using `rolldownversion` (not `rollupversion`) is intentional when detecting if rolldown-vit...
Learnt from: TheAlexLichter
PR: nuxt/nuxt#31812
File: packages/nuxt/src/components/plugins/islands-transform.ts:202-202
Timestamp: 2025-04-18T18:33:41.753Z
Learning: In Nuxt, using `rolldownVersion` (not `rollupVersion`) is intentional when detecting if rolldown-vite is being used, even though TypeScript may show an error because the property isn't in standard type definitions yet.
Applied to files:
docs/1.getting-started/18.upgrade.md
📚 Learning: applies to **/e2e/**/*.{ts,js} : write end-to-end tests using playwright and `@nuxt/test-utils`...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/e2e/**/*.{ts,js} : Write end-to-end tests using Playwright and `@nuxt/test-utils`
Applied to files:
docs/1.getting-started/18.upgrade.md
🪛 LanguageTool
docs/2.guide/1.concepts/8.typescript.md
[uncategorized] ~120-~120: Loose punctuation mark.
Context: ...e the file in the shared/ directory. ::warning Augmenting types outside of the...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~122-~122: This phrase is redundant. Consider using “outside”.
Context: ... directory. ::warning Augmenting types outside of these directories will not be recognize...
(OUTSIDE_OF)
[uncategorized] ~122-~122: Loose punctuation mark.
Context: ...s will not be recognized by TypeScript. :: ## Strict Checks TypeScript comes ...
(UNLIKELY_OPENING_PUNCTUATION)
docs/1.getting-started/18.upgrade.md
[uncategorized] ~1079-~1079: Loose punctuation mark.
Context: ... the files to the shared/ directory. ::warning Augmenting types from outside t...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~1081-~1081: Loose punctuation mark.
Context: ... with the new project references setup. :: 5. **Configure Node.js TypeScript opt...
(UNLIKELY_OPENING_PUNCTUATION)
🪛 markdownlint-cli2 (0.17.2)
docs/2.guide/1.concepts/8.typescript.md
125-125: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
126-126: Multiple consecutive blank lines
Expected: 1; Actual: 3
(MD012, no-multiple-blanks)
docs/1.getting-started/18.upgrade.md
1074-1074: Trailing spaces
Expected: 0 or 2; Actual: 3
(MD009, no-trailing-spaces)
1076-1076: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
1077-1077: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
1078-1078: Unordered list style
Expected: asterisk; Actual: dash
(MD004, ul-style)
1084-1084: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/2/3
(MD029, ol-prefix)
1106-1106: Ordered list item prefix
Expected: 2; Actual: 6; Style: 1/2/3
(MD029, ol-prefix)
🪛 GitHub Actions: autofix.ci
docs/1.getting-started/18.upgrade.md
[error] 1084-1084: markdownlint MD029/ol-prefix: Ordered list item prefix incorrect. Expected prefix '1' but found '5'.
[error] 1106-1106: markdownlint MD029/ol-prefix: Ordered list item prefix incorrect. Expected prefix '2' but found '6'.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
docs/1.getting-started/18.upgrade.md (1)
1075-1083: Polish wording & admonition formatting for the new step
- “Augmenting types from outside…” → drop “from” – it reads more naturally as “Augmenting types outside…”.
- Nuxt content docs usually place a blank line after
::warningso the call-out renders correctly.
Without it the parser sometimes treats::warningas literal text.- ::warning - Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup. - :: + ::warning + + Augmenting types outside the `app/`, `server/`, or `shared/` directories will **not** work with the new project-references setup. + + ::docs/2.guide/1.concepts/8.typescript.md (1)
111-124: Minor wording and localisation tweaksBritish-English spelling and a tiny redundancy fix improve readability:
-::warning -Augmenting types outside of these directories will not be recognized by TypeScript. -:: +::warning + +Augmenting types outside these directories will not be recognised by TypeScript. + +::
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/1.getting-started/18.upgrade.md(2 hunks)docs/2.guide/1.concepts/8.typescript.md(1 hunks)
🧰 Additional context used
🧠 Learnings (9)
📓 Common learnings
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.{ts,tsx} : Follow standard TypeScript conventions and best practices
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.vue : Use `<script setup lang="ts">` and the composition API when creating Vue components
Learnt from: GalacticHypernova
PR: nuxt/nuxt#26468
File: packages/nuxt/src/components/plugins/loader.ts:24-24
Timestamp: 2024-11-05T15:22:54.759Z
Learning: In `packages/nuxt/src/components/plugins/loader.ts`, the references to `resolve` and `distDir` are legacy code from before Nuxt used the new unplugin VFS and will be removed.
Learnt from: GalacticHypernova
PR: nuxt/nuxt#29661
File: packages/kit/src/template.ts:227-229
Timestamp: 2024-11-28T21:22:40.496Z
Learning: In `packages/kit/src/template.ts`, when updating the `EXTENSION_RE` regular expression for TypeScript configuration, avoid using patterns like `(\.\w+)+$` as they can result in catastrophic backtracking.
Learnt from: TheAlexLichter
PR: nuxt/nuxt#31812
File: packages/nuxt/src/components/plugins/islands-transform.ts:202-202
Timestamp: 2025-04-18T18:33:41.753Z
Learning: In Nuxt, using `rolldownVersion` (not `rollupVersion`) is intentional when detecting if rolldown-vite is being used, even though TypeScript may show an error because the property isn't in standard type definitions yet.
📚 Learning: applies to **/*.{ts,tsx} : follow standard typescript conventions and best practices...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.{ts,tsx} : Follow standard TypeScript conventions and best practices
Applied to files:
docs/1.getting-started/18.upgrade.mddocs/2.guide/1.concepts/8.typescript.md
📚 Learning: applies to **/*.vue : use `<script setup lang="ts">` and the composition api when creating vue compo...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.vue : Use `<script setup lang="ts">` and the composition API when creating Vue components
Applied to files:
docs/1.getting-started/18.upgrade.mddocs/2.guide/1.concepts/8.typescript.md
📚 Learning: ensure that ai-generated summaries accurately reflect the key changes in the pr, focusing on notable...
Learnt from: Tofandel
PR: nuxt/nuxt#0
File: :0-0
Timestamp: 2024-11-11T12:34:22.648Z
Learning: Ensure that AI-generated summaries accurately reflect the key changes in the PR, focusing on notable changes such as the removal of unused imports and variables starting with underscores.
Applied to files:
docs/1.getting-started/18.upgrade.mddocs/2.guide/1.concepts/8.typescript.md
📚 Learning: in nuxt, using `rolldownversion` (not `rollupversion`) is intentional when detecting if rolldown-vit...
Learnt from: TheAlexLichter
PR: nuxt/nuxt#31812
File: packages/nuxt/src/components/plugins/islands-transform.ts:202-202
Timestamp: 2025-04-18T18:33:41.753Z
Learning: In Nuxt, using `rolldownVersion` (not `rollupVersion`) is intentional when detecting if rolldown-vite is being used, even though TypeScript may show an error because the property isn't in standard type definitions yet.
Applied to files:
docs/1.getting-started/18.upgrade.md
📚 Learning: in `packages/nuxt/src/components/plugins/loader.ts`, the references to `resolve` and `distdir` are l...
Learnt from: GalacticHypernova
PR: nuxt/nuxt#26468
File: packages/nuxt/src/components/plugins/loader.ts:24-24
Timestamp: 2024-11-05T15:22:54.759Z
Learning: In `packages/nuxt/src/components/plugins/loader.ts`, the references to `resolve` and `distDir` are legacy code from before Nuxt used the new unplugin VFS and will be removed.
Applied to files:
docs/1.getting-started/18.upgrade.mddocs/2.guide/1.concepts/8.typescript.md
📚 Learning: applies to **/*.{test,spec}.{ts,tsx,js,jsx} : write unit tests for core functionality using `vitest`...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/*.{test,spec}.{ts,tsx,js,jsx} : Write unit tests for core functionality using `vitest`
Applied to files:
docs/1.getting-started/18.upgrade.mddocs/2.guide/1.concepts/8.typescript.md
📚 Learning: applies to **/e2e/**/*.{ts,js} : write end-to-end tests using playwright and `@nuxt/test-utils`...
Learnt from: CR
PR: nuxt/nuxt#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-18T16:46:07.446Z
Learning: Applies to **/e2e/**/*.{ts,js} : Write end-to-end tests using Playwright and `@nuxt/test-utils`
Applied to files:
docs/1.getting-started/18.upgrade.md
📚 Learning: in `packages/kit/src/template.ts`, when updating the `extension_re` regular expression for typescrip...
Learnt from: GalacticHypernova
PR: nuxt/nuxt#29661
File: packages/kit/src/template.ts:227-229
Timestamp: 2024-11-28T21:22:40.496Z
Learning: In `packages/kit/src/template.ts`, when updating the `EXTENSION_RE` regular expression for TypeScript configuration, avoid using patterns like `(\.\w+)+$` as they can result in catastrophic backtracking.
Applied to files:
docs/1.getting-started/18.upgrade.mddocs/2.guide/1.concepts/8.typescript.md
🪛 LanguageTool
docs/1.getting-started/18.upgrade.md
[uncategorized] ~1080-~1080: Loose punctuation mark.
Context: ... files to the shared/ directory. ::warning Augmenting types from outsi...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~1082-~1082: Loose punctuation mark.
Context: ...h the new project references setup. :: 5. **Configure Node.js TypeScript opt...
(UNLIKELY_OPENING_PUNCTUATION)
docs/2.guide/1.concepts/8.typescript.md
[uncategorized] ~120-~120: Loose punctuation mark.
Context: ...e the file in the shared/ directory. ::warning Augmenting types outside of the...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~122-~122: This phrase is redundant. Consider using “outside”.
Context: ... directory. ::warning Augmenting types outside of these directories will not be recognize...
(OUTSIDE_OF)
[uncategorized] ~122-~122: Loose punctuation mark.
Context: ...s will not be recognized by TypeScript. :: ## Strict Checks TypeScript comes wi...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: lint-docs
🔗 Linked issue
resolves #32727
📚 Description
This adds a section about needing to augment types in the correct context with the new Project Referneces TS setup and also mentions it in the upgrade guide to Nuxt 4.
I wasn't able to able to get augmentations recognized outside the default contexts (i.e. in
/types/which would be in the same directory asnuxt.config.ts) by doing this:So I didn't mention it yet.
It did pick up the augmentations when I added the directory to
typescript.tsConfig.include- but if I'm not mistaken, that only includes it in theappcontext. It also didn't work when I tried defining it intypescript.sharedTsConfig.include.Is there something I'm missing? https://stackblitz.com/edit/github-1zim1ccd?file=project%2Fnuxt.config.ts