mirror of
https://github.com/kingomarnajjar/flex-template-web.git
synced 2026-07-25 22:37:18 +10:00
Move customization guide and testing docs to Flex Docs
This commit is contained in:
Kimmo Puputti
parent
caa074c218
commit
dfc3a85557
5 changed files with 27 additions and 193 deletions
14
README.md
14
README.md
|
|
@ -29,12 +29,15 @@ For more information of the configuration, see the
|
|||
reference in Flex Docs.
|
||||
|
||||
**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 [Customization guide](./docs/customization-guide.md).
|
||||
repository instead of cloning it. See the
|
||||
[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex
|
||||
Docs.
|
||||
|
||||
## Getting started with your own customization
|
||||
|
||||
If you want to build your own Flex marketplace by customizing the template application, see the
|
||||
[Customization guide](docs/customization-guide.md) documentation.
|
||||
[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex
|
||||
Docs.
|
||||
|
||||
## Deploying to Heroku
|
||||
|
||||
|
|
@ -48,7 +51,12 @@ for more information.
|
|||
|
||||
## Documentation
|
||||
|
||||
Full documentation can be found in the [docs directory](docs/).
|
||||
We are currently moving documentation to the Flex Docs site, so at the moment part of the
|
||||
documentation is in this repository and part is in the Flex Docs site.
|
||||
|
||||
See the Flex Docs site: https://www.sharetribe.com/docs/
|
||||
|
||||
Rest of the documentation can be found in the [docs directory](docs/).
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -41,17 +41,21 @@ Docs:
|
|||
- [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/)
|
||||
tutorial.
|
||||
|
||||
## How to customize this template
|
||||
## Customization guide
|
||||
|
||||
The easiest way to start a customization project is to read through the
|
||||
[customization guide](customization-guide.md). After that, you probably should start with changing
|
||||
[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex
|
||||
Docs.
|
||||
|
||||
## How to customize this template
|
||||
|
||||
After going through the customization guide, you probably should start with changing
|
||||
[translations](translations.md), [common styles](styling.md) in marketplace.css, and then create
|
||||
[static pages](static-pages.md) and modify
|
||||
[Terms of Service and Privacy Policy pages](terms-of-service-and-privacy-policy.md).
|
||||
|
||||
Documentation for specific topics can be found in the following files:
|
||||
|
||||
- [Customization guide](customization-guide.md)
|
||||
- [Folder structure](folder-structure.md)
|
||||
- [Translations](translations.md)
|
||||
- [Styling a marketplace](styling.md)
|
||||
|
|
@ -65,7 +69,6 @@ Documentation for specific topics can be found in the following files:
|
|||
Docs
|
||||
- [Extend the listing data model](extend-listing.md)
|
||||
- [Search filters](search-filters.md)
|
||||
- [Testing](testing.md)
|
||||
- [Continuous Integration (CI)](ci.md)
|
||||
- [Original create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md)
|
||||
- [Customization checklist](customization-checklist.md)
|
||||
|
|
@ -76,6 +79,7 @@ Documentation for specific topics can be found in the following files:
|
|||
See also the following articles in the [Flex Docs](https://www.sharetribe.com/docs/) website:
|
||||
|
||||
- [How to set up Mapbox for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/)
|
||||
- [How to test FTW](https://www.sharetribe.com/docs/guides/how-to-test-ftw/)
|
||||
- [How to set up Sentry to log errors in FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-sentry-to-log-errors-in-ftw/)
|
||||
- [How to set up Analytics for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/)
|
||||
- [How to set up Content Security Policy (CSP) for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-csp-for-ftw/)
|
||||
|
|
|
|||
|
|
@ -1,159 +1,5 @@
|
|||
# Customization guide
|
||||
|
||||
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.
|
||||
Documentation moved to the Flex Docs site:
|
||||
|
||||
**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 customizations in that project. Forking the
|
||||
repository is the recommended way to proceed. Follow this guide for instructions.
|
||||
|
||||
## Getting started
|
||||
|
||||
We recommend going through the
|
||||
[Getting started articles](https://www.sharetribe.com/docs/background/getting-started/) in the Flex
|
||||
Docs:
|
||||
|
||||
- [Introducing Flex](https://www.sharetribe.com/docs/background/introducing-flex/)
|
||||
- [What development skills are needed?](https://www.sharetribe.com/docs/background/development-skills/)
|
||||
- [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/)
|
||||
tutorial.
|
||||
|
||||
## 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 customizations 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
|
||||
- CSS: styling the user interface using [CSS Modules](https://github.com/css-modules/css-modules)
|
||||
- [React](https://reactjs.org/): library for creating user interfaces with components
|
||||
- [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 customization 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/flex-template-web.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 customization 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 customization, 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.
|
||||
|
||||
## Installing dependecies
|
||||
|
||||
In your project root, install dependencies:
|
||||
|
||||
yarn install
|
||||
|
||||
## Configuration
|
||||
|
||||
There are some mandatory configuration, and some configuration that you most likely want to at least
|
||||
go through.
|
||||
|
||||
To get started, run:
|
||||
|
||||
yarn run config
|
||||
|
||||
This command will create `.env` file and guide you trough setting up the required environment
|
||||
variables. 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 Flex Docs
|
||||
[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/)
|
||||
reference for more information.
|
||||
|
||||
See also the [src/config.js](../src/config.js) file for more configuration options.
|
||||
|
||||
## Development
|
||||
|
||||
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](testing.md).
|
||||
|
||||
## Customization
|
||||
|
||||
There are many things that you should change in the default template, and many more that you can
|
||||
change. Read [more about FTW](README.md) and check the
|
||||
[Customization checklist](customization-checklist.md) documentation too before publishing your site.
|
||||
https://www.sharetribe.com/docs/guides/how-to-customize-ftw/
|
||||
|
|
|
|||
|
|
@ -73,8 +73,9 @@ changes to environment variables.
|
|||
If you haven't done this already, you just need to click the "Fork" button on the top-right corner
|
||||
of the page: <img width="300" src="./assets/deploying-to-production/fork_button.png" />
|
||||
|
||||
Read more from [Customization guide](./customization-guide.md#fork-the-repository) for more
|
||||
instructions.
|
||||
For more information, see the
|
||||
[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex
|
||||
Docs.
|
||||
|
||||
### Creating a new app
|
||||
|
||||
|
|
|
|||
|
|
@ -1,30 +1,5 @@
|
|||
# Testing Flex template for the web
|
||||
# Testing Flex Template for Web
|
||||
|
||||
The test setup is based on the `create-react-app` test setup and is using the
|
||||
[Jest testing framework](https://facebook.github.io/jest/). See the
|
||||
[Testing Components](create-react-app.md#testing-components) and
|
||||
[Experimental Snapshot Testing](create-react-app.md#experimental-snapshot-testing) sections in the
|
||||
`create-react-app` documentation.
|
||||
Documentation moved to the Flex Docs site:
|
||||
|
||||
## Running tests
|
||||
|
||||
To start the test watcher that automatically updates when files change, run
|
||||
|
||||
yarn test
|
||||
|
||||
If you want to run the tests once and not start the watcher, run
|
||||
|
||||
CI=true yarn test
|
||||
|
||||
Note that this also runs the linter.
|
||||
|
||||
## Jest
|
||||
|
||||
To learn more about testing with Jest, read the following documentation:
|
||||
|
||||
- [Getting Started](https://facebook.github.io/jest/docs/getting-started.html)
|
||||
- [Tutorial - React](https://facebook.github.io/jest/docs/tutorial-react.html)
|
||||
- [Tutorial - Async](https://facebook.github.io/jest/docs/tutorial-async.html)
|
||||
- [Snapshot Testing](https://facebook.github.io/jest/blog/2016/07/27/jest-14.html) blog post
|
||||
- [API Reference](https://facebook.github.io/jest/docs/api.html) lists the global environment with
|
||||
the available functions and the assertion matchers
|
||||
https://www.sharetribe.com/docs/guides/how-to-test-ftw/
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue