chore: revamp how we export types

[SethFalco]

Finally, this is what all of my previous PRs recently have been leading up to. I've spent a lot of time reading up on TypeScript, JSDocs, and reviewing how different projects choose to maintain their types and settled on this for us.

I personally like writing JavaScript, not TypeScript. So I wanted to maximize use of the TypeScript tooling, but without adopting the TypeScript language. We were doing this already by typing through JSDocs, but this takes things further.

The fundamental change that this applies is that instead of manually maintaining type declarations for our public interface, we now generate those declarations using tsc. Running yarn run build:types is now part of the build process before publishing to npm, similar to how we must run build:bundles to create the CJS and browser bundles too.

Benefits

• We maintain types closer to the implementation.
• We guarantee that types are in sync with the implementation, and reduces the risk of mistakes when defining types.

Breaking Changes

I've decided to drop default exports from the library. My original plan was to keep them in SVGO v4, and export with both named and default exports. However, this seems a little more annoying to maintain than I was expecting.

Reasons:

• Not a great experience to keep named exports and default exports in sync.
• Not a great experience to maintain default exports that also need to re-export from other files.
• When generating types with tsc, default exports didn't properly have their documentation forwarded in type declaration.
• I'm sure these were all solvable issues, but it didn't seem worth solving when there's little to no benefit from exporting twice anyway.

Not the main reason, but other considerations:

• The preferred interface is named exports anyway.
• Most usage of SVGO I've seen in the wild use it this way already (actually all usage, but I'm sure there's an exception somewhere):
  • gregberge/svgr
  • unjs/ipx
  • rossmoody/svg-gobbler
  • airbnb/babel-plugin-inline-react-svg
  • ben-eb/gulp-svgmin
  • cpsoinos/nuxt-svgo
  • sonnyp/OhMySVG
  • 1000ch/vscode-svgo
• Overall I'd consider named exports a better practice than default exports, and more conventional across libraries.

This has no impact on users who:

• Use SVGO from the CLI.
• Import the project from CJS (require).
• Who were already using named exports when importing SVGO.

However, if you are using the import syntax and imported SVGO via the default export, then you must adapt your code for v4:

- import svgo from 'svgo';
- svgo.optimize('<svg></svg>');

// Option 1. Use named exports!
+ import { optimize } from 'svgo';
+ optimize('<svg></svg>');

// Option 2. Or import everything as svgo!
+ import * as svgo from 'svgo';
+ svgo.optimize('<svg></svg>');

Changes

• Avoid using @typedef unless we actually want to declare/export a type to be used in other files. TypeScript generates an export whenever we used @typedef. This is also why for common types like XastElement, the IDE would often auto-complete it to the @typedef of a random file rather than the file that actually defined the type.
• Migrate some types from .d.ts files to JSDocs to maintain the type closer to the documentation.
• Rename types.d.ts to types.ts. The .d.ts format is usually to define types for code you don't control, which doesn't apply in our case. When documenting your types, one should use .ts.
• Migrate all manual type declarations to types.ts, as we'll generate types for the rest from the JSDoc types.
• Avoid using = undefined in the JavaScript function signature, and prefer using the = suffix in the JSDoc type.
• In our package.json, we no longer specify typesVersions.
  • This field is reluctant in our case since we only maintain one version of types.
  • TypeScript will prioritize exports.types over typesVersions anyway.

Testing

• We now use tsd to test our types and have a very simple .test-d.ts file. I can expand this later, but it tests the most important thing for now, which was the issue reported in optimize types missing from svgo-node.d.ts in 4.0.0-rc.1 #2078.

Documentation

• Many of our plugins had an @example in their documentation that featured an arrow to separate before vs. after. I've normalized the indentation of the arrow to 2 spaces just to keep it consistent between examples.

Chores

• Increment version to v4.0.0-rc.2.
• Update documentation in CONTRIBUTING.md to refer to the new file to update when making a new plugin.
• Update CONTRIBUTING.md to require Node.js v16 as a minimum, and clarify why.
• Test types in a separate build step in GitHub Actions now.
• Add directories that Yarn recommend to .gitattributes.
• Organize our .gitignore and add some comments.

Related

• Fixes optimize types missing from svgo-node.d.ts in 4.0.0-rc.1 #2078
• Closes fix(import): broken optimize for svgo-node #2099 — Alternate solution.

Thanks

I want to give a special thanks to @open-wc who have written great articles on how they handle their type declarations, which I largely referenced to implement the workflow here.

The Open Web Components team have a great article titled Generating TypeScript Definition Files from JavaScript. This was very helpful because most guides share how to generate types declarations, which is the easy part, but don't dive into much detail on workflow or a good way to incorporate the generated types into a package to publish. Meanwhile, open-wc does dive into deal and have many simple examples of the setup in their repositories.