docs: add typescript documentation for module authors #33637

cernymatej · 2025-11-02T22:02:01Z

📚 Description

This PR adds documentation for TS project references for module authors. I've also cleaned up the TS sections, removed duplicates, and hopefully made them more readable and easier to understand.

bolt-new-by-stackblitz · 2025-11-02T22:02:04Z

Run & review this pull request in StackBlitz Codeflow.

coderabbitai · 2025-11-02T22:04:29Z

Walkthrough

This pull request updates Nuxt documentation related to TypeScript configuration across four pages. Changes rename and clarify TypeScript option headings, replace generic app/server tsconfig references with explicit files (tsconfig.app.json, tsconfig.shared.json, tsconfig.node.json, tsconfig.server.json), add a Nitro TypeScript integration block (nitro.typescript.tsConfig) examples, and introduce a new "Extending TypeScript Configuration" section and hooks guidance for modules. The content shifts from file-specific imperative instructions toward broader, guideline-oriented explanations and consistent examples for per-context tsconfig customization. No functional code or public API declarations were changed.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Multiple docs across different sections with moderate logic density and new examples.
Heterogeneous edits (renaming, new sections, code snippets, hook guidance) require separate checks per file.

Areas requiring extra attention:

Consistent use of tsconfig filenames (tsconfig.app.json, tsconfig.shared.json, tsconfig.node.json, tsconfig.server.json) across all pages.
Accuracy of the nitro.typescript.tsConfig example and its placement in nuxt.config.ts snippets.
Correctness and clarity of the "Extending TypeScript Configuration" examples and module hook usage (prepare:types, nitro:prepare:types).
Cross-links, read-more/read-warning blocks and their contextual placement within each document.

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "docs: add typescript documentation for module authors" is directly related to the main changes in the changeset. The raw_summary shows that the PR updates multiple documentation files (upgrade.md, tsconfig.md, typescript.md, and modules.md) with a primary focus on adding TypeScript project references documentation and extending configuration guidance for module authors in modules.md. The title clearly captures this primary objective and follows conventional commit format with the "docs:" prefix. While the PR description mentions secondary objectives such as cleaning up and reorganising existing TypeScript sections, the title appropriately prioritises the main contribution (adding documentation for module authors).
Description Check	✅ Passed	The pull request description is clearly related to the changeset. The author states the PR "adds documentation for TS project references for module authors" and explains that they have "cleaned up the TS sections, removed duplicates, and made them more readable and easier to understand." This directly aligns with the raw_summary, which documents updates to TypeScript documentation across four files, including a new section on extending tsconfig.json for module authors and consolidation of TypeScript configuration guidance. The description is sufficiently specific and conveys meaningful information about the changeset.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 89f59b7 and 6e80dbc.

📒 Files selected for processing (4)

docs/1.getting-started/18.upgrade.md (1 hunks)
docs/2.guide/1.directory-structure/3.tsconfig.md (2 hunks)
docs/2.guide/2.concepts/8.typescript.md (1 hunks)
docs/2.guide/3.going-further/3.modules.md (2 hunks)

🧰 Additional context used

🧠 Learnings (7)

📓 Common learnings

Learnt from: CR
Repo: nuxt/nuxt PR: 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

📚 Learning: 2024-11-11T12:34:22.648Z

Learnt from: Tofandel
Repo: nuxt/nuxt PR: 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.md
docs/2.guide/2.concepts/8.typescript.md
docs/2.guide/1.directory-structure/3.tsconfig.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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.md
docs/2.guide/2.concepts/8.typescript.md
docs/2.guide/3.going-further/3.modules.md
docs/2.guide/1.directory-structure/3.tsconfig.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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.md
docs/2.guide/2.concepts/8.typescript.md
docs/2.guide/3.going-further/3.modules.md
docs/2.guide/1.directory-structure/3.tsconfig.md

📚 Learning: 2025-04-18T18:33:41.753Z

Learnt from: TheAlexLichter
Repo: nuxt/nuxt PR: 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/2.guide/2.concepts/8.typescript.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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/3.going-further/3.modules.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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/2.guide/3.going-further/3.modules.md

🪛 LanguageTool

