Forma 36 - FAQ

What does Forma 36 v4 mean for developers?

Smaller bundles for faster apps - In v4, components are in separate packages, meaning you can use those you need without adding the full suite to your bundle. This change makes bundle sizes much smaller and improves app performance — particularly for those only using a few components from the library. For example, you can import a Button component and tree shaking will make sure its the only component that ends up in your bundle. By importing just one component, v4 bundle sizes become 85% smaller than those in v3.
We’ve added Emotion to our components - With this change, every component encapsulates their own styles, there’s no need to import separate Forma 36 CSS file into your project anymore.
Consistency in code style guide - In v4, our API and code style guide align. This means all the components follow the same structure and name convention — they’re the same across all properties.
No more importing separate components - With v4, our APIs have compound patterns, eliminating manual work on your end. Here’s an example of what that looks like:

Instead of:

import { List, ListItem} from ‘@contentful/forma-36-react-components’
<List>
  <ListItem></ListItem>
</List>

now you can:

import { List } from ‘@contentful/f36-components’
<List>
  <List.Item></List.Item>
</List>

What does Forma 36 v4 mean for enterprise customers?

Greater accessibility - We believe that the web should be accessible to everyone, so v4 brings Web Content Access Guidelines (WCAG) Level AAA compliance to all of our React components. We’ve updated many components to fulfill a11y requirements and have resolved many of the accessibility issues previously voiced by customers.
Accelerated speed - V4 splits components into separate packages, meaning you can use those you need without adding the full suite to your bundle. This change makes bundle sizes much smaller and improves app performance — particularly for those only using a few components from the library. By importing just one component, v4 bundle sizes become 85% smaller than those in v3.

How do I migrate my existing project to use Forma 36 version 4?

We built tools that enable automatic migration, so that the process is fast and straightforward. To migrate your existing project to Forma 36 v4, simply run our codemods. Here’s detailed documentation on how to do that.

To migrate your existing project to use version 4, you need to run:

npx @contentful/f36-codemod

Note: When running this command for the first time it installs the package in the NPM cache. Make sure you run it again.

Select the first option from the list: run-all-v4. This codemod will adjust your package.json, install new packages, remove old ones, and also remove the CSS imports required for version 3.

Several components don’t have codemods and must be migrated manually. Here’s a list of those components with linked documentation on how to migrate them:

When do I need to update my apps to v4?

V3 will be supported until July 12, 2022, six months after the release of v4. Although v3 will be available after this, it won’t be updated further or supported by Contentful. For these reasons, we recommend migrating to v4 within the six-month transition period.

Until July 12, 2022, Contentful will support Forma 36 v3 for the following:

Minor API changes
Bug and issue fixes
Support for issues while migrating from v3 to v4

Will I need to redesign my app?

No. There are no major visual changes in v4, so there is no need to redesign apps. To migrate your apps to the new version, use our migration guide.

Why rename things (components, properties), instead of leaving them as they are?

To resolve some issues, we needed to remove or rename components

For example the Dropdown component was being used to cover many use cases and its API got very complex, leading to issues for our users. Additionally, it did not meet the a11y requirements that were key for v4. Therefore, we split this component into smaller ones that are more suitable for specific use cases:

Menu offers a list of choices to the user, such as a set of actions or links. Menu uses the Popover component as a base. It covers most of the examples where you previously used the `Dropdown component.
Popover is used to display some content on top of another, and should be paired with a clickable trigger element. It is a base component for Menu, but not styled and not handled. If you need to create a specific, custom solution, then this would be the right choice.
Autocomplete is an input field that provides selectable options as a user types into it. It allows users to quickly search through and select from large collections of options.

How much effort is it to migrate apps from v3 to v4??

To make the migration as easy as possible, we have built tools to automate the process. To migrate your existing project to use version 4, you need to run:

npx @contentful/f36-codemod