Best practice for Strapi version updates

Questions and Answers Strapi Backend
1
System Information
  • Strapi Version: 3.2.4
  • Operating System: macOS High Sierra 10.13.6
  • Database: SQLite 5.0.0, PostgreSQL 8.4.1
  • Node Version: 12.18.4
  • NPM Version: >=6.0.0
  • Yarn Version: 1.22.4

Curious to learn from the community here about best practices for Strapi updates. Would also love to hear from the Strapi core team like say @DMehaffy

  • What are your thoughts on updating your Strapi version?

  • What’s a good practice on how often we should update it, and what factors should we consider when thinking about updates?

  • Would the Strapi app break if we don’t update it for too long? (Or will it be buggy to update too many versions ahead?)

I’m more of a hold off updates as much as possible kind of dev. Just not sure if that’s the best approach…

2

It really comes down to subjective opinion. I myself am guilty of not updating my own projects (I was on v3.0.x literally up until recently and upgraded to v3.4.x).

In general my suggestion is try to make your updates at least once a month, if you have a mission critical app that isn’t something like a hobby or personal blog, being on the latest isn’t always the greatest (specifically x.x.0 releases). Typically we will handle quick hotfixes within a few days from a .0 release if needed.

When you are updating Strapi there are a few key things to keep in mind:

  • never use any of the ~, ^, ect options
  • all “Strapi” maintained packages need to be the same version
  • every. single. time. you update a package, regardless of version from us, you need to check our migration guides.
  • If no migration guide exists for your version jump you are fine to follow the standard update guide
  • While not required, you should pretty much always rebuild your admin panel when you update
  • If you use extensions, you will have some diff work to do to ensure your modifications don’t break code due to changes we made to ours. This is exactly the same as if you were to use the React ejection system.
  • Try not to fall to far behind, I saw it with our Alpha => Beta and Beta => Stable. For extremely old users, it’s common where we might just suggest you start a new project (which was the update system back in alpha). We plan our migration guides between minor versions, not major jumps. To update you have to walk through every migration guide one by one.

As a subset to that, when I did my own migration recently, I constructed a set of scripts (node and SQL) to handle the migration process smoothly and I tested them extensively for my environment. This certainly goes beyond a standard project, but I am extremely paranoid about proper migration procedures. Even on a hobby project that I do for fun…

You can see an example of what I was doing here: CAPIv2-Strapi/scripts/Migration at development · canonn-science/CAPIv2-Strapi · GitHub

Given this project is extremely massive and what I was doing was not just Strapi migrations but also content and database structure cleanup.

1 Like
3

Thanks so much Derrick! Appreciate the thoughtful detailed response, and love the script you made! I run a mini SaaS of sorts, so it’s definitely not a personal side project that I can just leave to gather dust on the shelf. Some questions to clarify:

Could you explain more about " * never use any of the ~, ^, ect options"?

If I missed too many minor versions and wanted to update my Strapi app, I should update incrementally, each minor version at a time (instead of jumping a few versions ahead)?

If I fall behind too much, the Strapi app would still work right? Would anything stop working/break because I don’t update?

4

Sorry I should have been more clear on this (also sorry for the late response, I was on vacation). This only applies to the Strapi packages, IE packages that we the Strapi team maintain (not community packages). The reason for this is when we release an update, all of our packages get updated regardless of any changed code or not.

It’s intended that all of the official Strapi packages are the same version, and trying to mix and match will almost certainly cause issues. Due to the “messed up” way npm can work sometimes due to mirror latency, ect. It’s not uncommon that one package may show a higher version when resolving the various ^, ~, <, > options.

You should updated based on the migration guides themselves, if we have a guide to from 3.4.x to 3.5.x then you are good to jump that far but if we have a guide from 3.4.3 to 3.4.4 you should follow it. In the case of no migration guides between your current version and the latest you can jump straight to that latest version.

We don’t follow semver “to the letter” yet, but we plan to in the future. It’s just been crazy busy and we have a bunch of refactoring that will happen later this year in v4.

Everything should still work, however any bugs you find and create bug reports for need to be validated on the latest version (see the contributing guide on the monorepo for more info about this). We generally only “support” the current latest minor release aka 3.5.x as of writing.

2 Likes
5

Thanks so much for explaining! :slight_smile: It’s assuring to know things won’t break because I stop updating, and that when I do choose to update, I can do so incrementally based on your guides.

6

Hello team!

This thread is very useful, thank you very much to you both!
I was wondering if there have been changes of thought about this since 2021 @DMehaffy.

I’ve been exploring if there is any documentation about this but haven’t found any. I also have production projects that are estimated to last a long time and at this stage, I only want to update them for security and stability reasons.

Thank you!
Esteban