Build tools improvement: api-extractor for bundling dts

fnlctrl commented 1 year ago

Why

Typings

Current dist is inconsitent for typescript usage, e.g. this example from quill repo:

import {
  Blot,
  BlotConstructor,
} from 'parchment/dist/typings/blot/abstract/blot';

could have simply been

import type { Blot, BlotConstructor } from 'parchment';

Module format

Currently dist/parchment.js is umd format. It would have been nice to have esm format too.

Whats changed

Vite is used for bundling js that support both umd and esm.
api-extractor is used for bundling .d.ts. dist/typings is removed. api-extractor.json is added for config.
Missing type exports like Blot and BlotConstructor found by api-extractor are added in the index file (src/parchment.ts)
tsconfig.json is modified.
- "emitDeclarationOnly": true is added since tsc is not used for runtime codegen (vite/esbuild are used instead).
- "moduleResolution": "node" is added for vite config in ts.
- "exclude" removed and "include" added because it's simpler.
Added overrides "semver-regex": "^3.1.4" and "http-cache-semantics": "^4.1.1". This fixes some npm audit issues.

Before

dist/
- typings/
- parchment.js
- parchment.js.map

After

dist/
- parchment.d.ts
- parchment.mjs
- parchment.mjs.map
- parchment.umd.js
- parchment.umd.js.map

fnlctrl commented 1 year ago

@luin Could you help take a look? In our current project we’re trying to import quill from TS source since it hasn’t had new versions for a long time. Everything works fine except for .d.ts bundling - we need it because we’re building on top of quill for an internal package. Let me know if there anything that you don’t like about this PR and I’ll update accordingly. You don't need to publish a new version for this if it's too much hassle - we can install from github directly. We just need this to be merged to not install from our own fork. I can make a similar PR for quill-delta to update js/.d.ts bundling as well.

luin commented 1 year ago

Hey @fnlctrl 👋

Thank you for the PR! I'm not sure if it's a good idea to provide both UMD/CJS and ESM, as I was under the impression that bundlers have issues dealing with them (ex webpack/webpack#5756). Additionally, this introduces the dual package hazard where we rely on instanceof heavily when dealing with Blot typings.

We should maintain a consistent tech stack across all Quill repositories. Therefore, I'd suggest avoiding the introduction of Vite at this time solely for ESM support. In the future, we could consider transitioning the package to ESM only.

fnlctrl commented 1 year ago

@luin Thank you for taking the time to reivew! Here are my thoughts:

For dual umd/esm builds:

As for the webpack issue, I think it only affects default export: The equivalent of import Default from 'module''s should be require('module').default. It shouldn't affect named exports. Since Parchment only contains named exports, this wouldn't be an issue.

As for the dual package hazard, if I'm not mistaken, Parchment is currently only meant to be run in the browser. So it won't be running directly in node and thus subject to node's issue. For people using umd via Githubissues.

Githubissues is a development platform for aggregating issues.

slab / parchment