Saltar al contenido principal

Upgrade steps (latest)

Some versions of Jutro require manual upgrade steps. If you are upgrading from a version that is earlier than the most recent version, you must apply the manual steps in order. Start from your current version and apply the manual steps for each version up to the latest version.

10.10.0​

Check out the release notes page for a list of deprecations, known issues, and more.

Migration from resolutions to npm overrides​

If your app currently uses the @jutro/cli-npm-preinstall package, you need to perform the following steps to migrate to the npm native overrides solution:

  1. Remove preinstall.js file from project root.
  2. Remove preinstall script from package.json.
  3. Rename resolutions in package.json to overrides.

For more information, see the release notes.

Migration from active token renewal to passive token renewal​

Passive token renewal was introduced in version 10.10. Active renewal is not deprecated, but it is recommended to move to passive renewal. To enable this feature, you need to perform the following steps:

  1. Elimine las variables JUTRO_AUTH_SILENT_REDIRECT_PATH y JUTRO_AUTH_SILENT_LOGIN_PATH, si están presentes. Estas variables son específicas del método activo con inicio de sesión silencioso y no son necesarias para el método pasivo.
  2. Agregue offline_access a la variable JUTRO_AUTH_SCOPE.
  3. Asegúrese de que la configuración de la aplicación Guidewire Hub incluya la concesión REFRESH_TOKEN en su matriz authSettings.grantTypes.
  4. Agregue la variable JUTRO_AUTH_USE_PASSIVE_TOKEN_RENEWALS=true.
  5. Reemplace los siguientes usos de propiedades desde el gancho useAuth:
Renovación activaRenovación pasiva
isAuthenticated: boolean | nullgetIsAuthenticated: () => Promise<boolean | null>
accessToken: string | nullgetAccessToken: () => Promise<string | null>
idToken: string | nullgetIdToken: () => Promise<string | null>
userInfo: OidcUserInfo | nullgetUserInfo: () => Promise<OidcUserInfo | null>

For more information on passive renewal, see the authentication client documentation

10.9.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.8.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.7.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.6.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.5.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.4.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.3.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.2.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.1.0​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

10.0.0​

Check out the release notes page for a list of deprecations, known issues, and more.

Some migration hints are available on the "Go to 10" page.

Update required to override default Jutro styles​

Since Jutro 10.0, all Jutro components in micro frontend applications have increased specificity of style selectors. For example, jut__Button__button is now .appName .jut__Button__button.

NOTE: appName comes from webpack.moduleFederation.name in overrides.config.js

This happens for all applications exposed as micro frontends, regardless if they are consumed through module federation, iFrame, JutroMicroFrontends SDK or accessed directly as a standalone. This is also not configurable.

This is a breaking change for styleOverrides.cssand is necessary to override Jutro default styles.

New Jutro Platform CLI tool replacing the initial Jutro and toolset CLIs​

Make sure that your application is based on Jutro 8.10.x or greater version. To migrate to the new Jutro Platform CLI, follow the Jutro migration guide.

Support for React Testing Library (RTL)​

The React Testing Library (RTL) packages @testing-library/react@14.0.0 and @testing-library/user-event@14.4.3 have been marked as peer dependencies so they need to be installed manually.

Support for Enzyme has been deprecated since Jutro 6.5.x. If you need to migrate to RTL, follow these steps:

  1. Make sure that your application is based on Jutro 8.10.x or greater.

  2. Rewrite your remaining Enzyme-based unit tests to use RTL instead. A fully automated migration is not possible in this case and needs to be done manually.

  3. Optional, though strongly recommended: Ensure your RTL-based unit tests do not make use of the deprecated userEvent API from the @jutro/test package. It is based on the older version of the @testing-library/user-event library and might not always work with modern app setups, e.g. with React 18. Instead, it is recommended to just use the latest available version of the @testing-library/user-event (>= 14.4.3) library directly in the application itself.

