Customizing the template

Prerequisites

When you start a new project, you should create a new Git repository for your project and add the template repository as a remote repository. That allows you to update your code with the latest changes from the upstream repository. See how to set up a remote repository in the tutorial.

Create a marketplace environment

The Sharetribe Web Template is a React application built on top of the Marketplace API. While you can create a marketplace client application from scratch using just the API, it requires a lot of effort and we recommend that you use a template as a starting point for customizations.

To use the Marketplace API, you will need a client ID. You can obtain one by creating a new Flex marketplace at the Sharetribe website.

Check that you have the correct transaction processes in your environment

If you have created your marketplace environment prior to the 25th of April 2023, and you are using the Sharetribe Web Template, it is good to note that there are two new transaction processes the template uses, and those processes may not be in your Flex marketplace by default. You can find the transaction processes in /ext/transaction-processes/ in the repository.

To use the template, you will need to have the transaction processes in your Flex environment. Follow these steps to create both processes in your environment through Flex CLI.

Getting started with the template

If you are new to Sharetribe Flex or the Sharetribe Web Template, we recommend reading these articles before starting to work on development:

• Introducing Flex
• What development skills are needed?
• Getting started

The tutorial introduction will also walk you through creating a GitHub repository.

Pull in the latest upstream changes

To update your project with the newest changes from the remote repository, you need to pull these changes from the upstream remote.

You should follow the tutorial to set up a local development environment and connect it to GitHub.

Run the following commands in a new branch.

1. Create a new branch and switch into that branch:

   git checkout -b updates-from-upstream

2. Fetch the latest changes from the upstream repository:

   git fetch upstream

3. Merge the changes to your local branch

   git merge upstream/main

4. Fix possible merge conflicts, commit, and push/deploy.

If you have forked the repository instead of setting a remote, see how to sync a fork.

Installing dependecies

In your project root, install dependency libraries:

yarn install

Configuring environment variables

You need to configure some environment variables before deploying or running the template locally. You can simply run the following command in the root of your project directory:

yarn run config

This command will create .env file and guide you trough setting up the required environment variables.

└── .env

The .env file is the place to add your local configuration. It is ignored by Git, so you will have to add the corresponding configuration also to your server environment. When deploying the template to Render or Heroku, you need to configure the environment variables in the hosting platform. See our article on deploying the template to Render for more information.

See the full list of environment variables for more information.

For in-app configurations, see the src/config directory.

└── src
    └── config

Development

To develop the application and to see changes live, start the frontend development server:

yarn run dev

Development with the actual Node.js server

The usual way to develop the application is to use the frontend development server (see above). However, in production you likely want to use the server-side rendering (SSR) setup. To develop against the actual server locally, run:

yarn run dev-server

This runs the frontend production build and starts the Express.js server in server/index.js.

└── server
    └── index.js

The server is automatically restarted when changes are detected in the server directory.

Tests

To start the test watcher, run

yarn test

For more information on tests, see the documentation on how to test the template.

Further reading

There are many things that you should change in the default template and many more that you can change. For more information, check the template customization checklist documentation before publishing your site. Also see the tutorial and other articles in the Sharetribe Web Template and How-to categories.