Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: create official TypeScript base config @docusaurus/tsconfig #9050

Merged
merged 3 commits into from
Jun 9, 2023
Merged

feat: create official TypeScript base config @docusaurus/tsconfig #9050

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3435065
Create official versioned package for @docusaurus/tsconfig
slorber Jun 8, 2023
7e7cb2d
Fix little issues in TS init templates
slorber Jun 9, 2023
b115a6f
change docs
slorber Jun 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions packages/create-docusaurus/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,5 +35,18 @@ cd `git rev-parse --show-toplevel` # Back to repo root
rm -rf test-website-in-workspace
yarn create-docusaurus test-website-in-workspace classic
cd test-website-in-workspace
yarn build
yarn start
```

For the TypeScript template:

```bash
cd `git rev-parse --show-toplevel` # Back to repo root
rm -rf test-website-in-workspace
yarn create-docusaurus test-website-in-workspace classic --typescript
cd test-website-in-workspace
yarn typecheck
yarn build
yarn start
```
2 changes: 1 addition & 1 deletion packages/create-docusaurus/templates/classic-typescript/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.0.0-alpha.0",
"@tsconfig/docusaurus": "^1.0.5",
"@docusaurus/tsconfig": "^3.0.0-alpha.0",
"typescript": "^5.0.4"
},
"browserslist": {
Expand Down
1 change: 0 additions & 1 deletion .../create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import React from 'react';
import clsx from 'clsx';
import Heading from '@theme/Heading';
import styles from './styles.module.css';
Expand Down
1 change: 0 additions & 1 deletion packages/create-docusaurus/templates/classic-typescript/src/pages/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import React from 'react';
import clsx from 'clsx';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
Expand Down
2 changes: 1 addition & 1 deletion packages/create-docusaurus/templates/classic-typescript/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
// This file is not used in compilation. It is here just for a nice editor experience.
"extends": "@tsconfig/docusaurus/tsconfig.json",
"extends": "@docusaurus/tsconfig",
"compilerOptions": {
"baseUrl": "."
}
Expand Down
1 change: 0 additions & 1 deletion packages/create-docusaurus/templates/classic/src/components/HomepageFeatures/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import React from 'react';
import clsx from 'clsx';
import Heading from '@theme/Heading';
import styles from './styles.module.css';
Expand Down
1 change: 0 additions & 1 deletion packages/create-docusaurus/templates/classic/src/pages/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import React from 'react';
import clsx from 'clsx';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
Expand Down
20 changes: 20 additions & 0 deletions packages/docusaurus-tsconfig/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"name": "@docusaurus/tsconfig",
"version": "3.0.0-alpha.0",
"description": "Docusaurus base TypeScript configuration.",
"main": "tsconfig.json",
"publishConfig": {
"access": "public"
},
"keywords": [
"tsconfig",
"typescript",
"docusaurus"
],
"repository": {
"type": "git",
"url": "https://github.com/facebook/docusaurus.git",
"directory": "packages/docusaurus-tsconfig"
},
"license": "MIT"
}
23 changes: 23 additions & 0 deletions packages/docusaurus-tsconfig/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"$schema": "https://json.schemastore.org/tsconfig",
"display": "Docusaurus",
"docs": "https://docusaurus.io/docs/typescript-support",
"compilerOptions": {
"allowJs": true,
"esModuleInterop": true,
"jsx": "preserve",
"lib": ["DOM"],
"moduleResolution": "Node16",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are considering making it an error to specify moduleResolution: "node16" without "module": "node16" at microsoft/TypeScript#54567. "module": "node16" implies "moduleResolution": "node16", but unfortunately not the reverse. Using one without the other matching has some very strange, unpredictable, and dangerous effects.

Many of the new errors that we detected would occur from this change are in tsconfigs that inherit from the old @tsconfig/docusaurus package. Would you be able to add "module": "Node16" to this template?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The moduleResolution should be bundler, because this config is shared for our users, who exclusively write client code. We use "moduleResolution": "node16" here so that package.json exports can be resolved, but if we use "module": "node16", then because users never specify "type": "module" in their package.json (this actually breaks webpack, for some reason yet to be discovered), they will not be able to import ESM dependencies.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, can you change to module: esnext with moduleResolution: bundler, then?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure! I don't think anyone has played with the tsconfig since the last time I added node16. I'm a bit caught up with MDN work recently so I may not be able to come back to it, but I (or @slorber) will surely play with it when we have time.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you version @docusaurus/tsconfig? Would this have to wait until a major version bump of other docusaurus packages?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@docusaurus/tsconfig is already created for the next major, so before its release, we are free to do anything with it :) Do you anticipate the switch to moduleResolution: bundler to be a breaking change?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically it could introduce new TS errors. With node16 and no "type": "module", resolution of imports of external libraries uses the types, node, and require conditions when lookup up conditional exports, because the assumption is that these imports will be emitted as require calls (this is part of why mixing --moduleResolution node16 with --module esnext breaks some core assumptions in the compiler). With bundler, the conditions are types and import. This better matches what Webpack is actually going to do during its own resolution, but we do occasionally see external libraries that have messed up the types for their import entrypoint.

So, it’s really like a bugfix, but it could trigger an external library’s typing bug in a way that the current config doesn’t.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. It should be okay for us. Our versioning scheme typically allows "more type errors that are undeniably user bugs" across minor versions.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @andrewbranch

Our CI started failing after 5.2 GA release, so it's a good reminder for me to handle this 😅

This will be fixed in #9258

Thanks

"noEmit": true,
"types": [
"node",
"@docusaurus/module-type-aliases",
"@docusaurus/theme-classic"
],
"baseUrl": ".",
"paths": {
"@site/*": ["./*"]
},
"skipLibCheck": true
}
}
4 changes: 2 additions & 2 deletions website/docs/typescript-support.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,14 @@ Below are some guides on how to migrate an existing project to TypeScript.
To start using TypeScript, add `@docusaurus/module-type-aliases` and the base TS config to your project:

```bash npm2yarn
npm install --save-dev typescript @docusaurus/module-type-aliases @tsconfig/docusaurus
npm install --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig
```

Then add `tsconfig.json` to your project root with the following content:

```json title="tsconfig.json"
{
"extends": "@tsconfig/docusaurus/tsconfig.json",
"extends": "@docusaurus/tsconfig",
"compilerOptions": {
"baseUrl": "."
}
Expand Down
2 changes: 1 addition & 1 deletion website/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@
},
"devDependencies": {
"@docusaurus/eslint-plugin": "^3.0.0-alpha.0",
"@tsconfig/docusaurus": "^1.0.7",
"@docusaurus/tsconfig": "^3.0.0-alpha.0",
"@types/jest": "^29.4.0",
"cross-env": "^7.0.3",
"rimraf": "^3.0.2"
Expand Down
6 changes: 2 additions & 4 deletions website/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
{
// This file is not used in compilation. It is here just for a nice editor experience.
"extends": "@tsconfig/docusaurus/tsconfig.json",
"extends": "@docusaurus/tsconfig",
"compilerOptions": {
"jsx": "preserve", // TODO add to preset config

"lib": ["DOM", "ESNext"],
"baseUrl": ".",
"resolveJsonModule": true,

// Duplicated from the root config, because TS does not support extending
// multiple configs and we want to dogfood the @tsconfig/docusaurus one
// multiple configs and we want to dogfood the @docusaurus/tsconfig one
"allowUnreachableCode": false,
"exactOptionalPropertyTypes": false,
"noFallthroughCasesInSwitch": true,
Expand Down
5 changes: 0 additions & 5 deletions yarn.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2818,11 +2818,6 @@
resolved "https://registry.yarnpkg.com/@trysound/sax/-/sax-0.2.0.tgz#cccaab758af56761eb7bf37af6f03f326dd798ad"
integrity sha512-L7z9BgrNEcYyUYtF+HaEfiS5ebkh9jXqbszz7pC0hRBPaatV0XjSD3+eHrpqFemQfgwiFF0QPIarnIihIDn7OA==

"@tsconfig/docusaurus@^1.0.5", "@tsconfig/docusaurus@^1.0.7":
version "1.0.7"
resolved "https://registry.yarnpkg.com/@tsconfig/docusaurus/-/docusaurus-1.0.7.tgz#a3ee3c8109b3fec091e3d61a61834e563aeee3c3"
integrity sha512-ffTXxGIP/IRMCjuzHd6M4/HdIrw1bMfC7Bv8hMkTadnePkpe0lG0oDSdbRpSDZb2rQMAgpbWiR10BvxvNYwYrg==

"@types/acorn@^4.0.0":
version "4.0.6"
resolved "https://registry.yarnpkg.com/@types/acorn/-/acorn-4.0.6.tgz#d61ca5480300ac41a7d973dd5b84d0a591154a22"
Expand Down