mirror of
https://github.com/kingomarnajjar/flex-template-web.git
synced 2026-07-26 06:47:17 +10:00
Getting started documentation
This commit is contained in:
Kimmo Puputti
parent
72ef521064
commit
dda884ab19
5 changed files with 178 additions and 108 deletions
83
README.md
83
README.md
|
|
@ -1,63 +1,40 @@
|
|||
# Sharetribe Starter App
|
||||
# Sharetribe Flex Template for Web
|
||||
|
||||
[](https://circleci.com/gh/sharetribe/sharetribe-starter-app)
|
||||
[](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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
145
docs/getting-started-with-customisation.md
Normal file
145
docs/getting-started-with-customisation.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Add table
Reference in a new issue