If you are upgrading from a Jutro version prior to 10.0.x, we recommend a gradual migration of the tests by only adding all the new tests in RTL already (it is fully possible to have part of your unit tests suite remaining in Enzyme but already have some other tests added in/migrated to RTL). Examples and guides provided by the authors of RTL can be really helpful with that activity. Jutro also provides some helper functions that can make writing tests in RTL easier and demonstrates examples of the most common migration patterns in the documentation.

NOTE: This change also implies the Enzyme-specific helper APIs that are part of the @jutro/test package getting decommissioned.

Support for Node 18 replacing the support for Node 16​

  1. Make sure that your application is based at least on Jutro 8.10.x version.
  2. Follow the steps provided here to switch your application to use Node 18 instead.
  3. Ensure both your application code, local dev environments, and CI configuration are updated to use Node 18.

Support for webpack 5 replacing the support for webpack 4​

  1. Make sure that your application is based at least on Jutro 8.10.x version.
  2. Follow the steps provided here to switch your application to use webpack 5 instead.

NOTE: This change also implies stopping the continuous releases of the @jutro/overrides NPM package as a whole, and the decommissioning parts of the @jutro/build-tools package that are specific to webpack 4. We recommend completely moving away from using those APIs today already.

NOTE FOR MICROFRONTENDS (SHELL/MICRO APP) OWNERS: Jutro 8.9 already drops the support for the integration of micro frontend applications with the webpack 4-based Module Federation mechanism. Webpack 5-based mechanism is the only available method in that version of Jutro already. Hence it is crucial for all the micro frontends (shell/micro) applications that are integrated to migrate to webpack 5 and get deployed to the appropriate common environments before any of them becomes upgraded to Jutro 8.9+. Not following that pre-requisite may result in temporary downtimes for those applications.

The following steps describe the recommended upgrade path to avoid the risk of downtimes:

  1. Switch both the shell and all the integrated micro frontends to Jutro 8.8.x.
  2. Get them deployed to the common environment. This step can be taken for each integrated app independently, without risking downtimes, as Jutro versions greater than 8.0.x and prior to 8.8.x still do provide micro frontends integration compatibility between apps using webpack 4 and webpack 5.
  3. After that, start switching any of the integrated apps to Jutro 8.9.x and getting them deployed to the common environments.

Support for React 18 replacing the support for React 17.​

  1. Make sure that your application is based at least on Jutro 8.13.x version.
  2. Optional, though strongly recommended: ensure your RTL-based unit tests don't make use of the deprecated userEvent API from the @jutro/test package since it is based on the older version of @testing-library/user-event library and might not always work in the modern app setups, e.g. with React 18. Instead, it is recommended to use the latest available version of the @testing-library/user-event (>= 14.4.3) library directly in the application itself.

GlobalizationStore replacing LocaleService​

  1. Make sure that your application is based at least on Jutro 8.13.x version.
  2. Follow our guide describing the migration of your application to GlobalizationStore for the locale service.

NOTE: As a side-effect of this change the @jutro/locale's LocaleSettingsInterface is also decomissioned. The preparation step for that change is simply recreating this interface on the particular application side, as described here.

Generic OIDC client replacing Okta-specific auth client​

  1. Make sure that your application is based at least on Jutro 8.13.x version.
  2. Optional: As a result of the new generic OIDC client not having a full feature-parity against the Okta-specific client, a potential need may arise to implement an alternative e.g. for the Okta-client TokenManager. The main functionality that is provided by TokenManager is handling token-related events. For the rare cases where this functionality might still be needed by the app after switching to the new auth client, we recommend implementing the events handling on the app side instead, as described here.

Removed all the leftovers from the experimental props and APIs added before the productization.

  • Remote URLs configuration through the microAppConfig param is getting renamed to microFrontendsConfig.
  • The ability to pass from the shell app to the micro frontend app the routerBinding config with a specification of shellHistory is decommissioned.
  • Consumption of the following properties passed from the shell app to the micro frontend through the jutro object is decommissioned: launchPropOverrides, configOverrides, routerBinding, globalizationOverrides, authOverrides, and iframe.
  • API decommissioned in Jutro 10:
    • Removal of deprecated MFE APIs.
    • Direct consumption of @jutro/micro-frontends start() function second argument, launchProps, getting replaced by a consumption of a nested mfeData attribute of the same launchProps second argument of that function.
    • Direct consumption of @jutro/micro-frontends start() function third argument, scriptAttributes getting replaced by the consumption of the same data through a nested mfeData attribute of the second launchProps argument of that function.
    • Several deprecated MicroFrontendsSdk.createRoot parameters are getting updated/decommissioned: consumption of the source descriptor object as the second argument of that function getting replaced with consumption of a string, consumption of jutro.routerBinding object in the first argument of RootType.render is getting replaced by the consumption of jutro.router, consumption of jutro.globalizationOverrides object in the first argument of RootType.render is getting replaced by the consumption of jutro.configOverrides, consumption of jutro.authOverrides object in the first argument of RootType.render is getting replaced by the consumption of jutro.auth, consumption of jutro.iframe object in the first argument of RootType.render is getting replaced by the consumption of the respective attributes of the jutro object.

To prepare your app for these changes:

  1. Make sure that your application is based at least on Jutro 8.13.x version.

  2. After having migrated to the productized version of the micro frontends API and seeing a risk of being impacted by the further cleanup of this API coming in Jutro 10.0.x, then depending on the impact:

    • In case of being impacted by the rename of the microAppConfig config parameter name, then search and replace with microFrontendsConfig all the occurrences of this name across your application codebase.
    • In case of being impacted by the restructuring of the parameters accepted by the @jutro/micro-frontends start() function, then ensure your configuration is passed to it through the nested mfeData attribute of the second launchProps argument of that function. More details here.
    • In case of being impacted by the changes related to the restructuring of configuration parameters accepted by the MicroFrontendSdk.createRoot then ensure your configuration is passed to it as follows: Source descriptor object (2nd argument of createRoot) is replaced with a string and the following attributes passed through the jutro object are replaced appropriately:
      • jutro.routerBinding -> jutro.router
      • jutro.globalizationOverrides -> jutro.configOverrides
      • jutro.authOverrides -> jutro.auth
      • jutro.iframe -> corresponding properties of the jutro object

  3. Verify that there are no deprecation warnings related to the micro frontend integration appearing in the browser dev console for either the shell or micro frontend apps. Anything flagged in there should be addressed according to the steps suggested by the warning.

Jutro 10.x-based shell apps can only communicate with 10.x or 8.13.x based micro frontends​

  1. Make sure that your application is based at least on Jutro 8.13.x version.
  2. Verify that none of the decomissioned parts of the micro frontends API are used by your app.
  3. Ensure that the versions of the shell and micro frontend applications are integrated based on compatible versions of Jutro.

Fix sharing configuration micro frontends override​

This is only applicable to the applications integrated into micro frontends-based systems:

  1. Verify that there are no divergencies in the sets of runtime configurations between the shell and the micro frontend applications integrated. Unify them if that is not the case.
  2. After the upgrade of applications to Jutro 10.0.x the exact set of runtime configurations used by all the applications will always be the one specified by the shell app.

Fix leakages of styles between different micro frontend applications​

This is only applicable to the nested micro frontend applications integrated into micro frontends-based systems:

  1. Make sure that your application is based on Jutro 8.13.4 or greater. A pre-requisite for getting any of the micro frontend apps in the set of those integrated into a single system, updated to Jutro 8.9+ is all the apps in that set having webpack 5 adopted, and being deployed to the common environment in such a shape first. In case the app does already make use of the new Jutro Platform CLI as well, then ensure the version of that tool used by your application is at least the latest 8.41.x available at the current moment (8.41.15 at the very minimum).
  2. Ensure the shell app within which your micro frontend is supposed to be embedded, gets updated to at least Jutro 8.13.0 as well and becomes deployed to the common integration environment in such a shape.
  3. Give a try to the new functionality by adding to your application .env file the following line: REACT_APP_USE_NEW_MFE_CSS_ORDERING=true. This might require some extra adjustments to the current app's custom styles. NOTE: The flag can also be removed later on, after getting the application updated to Jutro 10 already since the functionality will be always enabled in that release by default.

Google Analytics GA4 built-in integration capability replacing the corresponding one for Google Analytics Universal Analytics. Environment variables backing the configuration of that integration getting unified.​

  1. Make sure that your application is based on Jutro 8.10.x or greater.
  2. Ensure your Google Analytics service is based on Google Analytics 4.
  3. Verify that your Google Analytics integration key is configured using the REACT_APP_GA4_TRACKING_ID environment variable. Starting from Jutro 10.0 it is the only parameter available for the integration with Google Analytics.

If impacted by the removal of the locale-related HTTP headers injection: start using the @jutro/transport addOption API on top of the result of calling createHttpRequest to inject the headers on the application side.

General UI theme replacing the Flaine UI theme in the @jutro/theme-style package.​

  1. Make sure that your application is based on Jutro 8.13.x or greater.
  2. Replace your current references to the Flaine theme with General instead.

Built-in TSM integration capability getting decommissioned.​

According to our records, the demand for those functionalities across current Jutro consumers should be very low. If your application is impacted by these changes, reach out to us on the #ask-jutro channel to discuss a possible transfer of the functionality ownership.

Replace the remaining usages of those components with an appropriately configured Floorplan.

Replace the remaining usages of those components with @jutro/layout Grid, GridLayout, and Flex components.

Several UI components getting removed from the Jutro public API surface: StickyFooter, JsonForm, TabbedContainer, ColorSwatch, and PageLayout​

According to our records, the demand for those functionalities across current Jutro consumers should be very low. If your application is impacted by these changes, please reach out to us on the #ask-jutro Slack channel to discuss the possible transfer of ownership over the decommissioned functionality.

According to our records, the demand for those functionalities across current Jutro consumers should be very low. If your application is impacted by these changes, please consider moving the validation of your metadata file(s) to the application build time.

In case of a need to validate metadata files against the JSON schema as part of unit tests, it is recommended to switch to using the open source npm lib jest-json-schema instead of the validateMetadata API.

id prop from @jutro/components QuickView React component decommissioned​

Please stop specifying this prop explicitly. It will be auto-generated for your QuickView instance. If needed, please reference the instances of this component in tests, etc. in alternative ways.

@jutro/lab-preview-test-e2e NPM package replaces @jutro/e2e-tests​

  1. Make sure that your application is based on Jutro 8.10.x or greater.
  2. Search and replace all the references to @jutro/e2e-tests package across your application code to @jutro/lab-preview-test-e2e.
  3. Remove the dependency @jutro/e2e-tests from your application package.json file.

Removal of the automatically attached __docgenInfo attribute from all the @jutro/* React components​

According to our records, the demand for this functionality across current Jutro consumers should be very low. If your application is impacted by these changes, please reach out to us on the #ask-jutro Slack channel to discuss the possible alternatives or migration path.

NOTE: This change also implies the removal of the Metadata tab in the Jutro Storybook. Jutro consumers are recommended to specify their UIs using JSX instead of the UI Metadata Configs.

Several React components and functionalities are getting moved to the @jutro/legacy NPM package.​

The purpose of @jutro/legacy package is to contain deprecated features for their long term availability before they are decommissioned. The deprecated term refers to functionality or components that are in the process of being replaced by newer ones or being removed entirely.

You can learn more about this package here.

The only suggested action for such functionalities to be taken for now is just moving away from using them, as soon as possible. For the cases where that may not be feasible for some reason, the upgrade to Jutro 10.x will automatically update the remaining references to such functionalities across the application code to look for them under the @jutro/legacy package going forward instead, which will be the only breaking change related to those functionalities taking place in Jutro 10.0.

A detailed list of the component changes can be found here.

Reorganization and updates of several third-party libraries that Jutro NPM packages rely on​

No preparations should be needed for now. Most of the related updates needed resulting directly from Jutro changes should be handled automatically by the upgrade tooling while applying the switch to Jutro 10. It is possible though that updates of some 3rd party dependencies may result in facing some breaking changes initiated by the updates in these dependencies, which we cannot fully predict yet.

Packages and functions decommissioned due to low demand​

The following packages and functions have been decommissioned due to the lack of usage. If your application is impacted by any of these decommissions, reach out to #ask-jutro Slack channel to discuss a possible transfer of the functionality ownership.

  • Experimental metadata-specific NPM packages: @jutro/lab-preview-html-metadata-loader and @jutro/ lab-preview-metadata-converter
  • The following functions from the @jutro/uiconfig package: generateUIFromSchema, useJsonSchema, and extractSubSchema.
  • The @jutro/storybook-presets NPM package.
  • The following parts from the @jutro/transport package: zipkinTraceHandler and createHttpRequest built-in injection of the locale-related HTTP headers. If your application is affected by this change, follow these steps:
    1. Make sure that your application is based on Jutro 8.10.x or greater.
    2. If impacted by the decommission of zipkinTraceHandler: The Jutro team would be happy to transfer the ownership over this functionality to the last remaining consumer(s).
  • The textWasTranslated helper function from @jutro/test. If your application is affected by this change, follow these steps:
    1. Make sure that your application is based on Jutro 8.10.x or greater.
    2. Switch the remaining usages to the @jutro/test getTranslation API.

(Pre-)commit hooks handled by Husky are getting standardized​

  1. Wait for the auto-upgrade PR with a switch to Jutro 10 provided to your application
  2. Review the change around an automated upgrade of a dependency on Husky to v8, and the standardization of its pre-commit and commit hooks in the PR.
  3. Accept the change or revert it before getting the upgrade PR merged

Remove always-auth config option​

Jutro 10 uses npm > 6 which does not have an always-auth config option. You need to remove the npm config set always-auth true line from your .npmrc file.

8.13.14​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.13​

Check out the release notes page for a list of deprecations, known issues, and more.

Support for Node 22 replacing the support for Node 18​

We recommend you use Node.js v22. This is completely optional. Consider, however, that Node.js v18 is getting EOL in April 2025, so you should be ready to make this change. If you want to migrate, do the following:

  • Update the engines field in your package.json to:
  "engines": {
    "node": ">=22.6.0 < 23",
    "npm": ">=10.8.2 "
  }
  • (Optional) If you use NVM to manage Node versions - update .nvmrc with v22.6.0
  • Install Node.js v22.6.0 (and if you are not an NVM user, remove the old version)
  • Update any unit tests which use Intl (Node.js v22 is updated according to the latest version of Intl).

To check if your app still works with a newer version of Node.js (for example on TC pipelines), do the following:

  • Update the engines field in your package.json to:
  "engines": {
    "node": ">=22.6.0 < 23",
    "npm": ">=10.8.2 "
  }
Warning: Known issue

A change in translation process in Node 22 results in a space character being replaced with a unicode narrow no-break space https://www.compart.com/en/unicode/U+202F. This may result in failed unit tests as this does not match the \s regex pattern.

Note: Different versions of Node.js on local and CI environments might lead to inconsistent behavior of unit tests for components which use Intl

8.13.12​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.11​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.10​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.9​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.8​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.7​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.6​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.5​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.4​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.3​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

8.13.2​

There are no manual upgrade steps for most apps and upgrade is mostly automated. Check out the release notes page for a list of deprecations, known issues, and more.

To upgrade React to version 18, you must update the version of react and react-dom of your package.json. Besides, if you want to use React 18 and use React Testing Library (RTL) for testing, you must manually upgrade @testing-library/react to version 14.0.0 by adding it to the resolutions section in your package.json:

"resolutions": {
    "@testing-library/react": "14.0.0",
}

We recommend that your RTL-based unit tests do not use the deprecated userEvent API from the @jutro/test package. It is based on an older version of @testing-library/user-event and might not always work as expected in a modern app, for example one with React 18. Instead, we recommend you use the latest available version of @testing-library/user-event (>= 14.4.3) directly in the application.

On this page