diff --git a/README.md b/README.md index 414cc937..034f81c4 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,40 @@ -# Sharetribe Starter App +# Sharetribe Flex Template for Web -[![CircleCI](https://circleci.com/gh/sharetribe/sharetribe-starter-app.svg?style=shield&circle-token=198451e83e5cecb0d662949260dbc3273ac44a67)](https://circleci.com/gh/sharetribe/sharetribe-starter-app) +[![CircleCI](https://circleci.com/gh/sharetribe/sharetribe-starter-app.svg?style=svg&circle-token=198451e83e5cecb0d662949260dbc3273ac44a67)](https://circleci.com/gh/sharetribe/sharetribe-starter-app) -This is a template application for a Sharetribe marketplace that can be extended and customised. It -is based on an application bootstrapped with +This is a template web application for a Sharetribe Flex marketplace ready to be extended and +customised. It is based on an application bootstrapped with [create-react-app](https://github.com/facebookincubator/create-react-app) with some additions, namely server side rendering and a custom CSS setup. +## Quick start + +If you just want to get the app running quickly to test it out, first install +[Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/), and follow along: + +```sh +git clone git@github.com:sharetribe/sharetribe-starter-app.git # clone this repository +cd sharetribe-starter-app/ # change to the cloned directory +cp .env-template .env # copy the env template file to add your local config +emacs .env # in your favorite editor, add the mandatory env vars to the config +yarn install # install dependencies +yarn run dev # start the dev server, this will open a browser in localhost:3000 +``` + +See the [Environment configuration variables](docs/env.md) documentation for more information of the +required configuration variables. + +**Note:** If you want to build your own Flex marketplace on top of the template, you should fork the +repository instead of cloning it. See the following section. + +## Getting started with your own customisation + +If you want to build your own Flex marketplace by customising the template application, see the +[Getting started with customisation](docs/getting-started-with-customisation.md) documentation. + ## Documentation -Documentation can be found in the [docs directory](docs/). - -## Getting started - -Install required tools: - -* [Node.js](https://nodejs.org/) -* [Yarn](https://yarnpkg.com/) - -Clone this repository and install dependencies: - - yarn install - -## Development - -**First, you need to configure Client Id, Google Maps API key and Stripe publishable API key via -[environment variables](./docs/env.md).** The quickest way to do this is to copy `.env-template` -> -`.env`, and edit the file to set the three mandatory configuration values. - -To develop the application and to see changes live, start the frontend development server: - - yarn run dev - -**Known issues:** - -* Adding/changing `import`s may not be synced properly with ESLint. You may see an error - `Unable to resolve path to module` even though the module existing in right path. Restarting the - server doesn't help. To solve the issue, you need to make a change to the file where the error - occurs. - -## Development Server - -To develop the server setup, run: - - yarn run dev-server - -This runs the frontend production build and starts the Express.js server in `server/index.js` that -renders the application routes in the server. The server is automatically restarted when there are -changes in the `server/` directory. - -Not that this server does **not** pick up changes in the frontend application code. - -## Tests - -To start the test watcher, run - - yarn test - -See more in the [testing documentation](docs/testing.md). +Full documentation can be found in the [docs directory](docs/). ## License diff --git a/docs/README.md b/docs/README.md index 3fb2a813..674c0af2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ Documentation for specific topics can be found in the following files: * Original [create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md) +* [Getting started with customisation](getting-started-with-customisation.md) * [Testing](testing.md) * [Error logging with Sentry](sentry.md) * [CI](ci.md) @@ -18,7 +19,6 @@ Documentation for specific topics can be found in the following files: * [Terms of Service and Privacy Policy](terms-of-service-and-privacy-policy.md) * [i18n](i18n.md) * [Colors and icons](colors-and-icons.md) -* [Starting a new customisation project](starting-a-new-customisation-project.md) * [Google Maps](google-maps.md) * [Content Security Policy (CSP)](content-security-policy.md) * [Search filters](search-filters.md) diff --git a/docs/customisation-checklist.md b/docs/customisation-checklist.md index 824b497e..160c09d9 100644 --- a/docs/customisation-checklist.md +++ b/docs/customisation-checklist.md @@ -1,6 +1,6 @@ -# Customization checklist +# Customisation checklist -Some generic things to update and check when starting to customize Starter app. +Some generic things to update and check when starting to customise the template. * [Marketplace colors](colors-and-icons.md#colors) * [Generate app icons](colors-and-icons.md#icons) diff --git a/docs/getting-started-with-customisation.md b/docs/getting-started-with-customisation.md new file mode 100644 index 00000000..28d6876e --- /dev/null +++ b/docs/getting-started-with-customisation.md @@ -0,0 +1,145 @@ +# Getting started with customisation + +So you've decided to build your own Flex marketplace using the template. That's awesome! This guide +will help you in setting up your fork and describes the general workflow. + +**Note:** if you cloned the repository like described in the Quick start section of the project +README file, you probably don't want to make the customisations in that project. Forking the +repository is the recommended way to proceed. Follow this guide for instructions. + +## Requirements + +Install required tools: + +* [Node.js](https://nodejs.org/) +* [Yarn](https://yarnpkg.com/) + +## Technologies + +Depending on what you want to change in the template, various skills help in achieving your goal. +Some of the basic customisations don't require specific coding skills, but many customisations +become technically involved. We've tried to keep the technology setup as simple as possible, and +frontend developers with experience in widely used tooling should feel comfortable right from the +get-go. + +Here are some main technologies that the template uses: + +* JavaScript: programming language for the whole application +* [React](https://reactjs.org/): library for creating user interfaces with components +* CSS: styling the user interface using [CSS Modules](https://github.com/css-modules/css-modules) + and [cssnext](http://cssnext.io/) +* [Redux](https://redux.js.org/): state and data flow handling +* [Final Form](https://github.com/final-form/final-form): forms +* [React Router](https://reacttraining.com/react-router/): routing +* [Express](https://expressjs.com/): server + +## Setup + +To start a new customisation project, you should create a separate Git repository and setup the Git +remotes so that you can pull in changes from the main (upstream) repository to your custom +repository. + +### Fork the repository + +See the [Fork a repo](https://help.github.com/articles/fork-a-repo/) documentation for instructions +for forking a repository in GitHub. + +In the directory you want to create the project in: + + git clone git@github.com:YOUR_USERNAME/YOUR_FORK.git # clone your fork + cd YOUR_FORK # changed to the cloned directory + git remote add upstream git@github.com:sharetribe/sharetribe-starter-app.git # add the template as the upstream remote + +See also the +[Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/) +documentation. + +### Pull in latest upstream changes + +If you want to update your local customisation project with changes in the template, you should pull +in changes from the upstream remote. + +**Note:** Depending on the changes you've made to the template, this might be hard/impossible +depending on what has changed in the template. You should mainly think of the template being the +starting point of your customisation, not something that is constantly updated. + +In the `master` branch (or in the branch you want to merge in the upstream changes): + +1. Fetch the latest changes from the upstream repository: + + ```sh + git fetch upstream + ``` + +1. Merge the changes to your local branch + + ```sh + git merge upstream/master + ``` + +1. Fix possible merge conflicts, commit, and push/deploy. + +See also the [Syncing a fork](https://help.github.com/articles/syncing-a-fork/) documentation. + +## Configuration + +There are some mandatory configuration, and some configuration that you most likely want to at least +go through. + +To get started, first copy the config template: + + cp .env-template .env + +The `.env` file is the place to add your local configuration. It is ignored in Git, so you'll have +to add the corresponding configuration also to your server environment. + +There are some mandatory configuration variables that are defined in the template. See the +[Environment configuration variables](env.md) documentation for more information. + +See also the [src/config.js](../src/config.js) file for more configuration options. + +## Development + +In your project root, install dependencies: + + yarn install + +To develop the application and to see changes live, start the frontend development server: + + yarn run dev + +**Known issues:** + +* Adding/changing `import`s may not be synced properly with ESLint. You may see an error + `Unable to resolve path to module` even though the module existing in right path. Restarting the + server doesn't help. To solve the issue, you need to make a change to the file where the error + occurs. + +## Development 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 rendering setup. To develop the server +rendering setup locally, run: + + yarn run dev-server + +This runs the frontend production build and starts the Express.js server in `server/index.js` that +renders the application routes in the server. The server is automatically restarted when there are +changes in the `server/` directory. + +**Note:** this server does **not** pick up changes in the frontend application code. For that you +need to build the client bundle by restarting the server manually. + +## Tests + +To start the test watcher, run + + yarn test + +See more in the [testing documentation](docs/testing.md). + +## Customisation + +There are many things that you should change in the default template, and many more that you can +change. See the [Customisation checklist](customisation-checklist.md) documentation for more +information. diff --git a/docs/starting-a-new-customisation-project.md b/docs/starting-a-new-customisation-project.md deleted file mode 100644 index dbea1f93..00000000 --- a/docs/starting-a-new-customisation-project.md +++ /dev/null @@ -1,52 +0,0 @@ -# Starting a new customisation project - -To start a new project to customise the Starter App, you should create a separate Git repository and -setup the Git remotes so that you can pull in changes from the main (upstream) repository to your -custom repository. - -## Fork the repository - -See the [Fork a repo](https://help.github.com/articles/fork-a-repo/) documentation. - -**Note:** If you want to make the fork to the same user, you have to start with an empty repository -and follow the next steps in that repository. - -## Clone the fork - -Go to the directory where you want to clone the repository and run: - -```sh -git clone git@github.com:YOUR_USERNAME/YOUR_FORK.git -``` - -## Set up remotes - -In your local fork repository, run: - -```sh -git remote add upstream git@github.com:sharetribe/sharetribe-starter-app.git -``` - -See also the -[Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/) -documentation. - -## Pull in latest upstream changes - -In the `master` branch: - -1. Fetch the latest changes from the upstream repository: - - ```sh - git fetch upstream - ``` - -1. Merge the changes to your local branch - - ```sh - git merge upstream/master - ``` - -1. Fix possible merge conflicts, commit, and push/deploy. - -See also the [Syncing a fork](https://help.github.com/articles/syncing-a-fork/) documentation.