jsPDF-AutoTable: [v4-breaking] Propose new exporting API for better ESM & Typescript support
I was looking into fixing some of the autoTable is not defined issues and improving ESM support, and also typescript issues, It all came down to the hack we do to apply the plugin to the current jspdf instance, we are using require() here to wrap it with a try-catch, this cannot be transpiled to import so it causes a problem with rollup in some version of vite/vue/angular and requires setting a flag (https://github.com/vitejs/vite/issues/5759)
The solution
I propose we don’t apply the plugin to jsPDF, we don’t even supply applyPlugin(), so there will be no doc.autoTable* we just export the functions needed to work on a jspdf doc, currently there’s autoTable(doc, ...) we make this the only way and export any other function needed like setDefaults(), so the proposed API is like this :
// ESM imports
import { jsPDF } from 'jspdf'
import { autoTable } from 'jspdf-autotable'
// commonjs (node)
const { jsPDF } = require('jspdf')
const { autoTable } = require('jspdf-autotable')
// in the browser (with a <script> tag)
const { jsPDF } = window.jspdf
const { autoTable } = window['jspdf-autotable']
// Usage
const doc = new jsPDF()
const table = autoTable(doc, {/* options */})
doc.save()
// you can access anything regarding the created table
table.finalY
table.pageNumber
table.settings
// ...
// no applyPlugin()
// no jsPDF.autoTable*
// no jsPDF.lastAutoTable
// other autotable exported functions
import { autoTable, setDefaults, htmlToJson } from 'jspdf-autotable'
setDefaults({/* ... */})
htmlToJson(/* ... */)
What makes this a breaking change is instead of default export import autoTable from 'jspdf-autotable' we change to named exports import { autoTable } from 'jspdf-autotable' to allow us to export other parts like setDefault so we don’t need to extend jspdf (doc.autoTable*) and importing become consistent in all environments, That’s actually also what jspdf did from v1 to v2 :
// v1
import jsPDF from "jspdf";
// v2
import { jsPDF } from "jspdf";
The benefits
This solves many problems :
- No need for any
require()hacks, so the source code is pure ESM which makes it much easier to transpile to any format without problems (fixes #860 and many more). - The new API is fully ESM compliant and tree-shakable with a suitable build (fixes #706).
- Consistent usage between all environments, and only one way to create the table.
- Ability to use any version of
jspdf, you just pass thedoccreated toautoTable. - Solves the typescript
(doc as any).autoTableproblem (#994, #848) because we won’t extend jspdf, we just import the correctdoctype from jspdf and use it, and we have a type for the returned table which can be used to access any info regarding the table likefinalYso no need fordoc.lastAutotable
The downside
- No ease of use in the browser where you could just link the script and
doc.autoTable(). - This is a breaking change so will need a major version bump (v4?)
But we could use this opportunity and remove the deprecated parts and improve the other parts, we can study the other improvements that could be done, if some need API breaking changes we do it so we don’t have to do breaking changes again in the future.
@simonbengtsson What do you think? I’m ready to tackle this, if this is going to happen, I think we should create a v4 branch, do all the work there and merge when we are ready. but first I’ll work a bit on the current version, go through the issues, fix what I can and take notes of things need breaking changes to do it in v4.
About this issue
- Original URL
- State: closed
- Created 3 years ago
- Reactions: 3
- Comments: 18 (7 by maintainers)
Sounds great! Time for a proper modernization! 🎉
I believe an alpha release would be beneficial for testing v4 and for early adopters as long as they expect some breaking changing before the stable release.
All of the v4 goals have been met, however, there is still significant work to be done in the colspan/rowspan area and possibly
horizontalPageBreakthat could lead to some breaking changes in the API.@simonbengtsson What are your thoughts?
Hi @mmghv, thanks for the detailed instructions. I tested it and it works just fine 👍
We currently target
ES5when transpiling, is it time to upgrade toES6(ES2015) with v4? I hate seeing all thevars and.prototypestuff especially in the es build.ES6 adds support for const/let, classes, arrow functions and more, this results in a cleaner and a little bit smaller code:
But IE11 doesn’t fully support ES6: https://caniuse.com/?search=es6
I’m not actually sure if jsPDF or autoTable fully supports IE11, and everyone is dropping support for it. @simonbengtsson what do you think?
I played around with this a bit now in the newly pushed v4 branch and I think I were able to implement everything exactly as your proposal above @mmghv. Great stuff!
autoTable(doc, {...})usage style is now supported anddoc.autoTable({...})has been removedum, I was confused seeing v4 released shortly followed by v5!
I think this complicates things since the v4 branch might no longer be mergeable. I’m unsure about the next step, so feel free to proceed as you see fit.
@hrueger Great! thanks for taking the time 👍