Technical migration from grommet-v1 to grommet-v2
Migrating from grommet-v1 to grommet-v2 may feel intimidating at first, but I’ve survived to tell you it is not that scary, and I’m here to share my experience.
The migration requires two separate efforts:
1. Migrating webpack, babel.rc, package.json, and cleaning redundant libraries
2. Migrating grommet-v1 code to use grommet-v2 components
Different migration styles can be applied to complete the migration; one should consider the timeline, the project size, and have a good technical understanding before applying a migration method.
For example, if your project is large and your timeline is short, you may consider a side by side migration where you have both grommet-v1 and grommet-v2 running, so you are starting to use grommet-v2 for new development and gradually migrating grommet-v1 components along the way.
In my case, the timeline was two days, the project to migrate was relatively small and contained ~10 components that needed to be migrated. I was brand new to grommet-v2 and familiar with React and grommet v1. Hence, I took the approach of diving into grommet-v2 and getting the v2 ‘Big Bang’ all at once. I found this way cleaner, and it helped me clean up redundant imports, libraries, and dependencies while having more control in customizing the components I was using.
For a closer look at the migration work, take a look at the migrated repo of grommet-sample. grommet-sample was originally written in grommet-v1, and I took the challenge of migrating it to v2 while maintaining the same functionalities, and a similar look and feel.
Grommet-v1 components were migrated to v2, and the v1 look and feel were obtained by using grommet-theme-v1. For comparison use the following repositories:
Grommet-v1 grommet-sample, Grommet-v2 grommet sample
Phase #1 Starting the Migration
First, get familiar with the project you are migrating, understanding its content, dependencies, the library versions, and their required compatibility with grommet-v2.
After understanding what cleanups are required, I started with targeting the redundant libraries; grommet-cli, grommet-addons, sass/styling libraries were unnecessary, so I initially removed those and made sure the project still stands without failures.
All cleanups are applied, the project is slimmer and ready for the upgrade, applying the grommet-v1 upgrade to grommet-v2 as follows:
yarn upgrade –latestAfter the upgrade runs successfully, go to your package.json and verify the following:
1. React.js upgraded to ^16.4
2. Grommet upgraded to ^2.0.0
3. All webpack dependencies are upgraded to version ^4.0.0
4. All babel dependencies are upgraded to version ^7.0.0
5. Update the webpack.config.js file and babel.rc, for references, and examples use grommet-sample
Run yarn add styled-components, and verify package.json styled-components is updated to version ^4.0.0. This will help you use the <Grommet ..> component in phase #2.
All dependencies are up to date! Woot-woot!! 🙌
You are ready for phase #2!
Phase #2 Migrating Components
Make sure you have a new clean installation: remove node-modules and run yarn cache clean before runningyarn install.
Run your app (e.g. yarn start), and you should see errors coming from your running app. These error messages are your step-by-step guide to migrate the grommet-v1 components; each error will name the grommet-v1 component that needs to be migrated.
1. App
Most likely, the first error will be on the grommet-v1 <App …> component, <App …> is being replaced with <Grommet …> component.
So, remove the App Component:
import App from 'grommet/components/App;<App centered={false}>
And add the Grommet Component instead:
import { Grommet } from 'grommet';<Grommet full={true}>
To polish the usage of <Grommet ..>, it will be useful to embed the theme you will be using on your application, for this example, I used the grommet-v1 theme to maintain grommet-v1 look & feel on the migrated project:
import { v1 } from 'grommet-theme-v1';<Grommet full={true} theme={v1}>
For more information on how too yarn add the grommet-v1 theme, or any other out of the box theme, please use the grommet documentation. E.g., grommet-theme-v1 and feel free to ask us questions about the Theme concept.
2. Header, Footer, Section, Article
Common errors you’ll next see will be on the following v1 components:
<Header …> <Footer …> <Section …> <Article …>
they are often used in grommet-v1.
grommet-v2 allows these common HTML tags to be used as part of the Box component, e.g., <Box tag='header'> , in v2 the Box is able to contain these components as a tag, you can remove all Header/ Footer / Section/ Article /… from your application.
Practical examples — and many of them — , can be found here
3. Title
This is a super easy one, in case you were using a grommet-v1 <Title …> component, migrate it to grommet-v2 <Text …> and customize its size and weight as you wish (or you can just embed it in a theme)
Remove Title component:
import Title from 'grommet/components/Title';<Title>Todo App</Title>
Add Text component instead:
import Text from 'grommet/components/Text';<Text>Todo App</Text>
<Text> is only the plain version of <Title>.
In grommet v2 we have the flexibility to get the plain text to have more of a Title-like appearance.
Customizing:
<Text size='large' weight='bold'>Todo App</Text>
Click here, for more examples on how to customize Text.
4. Form/ FormFields
The above grommet-v1 components are not part of grommet-v2.
For replacing <Form …>, simply replace with the html5 tag of <form ..>.
Remove <Form>:
<Form onSubmit={this._onSubmit}>
Add <form>:
<form onSubmit={this._onSubmit}>
The <FormFields …> wrapper is no longer required and should be simply removed.
The <FormField> component is supported in grommet-v2, and does not need additional customization.
Again, this is the plain version of migrating <Form> from v1. On grommet-sample migration I had to wrap the plain HTML <form> with a <Box> to get the large padding I needed, your project might have different tweaks.
5. Select
grommet-v2 is offering a new component of <Select …>, so any usage of the html5 <select …> component can be enhanced and replaced by using grommet-v2 <Select… >
I found the use of this component straightforward and easy to use after understanding the examples, and having a simple <Select> component.
For more info on the Select component documentation and usage examples.
6. List/ ListItem
No longer supported with grommet-v2, and although I wasn’t sure how to handle it at first, after implementing the plain version of these components using simple <Box>, I had a room for flexibility on how I’d like the <List> and <ListItem> components to be implemented and customized.
In this example, I redefined the implementation of <List><ListItem> using the simple html ul and li as follows:
const List = props => <Box fill tag='ul' border='top' {…props} />;const ListItem = props => ( <Box tag='li' border='bottom' pad='small' direction='row' justify='between' {…props} />);
With my new customized definitions of <List> and <ListItem> I was able to keep the components in my project while removing the v1 imports, hence using my customized implementation. I had full control on the <List><ListItem> implementations inside the grommet-sample migration app.
The migration is mostly done for me, but I know you might experience different components that still need migration. Feel free to send me a message or hit our slack community with comments and questions and let us know how the migration experience went for you, and if there are more components you want technical advice on before performing the migration.
Good luck and we are here for you!
Shimi
