V8 Migration

[akraines]

Hi,

I invested a lot in setting up a ReactTable using the excellent samples of V7 and for use throughout our project. It seems like a big job to upgrade to V8. Can someone advise me regarding 2 things:

1. Is the performance of V8 better than V7? Or is that not the goal? [I want to improve row rendering performance - I'm using react-virtual for virtualization]
2. Is there a migration guide yet?

Thanks! and keep up the quality work!

[mryechkin]

Would love to see this as well. We also recently started using v7, and it's not very clear what the migration path to v8 would look like. It would be good to have some guidance on this

[tannerlinsley]

Working on it. Tanner Linsley

…

On Jun 29, 2022, 12:24 PM -0600, Mykhaylo Ryechkin ***@***.***>, wrote: Would love to see this as well. We also recently started using v7, and it's not very clear what the migration path to v8 would look like. It would be good to have some guidance on this — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[mryechkin]

Great to hear! 🙌 Thanks for the speedy response

[akraines]

I see that the migration guide [or the beginnings of it] are in the main readme

[MikePrus]

@tannerlinsley Hi, thanks for the fantastic table package I enjoy using it. How could I be notified when the migration guide will be ready?

[bobaekang]

Adding a comment to express more interest in a detailed migration guide. More concretely, a side-by-side comparison between old react-table@7 and @tanstack/react-table@8 for basic examples would be :chefs_kiss:.

Anyways, a big thanks to @tannerlinsley for your contribution to the ecosystem!

[nimeshvaghasiya]

@tannerlinsley Migration guide for v8 is up now? this thread is few month old so asking for any update!

[evoratec]

Working on it (ironic mode off)

[evoratec]

Here i was a fucking selfish. Why not to do the migration guide myself and share with all the people ?
I have to say that @tannerlinsley do a wonderful job.

[OmerWow]

Would like to know if there's a migration guide available yet

[riverxu99]

at the bottom of the README

[GRA0007]

That's not a full migration guide, just a list of important changes. We want to know exactly which props we have to find/replace etc. to make our code compatible with the new API.

[OmerWow]

That's not a full migration guide, just a list of important changes. We want to know exactly which props we have to find/replace etc. to make our code compatible with the new API.

Exactly.

I ended up simply deleting my old components and just writing everything again using the examples from the website.
Still hasn't got sorting and filtering functionality as I want to, just pagination and sub-components for now.

[danielMiron]

still nothing? we would really like to upgrade but it would be nice to understand how much effort to expect.
is it even expected to work with v7 code or is the whole API different

[JamesFredrickson]

This is the problem with using libraries that creators think they need to do a complete api re-write on. Good libraries should be easy to upgrade, not whatever this mess is, and without a migration guide on top of it. I would caution against using any of his libraries.

[atkallie]

@JamesFredrickson, I get your frustration since I'm currently dealing with the headache of migrating to v8 myself, but I have to side with @benjamincharity on this one.

First off, this is all OSS, so it's great of @tannerlinsley and the other contributors to make this all available to the community for free. Creating and maintaining this code from scratch (or hiring devs to do it) would be time-consuming and/or expensive. And I'd take a guess that the reason for the breaking changes is because it preserves the community built around the library (instead of spinning up a new one and fragmenting the community). This is also the case for widely used libraries like Material UI when they did the major overhaul from v4 to v5 (huge pain in the ass).

That being said, I'd agree that it would be nice to have more backwards-compatibility considerations (e.g. deprecations, etc.), but honestly the benefits outweigh the costs and any developer (including yourself) can always get more involved in the process if they love the library but want to suggest introducing more elegant transitions in the API. Regardless, It's nice to know that these big overhauls only happen during major version upgrades and minor version upgrades behave pretty nicely.

All in all, though, this migration seems pretty straightforward to be honest (though I wish there were more migration docs). Trust me, it was nothing compared to the migration from components to headless lol (v4 to v5, I think). Don't mean to lecture you, but I just don't want OSS developers to be discouraged from continuing the great work they do when they feel like it isn't being appreciated.

[JamesFredrickson]

@atkallie there are still no docs on how to upgrade. At least Material has automation and complete instructions on how to upgrade. I upgraded in one day. However, he practically threw V7 to the side and went to V8 with a whole new API; I would have not used this library if I knew that was going to be the case. Why anyone would trust anything he does going forward is beyond me, but to each their own. The comment below says a lot, a week to go over every component so that he could upgrade. I have around 15 tables in my app. I'm guessing it would take me a month to upgrade to V8. I've been working with React for 8 years and this is the first time I have ever come across something so screwed up. Yes I appreciate the library, but if you want to make something that you want everyone to use then I guess you have a certain responsibility to make upgrade documentation and automation as well. Give me some more thumbs down!

[atkallie]

@JamesFredrickson For the record, I didn't thumbs down your comment because - like I said - I get your frustration.

Let's ignore the maintainers feelings for a second and assume that you make a valid point. What then? You would have four options:

• Look for a better alternative (this is the most actively maintained headless UI React Table library to my knowledge, though. If you do find one, then check their migration guides to make sure you won't run into the same issue again).
• Try to voice your frustration to the maintainers and specifically ask what you can do to help avoid this problem moving forward.
• Fork a copy of v7 and maintain your own custom react-table implementation locally since there's no guarantee that anything will improve in terms of migration strategy without doing option 2.
• (What I do) Accept the fact that migrations will probably be a pain and design your codebase to minimize its direct exposure to the library (e.g. make a DataTable component with props that you control and any changes to the specifics of the library will be isolated to the internals of this component).

[JamesFredrickson]

@atkallie I agree, lesson learned. Although I did in fact remove direct exposure to most of the library from the get go but in the end that didn't matter. In case if anyone else reads this and thinks about using his query library, redux toolkit query is heads and shoulders above TanStack Query. Looking at TanStack Query then redux toolkit query really made me realize just how much his libraries are obfuscated. Which gets to the point, just because you have the time to make something doesn't mean you're good at making something.

[tannerlinsley]

I understand some of your sentiment here. The changes were vast and included paradigm shifts (headless, then agnostic). Table needs better docs, more guides, more examples, migration guides; all things that have been on my radar for a long time. But there’s that word: “time”.

I can only do so much, and only in the priority that produces the best net output for not only my users, but my own apps as well.

React Query is phenomenal and while I respect RTKQuery and its creators, your opinion is not widely shared.

My libraries are definitely not “obfuscated”. By definition, they are quite the opposite: headless, composable and configurable. I designed them with inverted control at the forefront.

The point isn’t that I just “had the time”. It’s that I took the time to work through challenges that others would rather not deal with and offered it up for free to people who found it useful (including yourself). However long you’ve used v7 productively is how much time in tableland I took off your plate (or that you put on my plate when you chose it).

If you think your choice was a bad one, I’m sorry, but remember that it was yours and where you’d likely be without it (probably building your own table abstraction or using another library with completely different issues to complain about). You’re free to move on as always, but instead I’d like to invite you to stick around.

We’d love your help improving Table’s docs. Help us write the migration guide, help us bolster the docs, or however you see fit. This is the OSS way.

[GuidovdRiet]

I went over this list:

1. npm install @tanstack/react-table && npm uninstall react-table.
2. Change react-table to @tanstack/react-table.
3. Strip your table down to the bare minimum and implement the [basic example].(https://tanstack.com/table/v8/docs/examples/react/basic)
4. If you use React Query, the controlled pagination example is a great next step.
5. From this point go over all the docs examples that are applicable to your integration.

I had to go over literally every component in my integration. For my (more complex) integration it took almost a week to get everything right.

[laduke]

how long is v8 going to live?

[tannerlinsley]

Quite a while

[akraines]

Here are some notes from my migration experience:
See migration section in readme which is still to be expanded as per #4019 (comment) (@tannerlinsley's reply) and #4019 (comment) (@GuidovdRiet's experience)
First of all the fact that the new api is typed is a major upgrade in discoverability. Apart from that it is much easier to understand and extend, and comes with some great new features such as column pinning.
In general, although a lot changed, it is mostly superficial and once you get started in your migration you will get the hang of it and the rest should be intuitive:

1. Update column definitions:
   1. create a columnHelper using createColumnHelper [if you are using ts, then you can also pass in your row type]
   2. for each column object wrap it in columnHelper.accessor( [or .display etc], passing in the accessor as the first param and all the other fields will be in an options object in the second param
   3. Some name changes:
      1. Header => header
      2. Cell => cell [the cell render function has also changed - see below]
      3. disableSortBy [GroupBy etc.] => enableSorting [,Grouping etc.]
      4. sortType => sortingFn
      5. etc. [see the docs as you migrate each feature]
   4. Cell render function props:
      1. value => getValue [this is a theme throughout the upgrade: instead of providing the value directly, it now exposes a function for you to evaluate it. I assume that this is in order to improve performance - it only does the work to evaluate the value if you call getValue() and then it caches it]
      2. cell: {isGrouped, isPlaceholder, isAggregated} => cell: {getIsGrouped, getIsPlaceholder, getIsAggregated}
      3. column: the base level props are now RT specific. values that you add into the object when you define it are now one level deeper in columnDef
      4. table: props that you pass into the useTable hook now appear under options.
      5. row... [see the docs / inspect]
2. migrate the table render:
   1. same sort of theme as above,
   2. api for filters and aggregate is slightly different - there is an optional prep function and the filter function gets the row instead of all the rows
   3. there are a few ways to access rows from the table object "getRowModel" etc. Just inspect and you will learn the lay of the land in short order.
   4. just go example by example - the same way you setup your table in the first place.

This list is not exhaustive, but as you will see migrating is not as scary as it looks and the new api is much cleaner, more powerful, inspectable and extendable - Thanks @tannerlinsley and team for all your hard work in making this and making it available to everyone.

[tannerlinsley]

PR that into a new docs file and I’ll publish it Tanner Linsley

…

On Apr 25, 2023 at 9:51 AM -0600, akraines ***@***.***>, wrote: Here are some notes from my migration experience: First of all the fact that the new api is typed is a major upgrade in discoverability. Apart from that it is much easier to understand and extend, and comes with some great new features such as column pinning. In general, although a lot changed, it is mostly superficial and once you get started in your migration you will get the hang of it and the rest should be intuitive: 1. Update column definitions: a. create a columnHelper using createColumnHelper [if you are using ts, then you can also pass in your row type] b. for each column object wrap it in columnHelper.accessor( [or .display etc], passing in the accessor as the first param and all the other fields will be in an options object in the second param c. Some name changes: d. Header => header e. Cell => cell [the cell render function is also going to be update in the next step] f. disableSortBy [GroupBy etc.] => enableSorting [,Grouping etc.] g. sortType => sortingFn h. Cell render function props: i. value => getValue [this is a theme throughout the upgrade: instead of providing the value directly, it now exposes a function for you to evaluate it. I assume that this is in order to improve performance - it only does the work to evaluate the value if you call getValue() and then it caches it] j. cell: {isGrouped, isPlaceholder, isAggregated} => cell: {getIsGrouped, getIsPlaceholder, getIsAggregated} k. column: the base level props are now RT specific. values that you add into the object when you define it are now one level deeper in columnDef l. table: props that you pass into the useTable hook now appear under options. 2. migrate the table render: a. same sort of theme as above, b. api for filters and aggregate is slightly different - there is an optional prep function and the filter function gets the row instead of all the rows c. there are a few ways to access rows from the table object "getRowModel" etc. Just inspect and you will learn the lay of the land in short order. d. just go example by example - the same way you setup your table in the first place. This list is not exhaustive, but as you will see migrating is not as scary as it looks and the new api is much cleaner, more powerful, inspectable and extendable - Thanks @tannerlinsley and team for all your hard work in making this and making it available to everyone. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[akraines]

I think it would need to be re-written to be converted into a doc and I dont think I'll have time in the near future to do so - but I'd be happy to look it over if someone else does.

[KevinVandy]

I'll work on integrating this

[KevinVandy]

I have started a guide in the docs. I based some of it on @akraines summary. It probably covers more than half of the changes you will encounter. More to come in the future hopefully. https://tanstack.com/table/v8/docs/guide/migrating

[csantos-nydig]

Any clue on how to support https://github.com/TanStack/table/blob/v7/docs/src/pages/docs/api/useRowState.md #4140 ?

[akraines]

Great Job! From: Kevin Van Cott ***@***.***> Sent: Monday, May 8, 2023 1:18 AM To: TanStack/table ***@***.***> Cc: akraines ***@***.***>; Mention ***@***.***> Subject: Re: [TanStack/table] V8 Migration (Discussion #4019) I have started a guide in the docs. I based some of it on @akraines <https://github.com/akraines> summary. It probably covers more than half of the changes you will encounter. More to come in the future hopefully. https://tanstack.com/table/v8/docs/guide/migrating — Reply to this email directly, view it on GitHub <#4019 (comment)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADT7NB4SZ65TAAZ2QZ6G6BLXFANRVANCNFSM5YUGYDIQ> . You are receiving this because you were mentioned. <https://github.com/notifications/beacon/ADT7NB6LWRQJ64MX2AKLN2LXFANRVA5CNFSM5YUGYDI2YY3PNVWWK3TUL52HS4DFWFCGS43DOVZXG2LPNZBW63LNMVXHJKTDN5WW2ZLOORPWSZGOABMQACA.gif> Message ID: ***@***.*** ***@***.***> >

[TonyVeigel]

Is this upgrade to V8 worth it? I don't see any feedback in here about that and it seems like that was part of the original question. I have a double digit number of tables in my app. I did convert one table and did not notice anything that stood out performance wise or other, although I did find out upgrading all the tables is going to be a challenge to say the least. The migration guide helped but so many things changed that are not in the migration guide yet. This feels like a re-write vs an upgrade. And yes, if I do end up migrating, I will contribute to the migration docs.

[tannerlinsley]

• Typescript, so you will likely find bugs in existing code
• Just-in-time computation and memoization, so depending on the features you use, there is a big potential to run faster or save rerenders.
• State management is more robust for controlled/custom setups, so depending on your usage, you may find it easier to work with.