1. Developing Open Storefront Framework Applications for Oracle Commerce
  2. Set Up a Development Environment
  3. Upgrade the version of OSF in a workspace

Upgrade the version of OSF in a workspace

Oracle Commerce provides tools for upgrading your version of OSF to a newer version.

The OSF version in the Commerce registry is updated regularly. When you first create a workspace from the registry, the workspace has the latest version of OSF.

If you have been using a workspace that has an earlier version of OSF, you can upgrade the workspace using the upgrade command. This command updates the version of OSF packages used throughout the workspace. Typically it is used to upgrade to a higher-numbered version, though in certain cases it can also be used to downgrade to a lower-numbered version. Note that it does not update the version of non-OSF packages.

The primary way to use the upgrade command is to update the version of OSF in a workspace to the latest version allowed by your Commerce server, provided that both versions have the same major version number. To do this, invoke the command without any flags: 

yarn occ upgrade

So, for example, if the current OSF version is 2.2.3 and the latest version the server supports is 2.6.7, this command updates the workspace to version 2.6.7.

If you're uncertain of the effect an upgrade command will have on your workspace, you can invoke the command with the --dryRun flag. This returns a list of the changes the command would make but does not actually make them. For example: 

yarn occ upgrade --dryRun

If the changes are what you expect, you can then run the command without the --dryRun flag.

If the current workspace version of OSF is newer than the latest version the Commerce server supports, or if the workspace has a different major version number from the server, the upgrade command produces a warning and exits. You can override this behavior by using one or both of these flags:

  • --acceptDowngrade – If the current workspace version of OSF is newer than the latest version the Commerce server supports, the workspace is downgraded to the latest version that the server supports.
  • --latest – The workspace is updated to the latest version the server supports, even if the workspace and the server have different major version numbers. Be aware that updating to a different major version may introduce breaking changes.

To upgrade to a specific version of OSF, specify the version number explicitly in the command. For example:

yarn occ upgrade 2.13.6

If the specified version number is lower than the current workspace version, include the --acceptDowngrade flag.

Special options

The following flags may be useful in certain circumstances, but you should use them with caution:
  • --no-verifyOcc – The command does not check the server version when determining what version of OSF to upgrade to.
  • --force – The command attempts to continue rather than exiting when encountering errors (version incompatibilities, inability to contact the registry or Commerce servers, etc.). Can be used only if a specific version of OSF is specified. For example:
    yarn occ upgrade 2.0.0 --force

If you use either of these flags, be sure you understand the implications. It is a good idea to try the command with the --dryRun flag first to see the changes it will make before running it normally.