docs/2.guide/2.concepts/8.typescript.md

[uncategorized] ~53-~53: Loose punctuation mark.
Context: ... ~/file, or #build/file, and more. ::warning Nuxt relies on this configurati...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~55-~55: Loose punctuation mark.
Context: ....x/guide/directory-structure/tsconfig). :: ::tip{icon="i-lucide-video" to="https...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~57-~57: Loose punctuation mark.
Context: ...uide/directory-structure/tsconfig). :: ::tip{icon="i-lucide-video" to="https://y...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~59-~59: Loose punctuation mark.
Context: ...l Roe explaining built-in Nuxt aliases. :: ## Project References Nuxt uses [Typ...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~76-~76: Loose punctuation mark.
Context: ...e-checking for their specific context. ::note For backward compatibility, Nuxt s...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~78-~78: Loose punctuation mark.
Context: ...be removed in a future version of Nuxt. :: ### Benefits of Project References -...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~97-~97: Loose punctuation mark.
Context: ...e the file in the shared/ directory. ::read-more{to="/docs/4.x/guide/going-fur...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~99-~99: Loose punctuation mark.
Context: ... contexts** in the Module Author Guide. :: ## Strict Checks TypeScript comes wi...

(UNLIKELY_OPENING_PUNCTUATION)

docs/2.guide/3.going-further/3.modules.md

[uncategorized] ~734-~734: Possible missing preposition found.
Context: ...fy the TypeScript configuration similar the example above. ```ts nuxt.hook('prepar...

(AI_HYDRA_LEO_MISSING_TO)

[uncategorized] ~751-~751: Loose punctuation mark.
Context: ...: resolve('./augments.d.ts') }) }) ``` ::note TypeScript references add files to...

(UNLIKELY_OPENING_PUNCTUATION)

[grammar] ~753-~753: Probably a preposition is missing after ‘references’.
Context: ...nts.d.ts') }) }) ``` ::note TypeScript references add files to the type context [without bein...

(ATD_VERBS_TO_COLLOCATION)

[uncategorized] ~753-~753: Loose punctuation mark.
Context: ....typescriptlang.org/tsconfig/#exclude). :: #### Augmenting Types From Modules N...

(UNLIKELY_OPENING_PUNCTUATION)

docs/2.guide/1.directory-structure/3.tsconfig.md

[uncategorized] ~33-~33: Loose punctuation mark.
Context: ...nstead, extend it via nuxt.config.ts. :: ::read-more{to="/docs/4.x/guide/conce...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~35-~35: Loose punctuation mark.
Context: ...ad, extend it via nuxt.config.ts. :: ::read-more{to="/docs/4.x/guide/concepts/...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~37-~37: Loose punctuation mark.
Context: ...t type contexts of a Nuxt project here. :: ## Extending TypeScript Configuration...

(UNLIKELY_OPENING_PUNCTUATION)

🔇 Additional comments (9)

docs/2.guide/3.going-further/3.modules.md (2)

707-755: Clear and comprehensive guidance on extending TypeScript configuration.

The new section effectively explains per-context customization with well-structured examples covering all four contexts (app, shared, node, and server). The direct modification approach is presented clearly alongside the hook-based alternative.

756-772: Well-organised directory structure guidance for type augmentation.

The new section provides clear guidance on where to place type declaration files for different contexts, with a helpful directory structure example. This aligns well with the module author's need to understand Nuxt's type context separation.

docs/2.guide/1.directory-structure/3.tsconfig.md (2)

8-10: Improved clarity on auto-generated configuration files.

The expanded description now explicitly mentions what the auto-generated tsconfig files include (recommended TypeScript configuration, auto-imports references, API route types, path aliases), which provides valuable context for users.

40-68: Comprehensive new section on extending TypeScript configuration.

The "Extending TypeScript Configuration" section effectively demonstrates how to customise all four TypeScript contexts (app, shared, node, and server) through nuxt.config.ts. The example is clear and covers both the typescript and nitro configuration options appropriately.

docs/2.guide/2.concepts/8.typescript.md (3)

50-52: Updated guidance on auto-generated types is more comprehensive.

The revised explanation now clearly states that types are stored in .nuxt and generated on nuxt dev/build or nuxt prepare, which provides users with better understanding of when these files are created.

68-79: Clearer project references structure with backward compatibility note.

The updated section now explicitly lists all four context-specific tsconfig files with their purposes, and properly notes backward compatibility with the legacy .nuxt/tsconfig.json file. This clarity helps users understand the new structure whilst reassuring them about migration safety.

90-100: Improved context-aware augmentation guidance.

The updated guidance now emphasises the importance of augmenting types within the correct context, and the new read-more link to the Module Author Guide provides a clear pathway for developers needing to augment types from files outside those contexts.

docs/1.getting-started/18.upgrade.md (2)

1138-1152: Well-structured section on TypeScript configuration splitting.

The section provides clear explanation of the new configuration structure with explicit references to the four context-specific tsconfig files. The enumerated list of changes is easy to follow and helps users understand the scope of the update.

1215-1243: Practical migration steps with clear configuration examples.

The configuration examples in the migration steps are consistent with guidance provided in other documentation files. The code block clearly shows customisation options for all four contexts (app, shared, node, and server), with appropriate comments explaining each section.

docs/2.guide/3.going-further/3.modules.md

cernymatej · 2025-11-02T22:04:53Z

docs/2.guide/3.going-further/3.modules.md

+------| server/ # server type context
+---------| augments.server.d.ts


This might not work correctly at the moment... see #33627

cernymatej · 2025-11-02T22:09:47Z

docs/2.guide/2.concepts/8.typescript.md

 Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.

+::note
+For backward compatibility, Nuxt still generates `.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/guide/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance. This legacy file will be removed in a future version of Nuxt.


This legacy file will be removed in a future version of Nuxt.

this is something I added - if that isn't the case, let me know and I'll remove it

coderabbitai

Actionable comments posted: 0

♻️ Duplicate comments (1)

docs/2.guide/3.going-further/3.modules.md (1)

734-734: Fix grammar: add missing preposition.

Line 734 is missing the preposition "to". The phrase should read "similar to the example above".

- Alternatively, you can use the `prepare:types` and `nitro:prepare:types` hooks to extend the TypeScript references for specific type contexts, or modify the TypeScript configuration similar the example above.
+ Alternatively, you can use the `prepare:types` and `nitro:prepare:types` hooks to extend the TypeScript references for specific type contexts, or modify the TypeScript configuration similar to the example above.

🧹 Nitpick comments (1)

docs/2.guide/3.going-further/3.modules.md (1)
752-754: Clarify note about TypeScript references and exclude behaviour.

The note at line 752–754 could be slightly clearer. Consider restructuring to emphasise that TypeScript references bypass the exclude option, which is an important distinction from regular includes:
- ::note
- TypeScript references add files to the type context [without being affected by the `exclude` option in `tsconfig.json`](https://www.typescriptlang.org/tsconfig/#exclude).
- ::
+ ::note
+ TypeScript references add files to the type context and are not affected by the `exclude` option in `tsconfig.json`. This is an important distinction from regular `include` entries.
+ 
+ :read-more{to="https://www.typescriptlang.org/tsconfig/#exclude"}
+ ::

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6e80dbc and d001e35.

📒 Files selected for processing (1)

docs/2.guide/3.going-further/3.modules.md (2 hunks)

🧰 Additional context used

🧠 Learnings (7)

📓 Common learnings

Learnt from: CR
Repo: nuxt/nuxt PR: 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

📚 Learning: 2024-11-11T12:34:22.648Z

Learnt from: Tofandel
Repo: nuxt/nuxt PR: 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/3.going-further/3.modules.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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/3.going-further/3.modules.md

📚 Learning: 2024-11-28T21:22:40.496Z

Learnt from: GalacticHypernova
Repo: nuxt/nuxt PR: 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/3.going-further/3.modules.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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/3.going-further/3.modules.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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/3.going-further/3.modules.md

📚 Learning: 2025-07-18T16:46:07.446Z

Learnt from: CR
Repo: nuxt/nuxt PR: 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/2.guide/3.going-further/3.modules.md

🪛 LanguageTool

docs/2.guide/3.going-further/3.modules.md

[uncategorized] ~751-~751: Loose punctuation mark.
Context: ...: resolve('./augments.d.ts') }) }) ``` ::note TypeScript references add files to...

(UNLIKELY_OPENING_PUNCTUATION)

[grammar] ~753-~753: Probably a preposition is missing after ‘references’.
Context: ...nts.d.ts') }) }) ``` ::note TypeScript references add files to the type context [without bein...

(ATD_VERBS_TO_COLLOCATION)

[uncategorized] ~753-~753: Loose punctuation mark.
Context: ....typescriptlang.org/tsconfig/#exclude). :: #### Augmenting Types From Modules N...

(UNLIKELY_OPENING_PUNCTUATION)

🔇 Additional comments (3)

docs/2.guide/3.going-further/3.modules.md (3)

707-750: Verify TypeScript configuration patterns match current Nuxt implementation.

The documentation provides two approaches for extending tsconfig.json from modules. However, a previous comment indicates that this functionality may not work correctly (see #33627).

Ensure that the documented patterns for:

nuxt.options.typescript.tsConfig

nuxt.options.typescript.sharedTsConfig

nuxt.options.typescript.nodeTsConfig

nuxt.options.nitro.typescript.tsConfig

are accurate and stable in the current Nuxt version before publishing this documentation.

656-667: Approve: "Updating Templates" section is clear and practical.

The new section provides a concrete, concise example of how to use updateTemplates within a file watcher hook. The pattern is well-structured and the use case is clear.

756-772: Approve: "Augmenting Types From Modules" section provides excellent guidance.

The expanded section clearly explains directory-structure conventions for augmenting types across different contexts (app, server, node), and the directory-structure example (lines 764–772) effectively illustrates the pattern. This helps module authors understand where to place type declarations without additional configuration.

danielroe

this is SO much better - thank you ❤️

docs: add typescript documentation for module authors

6e80dbc

cernymatej requested a review from danielroe as a code owner November 2, 2025 22:02

github-actions bot added 4.x documentation labels Nov 2, 2025

coderabbitai bot reviewed Nov 2, 2025

View reviewed changes

docs/2.guide/3.going-further/3.modules.md Outdated Show resolved Hide resolved

cernymatej commented Nov 2, 2025

View reviewed changes

docs: add missing preposition

d001e35

cernymatej commented Nov 2, 2025

View reviewed changes

coderabbitai bot reviewed Nov 2, 2025

View reviewed changes

danielroe approved these changes Nov 3, 2025

View reviewed changes

danielroe merged commit fa013f9 into nuxt:main Nov 3, 2025
8 of 9 checks passed

cernymatej deleted the docs/improve-typescript-secitons branch November 3, 2025 11:10

github-actions bot mentioned this pull request Nov 3, 2025

v4.2.1 #33565

Merged

coderabbitai bot mentioned this pull request Dec 3, 2025

docs: split and improve Module Author Guides #33803

Merged

coderabbitai bot mentioned this pull request Dec 25, 2025

docs: clarify type-checking context limitations for server routes #33964

Open

coderabbitai bot mentioned this pull request Jan 16, 2026

docs: add Information about module code in the runtime directory #34095

Open

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: add typescript documentation for module authors #33637

docs: add typescript documentation for module authors #33637

Uh oh!

cernymatej commented Nov 2, 2025

Uh oh!

bolt-new-by-stackblitz bot commented Nov 2, 2025

Uh oh!

coderabbitai bot commented Nov 2, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

cernymatej Nov 2, 2025

Uh oh!

cernymatej Nov 2, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

danielroe left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		------\| server/ # server type context
		---------\| augments.server.d.ts

Uh oh!

docs: add typescript documentation for module authors #33637

docs: add typescript documentation for module authors #33637

Uh oh!

Conversation

cernymatej commented Nov 2, 2025

📚 Description

Uh oh!

bolt-new-by-stackblitz bot commented Nov 2, 2025

Uh oh!

coderabbitai bot commented Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cernymatej Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

cernymatej Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

danielroe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai bot commented Nov 2, 2025 •

edited

Loading

cernymatej Nov 2, 2025 •

edited

Loading