Updating your custom Sharetribe Web Template from upstream

When Sharetribe marketplace founders want to start custom development on their marketplace, most choose the Sharetribe Web Template as their starting point. The Sharetribe Web Template is an open-source version of the codebase that also powers the no-code Sharetribe marketplaces, so it is an ideal starting point for code customizations.

When you start developing, you clone an up-to-date version of the template. While you are developing and running a customized marketplace, the Sharetribe team will also continue to develop new features for the default Sharetribe no-code marketplaces. This means that the Sharetribe Web Template codebase keeps developing in one direction, and your own codebase keeps developing in another direction.

If you want to then incorporate code changes and new features released by the Sharetribe team into your own codebase, you need to do some development work to reconcile the two directions of development into one coherent codebase. We call this doing an upstream update, since the Sharetribe Web Template repository is “upstream” from your custom version.

In this article, I’ll take an in depth look into when it makes sense to do an upstream update, when it does not make sense, and when it is time to part ways with the Sharetribe Web Template completely. I’ll also share some best practices on managing your codebase so that making upstream updates remains as straightforward as possible.

When does an upstream update make sense

The Sharetribe Web Template is first and foremost a template application, in that it is intended as the starting point for custom development. In other words, taking upstream updates is never required to successfully run your Sharetribe marketplace.

The best time to make upstream updates is when the Sharetribe team publishes features to the default marketplace functionality that you would otherwise want to custom develop yourself down the road. There may be features that our team publishes but that you aren’t interested in incorporating, because they are not relevant to your marketplace – you can freely skip those.

It is also possible that there is a feature on our roadmap that you are looking forward to, and you want to make multiple smaller upstream updates so that eventually incorporating that feature will be easier. If your team is doing active development on other features, that might be a good call, so that they can keep developing on top of a codebase that is as close as possible to upstream.

Some template releases include big overhauls to dependency libraries or fundamental template logic. These are usually major versions (X.0.0). Making these upstream updates can be useful if you are looking to stay fairly close to the upstream codebase, because if we end up releasing features that you later want to incorporate, the major version update needs to be a part of that process anyway.

Even if you are not taking full upstream updates, it may make sense to track new template releases to see what new Console-defined assets are being introduced. When a new configuration option (i.e. new asset) is released, you can then check the Template implementation to see an example on how to create a client-side implementation around that asset. 

When does an upstream update not make sense

I already mentioned one possible case: our team releases a feature that is not relevant to your marketplace. Other reasons might be that you have found the feature set that works for your marketplace, and the upstream update would include a “nice-to-have” feature where the positive impact on your marketplace is smaller than the cost of updating your codebase.

Sometimes, you may try out an upstream update locally, and notice that there is a lot of overlap and a ton of merge conflicts to resolve. This can happen especially if the new template release touches a lot of files (such as a major version) or if you have a lot of custom development in the same files that the new release changes. 

At that point, it is important to consider whether keeping up with upstream updates is the right strategic choice for your marketplace. 

We have a lot of customers who have started with one of our template applications (either legacy ones or the Sharetribe Web Template) and have stopped taking upstream updates. Their own custom development has gone so far in the other direction that they have decided to part ways with the Sharetribe Web Template codebase. Yet they still continue to use Sharetribe APIs and the Console, and they just develop their own custom features when relevant.

The Sharetribe team will keep developing new features to the Console and the Sharetribe Web Template. The more mature a marketplace is, though, the fewer of those features will be necessary – and the more likely it is that if they are really crucial, the marketplace has already custom developed something similar. 

However, even if you’ve decided to not take upstream updates from the Sharetribe Web Template repository – either your codebase has diverged, or you’ve built a client from scratch with a different framework – it can still be useful to review new feature implementations as they are released. You may find that you want to implement something similar without making a direct upstream update, and it might be useful to see what our team has considered when developing the feature for the template.

What makes upstream updates easier

In essence, an upstream update means fetching the upstream version to your local computer, resolving all merge conflicts, and then testing that both your custom developed features and the new upstream features work correctly. You can find the practical steps for upstream updates in this article. 

Here are three best practices you can follow in your development work to make this process as easy as possible – it still isn’t always easy, but there are steps we can take to mitigate the difficulty.

1. Make a lot of your custom code changes in new files.

More overlapping changes mean more merge conflicts. 

The more you can separate your own code in new files that don’t exist upstream, the less you will have overlapping code. Separating your code into separate functions and components that you call from the main containers and components (instead of building everything into the same massive file) means that even when overlap happens, it is easy to identify what exactly is happening in each of your custom developed blocks.

This is a pattern our team tries to follow, too. Whenever we make larger overhauls, we try to be mindful that new functionality, helpers, etc. are easier to incorporate when they are in their own separate files. 

If there are places where you cannot make changes outside the default file, it's a good idea to bookend your customizations with comments, such as

// Google Meet customization begins 
– {your custom code} – 
// Google Meet customization ends. 

This helps you in solving merge conflicts so that you can more easily detect what code is related to what feature.

2. Have good tests

When you build custom functionality, also build good automated tests. This allows you to quickly check that things are working as expected after an upstream update. The Sharetribe Web Template has a test setup based on Jest that our team also uses to some extent for adding test coverage to new features.

Tests in the Sharetribe Web Template fall under two categories: unit tests and snapshot tests. On a high level, testing is mostly done with unit tests for functions and components, and there are integration tests over multiple components. There are also some snapshot tests added for small presentational components. It is worthwhile to get familiar with the test structure of the template for many reasons, and easier upstream updates are one of those reasons.

Tests in the template have been intentionally relaxed, because changing tests to match any specific marketplace concept could be significant work on its own. However, in your own repository, strict tests would help to detect changes or bugs that would affect your specific marketplace concept.

3. Make upstream updates a part of your routine

As I mentioned earlier, more frequent updates mean that there is less time for the two codebases to diverge. If you have made the strategic choice to keep taking upstream updates, it is a good idea to factor them into your development timeline as a part of your development process.

The Sharetribe team keeps continuously developing new template features. Depending on the size of the features, there will be frequent small releases interspersed with some larger releases and major version updates. Rather than reactively updating each version as it comes, it is a good idea to have a regular cadence of updating whichever releases have been made since your most recent upstream update.

Our roadmap shows what we are currently working on, as well as what we are looking to work on in the near future. We communicate our template releases in our Developer Slack community, and you can see all of our releases in the Sharetribe Web Template Github repository. Being aware of those two resources, as well as having a routine for regular upstream updates, gives you a good overview of what is coming in the pipeline and how you might need to prepare.

Conclusion

If you are developing your custom marketplace on top of the Sharetribe Web Template, you may or may not choose to update your codebase when new features are released. The question of “should we do upstream updates” is very difficult to answer for anyone except the marketplace team, but there are some considerations that might make that process clearer. In this article, I discussed some aspects of making that decision, as well as best practices to make upstream updates easier, if that’s what you choose to do.

If you have any questions or insights about upstream updates based on this article, we’d love to hear them! Let us know by sending us a message through the Console chat widget, or respond to any of our newsletters!