From ebd087a31661a1b701650d0be3e123cc5a813bd8 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Wed, 13 Jan 2021 09:37:35 +0000 Subject: [PATCH] feat(types): expose typedefs to consumers (#6745) This PR replaces https://github.com/puppeteer/puppeteer/pull/6289 with a simpler approach to types where we compile them all alongside the compiled code (so for every `foo.js` that is generated, we generate `foo.d.ts`). By default that's not enough, as when you `import puppeteer from 'puppeteer'` in Node land you import `cjs-entry.js`, so we also create `cjs-entry.d.ts` which TypeScript will then pick up. This type file tells TypeScript that the thing that `cjs-entry.js` exposes is an instance of the `Puppeteer` class, which then hooks all the types up. The previous PR (https://github.com/puppeteer/puppeteer/pull/6289) tried to merge all our typedefs into one big file via API Extractor, but this isn't really necessary a good experience for the developer. One important consideration is that you _could_ consider this a breaking change. I'm not sure how likely it is, but it could cause problems for: * Projects that didn't have any type info for Puppeteer and treated all its exports as `any` may now start having legitimate type failures. * Projects that depend on the `@types/puppeteer` package may have issues if they now swap to use this one and the types aren't quite aligned. In addition, once we do ship a release with this change in, it will mean that we have to treat any changes to any type definitions as release-note-worthy, and any breaking changes to type definitions will need to be treated as breaking code changes (nearly always a breaking type def means a breaking change anyway), but it's worth considering that once we expose these typedefs we should treat them as first class citizens of the project just like we would with the actual source code. I also fully expect to have some bugs with our types, or have users create issues/PRs to change our types, but I think that's a good thing and it should settle down. I've tested this locally by creating a new package, linking Puppeteer via `npm link puppeteer` and then checking that VSCode correctly shows me the right things when I use `Go to Definition` on something that comes from the Puppeteer source code. --- cjs-entry.d.ts | 3 +++ src/tsconfig.esm.json | 4 +--- tsconfig-esm.json | 7 ------- tsconfig.base.json | 2 +- 4 files changed, 5 insertions(+), 11 deletions(-) create mode 100644 cjs-entry.d.ts delete mode 100644 tsconfig-esm.json diff --git a/cjs-entry.d.ts b/cjs-entry.d.ts new file mode 100644 index 00000000000..8e7dc53e0fe --- /dev/null +++ b/cjs-entry.d.ts @@ -0,0 +1,3 @@ +declare const _default: typeof import('./lib/cjs/puppeteer/node').default; + +export default _default; diff --git a/src/tsconfig.esm.json b/src/tsconfig.esm.json index 487533061f4..29fabd9aa75 100644 --- a/src/tsconfig.esm.json +++ b/src/tsconfig.esm.json @@ -5,7 +5,5 @@ "outDir": "../lib/esm/puppeteer", "module": "esnext" }, - "references": [ - { "path": "../vendor/tsconfig.esm.json"} - ] + "references": [{ "path": "../vendor/tsconfig.esm.json" }] } diff --git a/tsconfig-esm.json b/tsconfig-esm.json deleted file mode 100644 index 06d8e25d98b..00000000000 --- a/tsconfig-esm.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "extends": "./tsconfig.json", - "compilerOptions": { - "outDir": "./lib/esm", - "module": "ES2015", - }, -} diff --git a/tsconfig.base.json b/tsconfig.base.json index 8e2d98cf2a1..b1229ed97d0 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -9,6 +9,6 @@ "declaration": true, "declarationMap": true, "resolveJsonModule": true, - "sourceMap": true, + "sourceMap": true } }