Rewrite in Typescript

[berstend]

Current progress (28 Nov - not pushed yet!) 📚

• Rewrite puppeteer-extra in TypeScript 🎉
• New addExtra export to support non-standard or multiple puppeteer instances
• Find a way to stay compatible with the existing default export and behavior
• Make all existing tests go green
• Find a way to use documentation.js with TypeScript
• Find a way to have plugins extend Puppeteer types (e.g. page.solveCaptchas())
• Add TypeScript usage examples to readme
• Add puppeteer-firefox usage examples to readme
• Beautify the documentation.js output to the current look
• Update all plugins to use the new core
• Update all plugins to use the new documentation approach

---

(initial comment)

I started this repo before noticing how awesome typescript is. 😄

Whenever I find the time I shall refactor this project into typescript.

Potential issues:

• Automatic JSDoc > Markdown conversion (tsdoc isn't there yet)
  • TypeScript support documentationjs/documentation#282
• How to best generate types when dynamically patching puppeteer

Update

Parts have been rewritten in TypeScript 🎉

• puppeteer-extra-plugin-recaptcha
• puppeteer-extra-plugin (base class for plugins)

Before I can rewrite the rest I need to improve the generated typedoc output.

We're using typedoc-plugin-markdown (the current best thing) and the output looks like this, compared to the previous documentation.js based docs. 😢

I'm really close to start developing my own minimal typedoc-plugin-readme plugin. 😅

[outlabeau]

Agreed! At this point, i will only use npm modules that have an @types package that goes along with it. Especially important for puppeteer-extra since it's used as a drop-in replacement for puppeteer in the code. Can't wait to see a @types package become available for this!

[berstend]

@outlabeau I'm gonna create a d.ts for the time being (until everything is written in typescript) 😄 No need for @types though, the new version will come pre-shipped with the definitions.

[outlabeau]

@berstend that's great! Can't wait for the d.ts.

[n1xn]

What is the status for this intend?

[berstend]

Apologies, got swamped with $work related things. Given that I love TS and my documentation system seems to be supporting TS now (this was the main blocker) I'll be rewriting the puppeteer-extra core in TS now after some hygiene tasks (updating deps, etc) :)

[berstend]

Current workarounds are mentioned here:
#38 (comment)

I'm currently checking that documentation.js will work with TypeScript as advertised (auto-generated docs are super important 😄).

In case that doesn't work I'll whip up a custom d.ts for the time being with the essentials.

[berstend]

The heavy lifting is done and the TypeScript version makes all tests go green. The auto-completion support in JS is a game changer, even for non-TS users.

I ended up finding a way to stay backwards compatible with the current default export/behaviour:

// existing simple case: defaults to require "puppeteer" or "puppeteer-core"
const puppeteer = require('puppeteer-extra')
puppeteer.use(...)

// new: optionally provide a puppeteer instance to patch
const { addExtra } = require('puppeteer-extra')
const puppeteer = addExtra(require('puppeteer-firefox'))
puppeteer.use(...)

Using this opportunity to cleanup and overhaul some other things as well before pushing this release.

[berstend]

First class TypeScript support has just landed!

import puppeteer from 'puppeteer-extra'

import RecaptchaPlugin from 'puppeteer-extra-plugin-recaptcha'
import StealthPlugin from 'puppeteer-extra-plugin-stealth'

puppeteer.use(RecaptchaPlugin()).use(StealthPlugin())

puppeteer.launch({ headless: false }).then(async browser => {
  const page = await browser.newPage()
  await page.setViewport({ width: 800, height: 600 })

  await page.goto('https://bot.sannysoft.com')
  await page.waitFor(5000)
  await page.screenshot({ path: 'stealth.png', fullPage: true })

  await browser.close()
})

cc @outlabeau @NikoMontana

They only thing I haven't figured out yet is how plugins could automatically extend built-in Puppeteer types (e.g. page.solveCaptchas()).

Not sure if that's even possible.

But that's not too critical and can be overridden by the user easily ((page as any).solveCaptchas()). :)

[berstend]

Found a way to have plugins extend Puppeteer types (e.g. page.solveCaptchas()) fully type safe for consumers by shipping an ambient d.ts file. :)

Closing this for now.