Upgrading Grouparoo

Last Updated: 2022-02-01

Grouparoo will regularly publish new versions of the packages that compose your Grouparoo application. Grouparoo packages are published to npm under the @grouparoo. You can view a list of packages in the @grouparoo organization here.

We strongly recommend that you update your Grouparoo application as soon as a new version becomes available. In addition to new features, new versions are likely to contain bug and security fixes.

Upgrade Guides

Our upgrade guides will help you through the process of upgrading when the new version contains a breaking change. Here is a list of available upgrade guides:

Determining if There are Updates

There are a few ways to determine if there are updates to the packages that make up your Grouparoo application:

In the App

If you visit the /about page of your Grouparoo server, you'll see a list of the packages you have installed, the current version installed, and the latest version available on npm.

In App Versions

Release Notes

Grouparoo publishes release notes for new versions at https://github.com/grouparoo/grouparoo/releases. Here you can see when each new version was released, and what was added.

Release Notes

Tools from the Node.JS ecosystem

As Grouparoo is a Node.js application, there are a number of tools available to automatically notify you when there's an update to a dependency in your package.json file. Two recommendations are:

  • Depnedabot - If you store your Grouparoo application in git hosted on Github.com, you can use Dependabot to check for dependency updates every day, week, or month. An example dependaboy.yml is available here.
  • npm-check-updates - The npm check updates package can be used in your Grouparoo project to scan your package.json and update the versions of your dependencies.

Installing Updates

Running New Versions

In most cases, all that is needed to update your Grouparoo application is update the versions of your dependencies in your package.json file, then run npm install.

Upgrade Diff

The grouparoo update command can help you with this process and update all of your plugins to the latest versions;

Always start by ensuring you have the latest version of the Grouparoo CLI:

npm install -g grouparoo

Then you can use the grouparoo update command.

$ grouparoo update
šŸ¦˜ Upgrading Grouparoo Project

ā„¹ path: /private/tmp/groo
ā„¹ Upgrading dependencies...
āœ” Updated @grouparoo/core to version 0.2.12
āœ” Updated @grouparoo/mailchimp to version 0.2.12
āœ” Updated @grouparoo/postgres to version 0.2.12
āœ” Updated @grouparoo/ui-community to version 0.2.12
āœ” Installation Complete!

Depending on your method of deployment, you will need to either re-deploy your application, git push to Heroku, or publish a new Docker image.

Some cases will require additional effort. See our Upgrade Guides (listed above) for more info.


The Grouparoo application uses migration files to describe changes in the schema of the Grouparoo Application Database. Any new release may contain a change to this schema and include a new migration file.

The Grouparoo application will automatically attempt to run pending migrations as the application starts. There is no special step needed to migrate your database.

Breaking Changes

Grouparoo follows Semver versioning. This means that our version numbers mean major.minor.patch. Any breaking changes we make will result in a major version change. However, per Semver convention, we will not start tracking breaking changes until we reach version 1.0.0. This means that before version 1.0.0, any new version may contain a breaking change.

Please be sure to read the release notes before upgrading.