Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

4.0 KB
Raw Blame
---
title: Quickstart
description: Learn how to upgrade your Spree application
---

Keeping your Spree installation up-to-date is essential to keep it safe and secure. Each Spree version brings new features, enhancements and bug fixes so it's greatly beneficial for you and your clients to upgrade frequently.

The upgrade process is fairly easy and well described. Of course, it all boils down to the level of customizations and the way you've customized your Spree applications.

We strongly advise upgrading Spree incrementally, rather than in one big go.

## How to upgrade

An upgrade updates the server and the `@spree/*` packages of your dashboard apps, migrates the database, and runs the version's data backfills. Always read the guide for the version you're moving to first — it lists the behavior changes to review.

<Tabs>
  <Tab title="Spree CLI">
    ```bash
    spree upgrade
    ```

    One command for every project: it pulls the new image, or updates the Spree gems on an [ejected](/developer/cli/quickstart#spree-eject) project, then updates the packages and runs migrations and data backfills. See [`spree upgrade`](/developer/cli/quickstart#spree-upgrade) for its options.
  </Tab>
  <Tab title="Without CLI">
    Run from the project root:

    ```bash
    (cd server && bundle update $(bundle list --name-only | grep ^spree))

    # The project root and each dashboard app have their own package.json
    pnpm update "@spree/*"
    (cd apps/dashboard && pnpm update "@spree/*")
    (cd apps/seller-dashboard && pnpm update "@spree/*")

    cd server
    bin/rails spree:install:migrations db:migrate
    bin/rails spree:upgrade
    ```

    On npm or Yarn, run `npm update` or `yarn upgrade` instead, naming each `@spree/*` package from that `package.json` (they do not accept the `"@spree/*"` pattern).

    `update` never moves a package pinned to an exact version, such as `"@spree/dashboard": "6.0.0"`. Install the version you are upgrading to by name instead, the same version as the Spree gems on your server, then fold duplicate copies of shared dependencies together, in each directory you changed:

    | Package manager | Install the new version | Fold duplicates |
    | --- | --- | --- |
    | pnpm | `pnpm add --save-exact @spree/dashboard@<version>` | `pnpm dedupe` |
    | npm | `npm install --save-exact @spree/dashboard@<version>` | `npm dedupe` |
    | Yarn 2 or later | `yarn add --exact @spree/dashboard@<version>` | `yarn dedupe` |
    | Yarn 1 | `yarn add --exact @spree/dashboard@<version>` | Not available |

    Moving from a release candidate pin such as `6.0.0-rc.7` to 6.0, change the pin to a range such as `^6.0.0` in `package.json` instead, then run `update` as above. Installing over an exact pin by name keeps it exact.

    Add `--save-dev` (pnpm and npm) or `--dev` (Yarn) for a package listed under `devDependencies`. Without the dedupe step, a dependency that the new version pins, such as `@codemirror/view`, can end up installed twice and fail type checks.
  </Tab>
</Tabs>

## Support

If you're stuck and would want to get some professional help, you can [contact us directly](https://spreecommerce.org/contact/) and request a quote for our consulting services.

## Release types

Spree development follows a shifted version of [Semantic Versioning](https://semver.org/):

**Patch Z, eg. 4.2.1**

Only bug fixes, no API changes, no new features. Except as necessary for security fixes.

**Minor Y, eg. 4.2.0**

New features, may contain API changes Serve as major versions of Semver. Breaking changes are paired with deprecation notices in the previous minor or major release.

**Major X, eg. 4.0.0**

New features, will likely contain API changes. The difference between Spree minor and major releases is the magnitude of breaking changes and is usually reserved for special occasions.

## Security

Our Security policy is [described here](/developer/security).

When a release series is no longer supported, it's your own responsibility to deal with bugs and security issues. We may provide backports of some critical security fixes.