diff --git a/README.md b/README.md index 2b13c670..846e0fda 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,10 @@ [![CircleCI](https://circleci.com/gh/sharetribe/sharetribe-starter-app.svg?style=shield&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 -[create-react-app](https://github.com/facebookincubator/create-react-app) with -some additions, namely server side rendering and a custom CSS setup. +This is a template application for a Sharetribe marketplace that can 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. ## Documentation @@ -16,8 +15,8 @@ Documentation can be found in the [docs directory](docs/). Install required tools: - - [Node.js](https://nodejs.org/) - - [Yarn](https://yarnpkg.com/) +* [Node.js](https://nodejs.org/) +* [Yarn](https://yarnpkg.com/) Clone this repository and install dependencies: @@ -25,18 +24,16 @@ Clone this repository and install dependencies: ## Development -To develop the application and to see changes live, start the frontend -development server: +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. +* 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 @@ -44,13 +41,11 @@ 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. +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. +Not that this server does **not** pick up changes in the frontend application code. ## Tests @@ -62,8 +57,7 @@ See more in the [testing documentation](docs/testing.md). ## Deployment -The `master` branch is automatically deployed to Heroku. If you want -to deploy a feature branch, setup the `sharetribe-starter-app` Heroku -app and push the feature branch: +The `master` branch is automatically deployed to Heroku. If you want to deploy a feature branch, +setup the `sharetribe-starter-app` Heroku app and push the feature branch: git push heroku my-feature-branch:master diff --git a/docs/README.md b/docs/README.md index a593f5db..ceeafd7e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,20 +1,19 @@ # Sharetribe Starter App Documentation The application was bootstrapped with a forked version of -[create-react-app](https://github.com/facebookincubator/create-react-app). While -most of the original documentation still apply, there are some -important differences listed in the -[sharetribe-scripts](https://www.npmjs.com/package/sharetribe-scripts) -NPM package. +[create-react-app](https://github.com/facebookincubator/create-react-app). While most of the +original documentation still apply, there are some important differences listed in the +[sharetribe-scripts](https://www.npmjs.com/package/sharetribe-scripts) NPM package. 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) - - [Testing](testing.md) - - [Error logging with Sentry](sentry.md) - - [CI](ci.md) - - [Static pages](static-pages.md) - - [Analytics](analytics.md) - - [Terms of Service and Privacy Policy](terms-of-service-and-privacy-policy.md) - - [i18n](i18n.md) - - [Colors and icons](colors-and-icons.md) +* Original + [create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md) +* [Testing](testing.md) +* [Error logging with Sentry](sentry.md) +* [CI](ci.md) +* [Static pages](static-pages.md) +* [Analytics](analytics.md) +* [Terms of Service and Privacy Policy](terms-of-service-and-privacy-policy.md) +* [i18n](i18n.md) +* [Colors and icons](colors-and-icons.md) diff --git a/docs/analytics.md b/docs/analytics.md index 636a140b..ae5b5d80 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -1,13 +1,11 @@ # Analytics -The application supports tracking page views with pluggable analytics -handlers. +The application supports tracking page views with pluggable analytics handlers. ## Google Analytics -Google Analytics (GA) is supported by default. The enable GA, set the -GA tracker ID to the environment variable -`REACT_APP_GOOGLE_ANALYTICS_ID`; +Google Analytics (GA) is supported by default. The enable GA, set the GA tracker ID to the +environment variable `REACT_APP_GOOGLE_ANALYTICS_ID`; ## Custom analytics handler @@ -15,29 +13,25 @@ If you want to add a new analytics library, you can do as follows: 1. Add the analytics library script - If the analytics library has an external script, add the library - script tag to the [src/public/index.html](../public/index.html) - file. If you need more control, see how the GA script is added in - [server/renderer.js](../server/renderer.js). + If the analytics library has an external script, add the library script tag to the + [src/public/index.html](../public/index.html) file. If you need more control, see how the GA + script is added in [server/renderer.js](../server/renderer.js). 1. Create a handler To track page views, create a custom handler e.g. in - [src/analytics/handlers.js](../src/analytics/handlers.js). The - handler should be a class that implements a `trackPageView(url)` - method. + [src/analytics/handlers.js](../src/analytics/handlers.js). The handler should be a class that + implements a `trackPageView(url)` method. - Note that the `url` parameter might not be the same as in the URL - bar of the browser. It is the canonical form of the URL. For - example, in the listing page it doesn't have the dynamic title slug - in the middle. This allows unified analytics and correct tracking - of pages that can be accessed from multiple different URLs. + Note that the `url` parameter might not be the same as in the URL bar of the browser. It is the + canonical form of the URL. For example, in the listing page it doesn't have the dynamic title + slug in the middle. This allows unified analytics and correct tracking of pages that can be + accessed from multiple different URLs. - If you analytics library takes the page URL from the browser, you - might need to override that behavior to use the canonical URL that - is given to the method. + If you analytics library takes the page URL from the browser, you might need to override that + behavior to use the canonical URL that is given to the method. 1. Initialise the handler - Initialise the handler in the `setupAnalyticsHandlers()` function - in [src/index.js](../src/index.js). + Initialise the handler in the `setupAnalyticsHandlers()` function in + [src/index.js](../src/index.js). diff --git a/docs/ci.md b/docs/ci.md index ec1471c1..bc39d56a 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -1,9 +1,8 @@ # CI -The application provides a configuration to use -[CircleCI](https://circleci.com/) as a continuous integration server -to run tests and other scripts. This ensures quality and can be forced -to avoid merging changes that break tests or fail audits. +The application provides a configuration to use [CircleCI](https://circleci.com/) as a continuous +integration server to run tests and other scripts. This ensures quality and can be forced to avoid +merging changes that break tests or fail audits. The [circle.yml](../circle.yml) file is used to configure CircleCI. @@ -11,23 +10,20 @@ Currently the CI runs the following scripts: ## Security audit: `yarn run audit` -This command runs the security audit using -[nsp](https://www.npmjs.com/package/nsp). The audit checks for -installed packages with known vulnerabilities and warns about those. +This command runs the security audit using [nsp](https://www.npmjs.com/package/nsp). The audit +checks for installed packages with known vulnerabilities and warns about those. -The scripts outputs information about the dependency path that added -the package. If that information is not enough, `yarn why -package-name` can be used to get more detailed information about why -the package is installed. +The scripts outputs information about the dependency path that added the package. If that +information is not enough, `yarn why package-name` can be used to get more detailed information +about why the package is installed. -If you are convinced that the vulnerability can be ignored, exceptions -can be added to the [.nsprc](../.nsprc) file. +If you are convinced that the vulnerability can be ignored, exceptions can be added to the +[.nsprc](../.nsprc) file. ## Code formatting: `yarn run format-ci` -This command fails if there are changes in the formatting that are not -committed. Run `yarn run format` to format the code and get rid of the -error. +This command fails if there are changes in the formatting that are not committed. Run +`yarn run format` to format the code and get rid of the error. ## Build: `yarn run build` diff --git a/docs/colors-and-icons.md b/docs/colors-and-icons.md index 11962cf3..52e8b682 100644 --- a/docs/colors-and-icons.md +++ b/docs/colors-and-icons.md @@ -1,13 +1,11 @@ # Colors and icons -One of the first customisations is to change the marketplace colors -and icons. +One of the first customisations is to change the marketplace colors and icons. ## Colors -To change the marketplace colors, open the -[src/marketplace.css](../src/marketplace.css) file and change the -color variables: +To change the marketplace colors, open the [src/marketplace.css](../src/marketplace.css) file and +change the color variables: ```css --marketplaceColor: #c0392b; @@ -17,11 +15,9 @@ color variables: ## Icons -The default icons are generated with -[RealFaviconGenerator](https://realfavicongenerator.net/). You can -upload your original icon to the tool, customise the colors and -themes, and download a generated set if icons and an HTML snippet to -point to those images. +The default icons are generated with [RealFaviconGenerator](https://realfavicongenerator.net/). You +can upload your original icon to the tool, customise the colors and themes, and download a generated +set if icons and an HTML snippet to point to those images. 1. Open https://realfavicongenerator.net/ @@ -35,17 +31,14 @@ point to those images. 1. Generate the icons -1. Unzip the favicons.zip archive and replace the default icons and - files in [public/static/icons/](../public/static/icons/) with the - new icons +1. Unzip the favicons.zip archive and replace the default icons and files in + [public/static/icons/](../public/static/icons/) with the new icons -1. Replace the default HTML snippet in - [public/index.html](../public/index.html) with the snippet from the - generator. +1. Replace the default HTML snippet in [public/index.html](../public/index.html) with the snippet + from the generator. - **Note:** Remove the manifest link from the snippet as we have a - default manifest with extra data compared to the generated one. You - can edit the default file as you wish. + **Note:** Remove the manifest link from the snippet as we have a default manifest with extra data + compared to the generated one. You can edit the default file as you wish. **Example HTML snippet:** @@ -64,6 +57,5 @@ point to those images. ## Map marker icon The map marker icon in the listing can be found in -[src/components/Map/images/marker.png](../src/components/Map/images/marker.png). The -dimensions should be 32x32 pixels, so the `favicon-32x32.png` file can -be used to replace the map icon. +[src/components/Map/images/marker.png](../src/components/Map/images/marker.png). The dimensions +should be 32x32 pixels, so the `favicon-32x32.png` file can be used to replace the map icon. diff --git a/docs/i18n.md b/docs/i18n.md index 28a81954..d6a890a5 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -1,22 +1,18 @@ # i18n -The application supports having a single language for the UI. By -default the language is English. +The application supports having a single language for the UI. By default the language is English. -We are using the [react-intl](https://github.com/yahoo/react-intl) -package to translate UI texts and to format dates, numbers, money -values, etc. +We are using the [react-intl](https://github.com/yahoo/react-intl) package to translate UI texts and +to format dates, numbers, money values, etc. To change the language, do the following: -1. Copy the default - [src/translations/en.json](../src/translations/en.json) English - translation messages file into some other file like `es.json`. +1. Copy the default [src/translations/en.json](../src/translations/en.json) English translation + messages file into some other file like `es.json`. 1. Change the messages in the new messages file to your language. 1. In [src/config.js](../src/config.js), change the `locale` variable value -1. In [src/app.js](../src/app.js), change the translation imports to - come from the correct `react-intl` locale and the new messages file - you created. +1. In [src/app.js](../src/app.js), change the translation imports to come from the correct + `react-intl` locale and the new messages file you created. diff --git a/docs/sentry.md b/docs/sentry.md index fd68f4ea..188a7d03 100644 --- a/docs/sentry.md +++ b/docs/sentry.md @@ -1,15 +1,21 @@ # Error logging with Sentry +The Starter App supports error logging with [Sentry](https://sentry.io/) out of the box provided +that required environment variables are set in place. Other logging solutions can also be used but +the Sentry client comes already strapped into the Starter App. -The Starter App supports error logging with [Sentry](https://sentry.io/) out of the box provided that required environment variables are set in place. Other logging solutions can also be used but the Sentry client comes already strapped into the Starter App. +To enable the Sentry error logging a DSN, _Data Source Name_ has to be provided as an environment +variable. Browser and Node environments both require their own keys. The key names are as follows: -To enable the Sentry error logging a DSN, _Data Source Name_ has to be provided as an environment variable. Browser and Node environments both require their own keys. The key names are as follows: +* **SERVER_SENTRY_DSN** - the private Sentry DSN, used on the server side +* **REACT_APP_PUBLIC_SENTRY_DSN** - the public Sentry DSN, used in the browser - - __SERVER_SENTRY_DSN__ - the private Sentry DSN, used on the server side - - __REACT_APP_PUBLIC_SENTRY_DSN__ - the public Sentry DSN, used in the browser - -The DSN keys can be aquired from the Sentry project settings. To test them in your local environment they can be passed for example to the `yarn run dev-server` command: +The DSN keys can be aquired from the Sentry project settings. To test them in your local environment +they can be passed for example to the `yarn run dev-server` command: REACT_APP_PUBLIC_SENTRY_DSN='' SERVER_SENTRY_DSN='' yarn run dev-server -If the Sentry DSN keys are not provided Starter App will log errors to the console. The logging and Sentry setup is implemented in [util/log.js](../src/util/log.js) and [server/log.js](../server/log.js) so refer to those files to change the external logging service or the logging logic in general. +If the Sentry DSN keys are not provided Starter App will log errors to the console. The logging and +Sentry setup is implemented in [util/log.js](../src/util/log.js) and +[server/log.js](../server/log.js) so refer to those files to change the external logging service or +the logging logic in general. diff --git a/docs/static-pages.md b/docs/static-pages.md index 58fce874..f78e25d6 100644 --- a/docs/static-pages.md +++ b/docs/static-pages.md @@ -1,33 +1,36 @@ # Static pages -If you want to create simple pages that just show static content without need for data fetches, -you can create a static page. +If you want to create simple pages that just show static content without need for data fetches, you +can create a static page. Steps for creating a static page: -1) [Create a new folder under `src/containers/`](#1-creating-a-new-folder) -2) [Create a new JavaScript file using the same name.](#2-creating-a-javascript-file) -3) [Create a new CSS file using the same name.](#3-creating-a-css-file) -4) [Write the content to a JavaScript file (i.e. AboutPage.js in our example).](#4-creating-the-component) -5) [Write the style rules to CSS file (i.e. AboutPage.css in our example).](#5-adding-some-styles-to-the-css-file) -6) [Add the newly created page component to `src/containers/index.js`](#6-adding-the-component-to-the-component-directory) -7) [Add the newly created page to `src/routeConfiguration.js`](#7-adding-a-route-to-the-page) + +1. [Create a new folder under `src/containers/`](#1-creating-a-new-folder) +2. [Create a new JavaScript file using the same name.](#2-creating-a-javascript-file) +3. [Create a new CSS file using the same name.](#3-creating-a-css-file) +4. [Write the content to a JavaScript file (i.e. AboutPage.js in our example).](#4-creating-the-component) +5. [Write the style rules to CSS file (i.e. AboutPage.css in our example).](#5-adding-some-styles-to-the-css-file) +6. [Add the newly created page component to `src/containers/index.js`](#6-adding-the-component-to-the-component-directory) +7. [Add the newly created page to `src/routeConfiguration.js`](#7-adding-a-route-to-the-page) ## 1. Creating a new folder -Create a new folder under `src/containers/` with the name of your static page. E.g. "about" page should be named as `AboutPage`. +Create a new folder under `src/containers/` with the name of your static page. E.g. "about" page +should be named as `AboutPage`. ## 2. Creating a JavaScript file -Create a new JavaScript file using the folder name. The path should look like `src/containers/AboutPage/AboutPage.js`. +Create a new JavaScript file using the folder name. The path should look like +`src/containers/AboutPage/AboutPage.js`. ## 3. Creating a CSS file -Create a new CSS file using the folder name. The path should look like `src/containers/AboutPage/AboutPage.css`. +Create a new CSS file using the folder name. The path should look like +`src/containers/AboutPage/AboutPage.css`. ## 4. Creating the component -Template for a single column static page (AboutPage.js): -(We'll go through this line-by-line below.) +Template for a single column static page (AboutPage.js): (We'll go through this line-by-line below.) ```jsx import React from 'react'; @@ -39,7 +42,7 @@ import { LayoutWrapperFooter, Footer, NamedLink, - ExternalLink + ExternalLink, } from '../../components'; import css from './AboutPage.css'; @@ -51,10 +54,10 @@ const AboutPage = () => { className={css.root} title="About" schema={{ - "@context": "http://schema.org", - "@type": "AboutPage", - "description": "Description of this page", - "name": "About page", + '@context': 'http://schema.org', + '@type': 'AboutPage', + description: 'Description of this page', + name: 'About page', }} > @@ -75,32 +78,40 @@ const AboutPage = () => { ); -} +}; export default AboutPage; - ``` -We are using [React](https://reactjs.org/) and [JSX](https://reactjs.org/docs/introducing-jsx.html) to create components and pages. Therefore, we need to import React to our new component which is done in the first line. +We are using [React](https://reactjs.org/) and [JSX](https://reactjs.org/docs/introducing-jsx.html) +to create components and pages. Therefore, we need to import React to our new component which is +done in the first line. + ```jsx import React from 'react'; ``` In the second line we are importing two containers: -- `StaticPage`: helps in creating static pages -- `TopbarContainer`: creates our Topbar component and fetches the data it needs. + +* `StaticPage`: helps in creating static pages +* `TopbarContainer`: creates our Topbar component and fetches the data it needs. ```jsx import { StaticPage, TopbarContainer } from '../../containers'; ``` After that we need to import some components: -- `LayoutSingleColumn` and wrappers that it needs to position content -- `Footer` component (to be added inside LayoutWrapperFooter) -- `NamedLink` makes it easier to point to different pages inside Starter app -- `ExternalLink` can be used to link outside of Starter app. It creates a normal ``link with extra attributes `target="_blank" rel="noopener noreferrer"` that add some security to these outbound links. -`LayoutSingleColumn` (and other layouts like LayoutSideNavigation) need to understand what the content is about. Therefore, different parts of the page need to be wrapped with specific components - in this case: `LayoutWrapperTopbar`, `LayoutWrapperMain`, and `LayoutWrapperFooter`. +* `LayoutSingleColumn` and wrappers that it needs to position content +* `Footer` component (to be added inside LayoutWrapperFooter) +* `NamedLink` makes it easier to point to different pages inside Starter app +* `ExternalLink` can be used to link outside of Starter app. It creates a normal ``link with + extra attributes `target="_blank" rel="noopener noreferrer"` that add some security to these + outbound links. + +`LayoutSingleColumn` (and other layouts like LayoutSideNavigation) need to understand what the +content is about. Therefore, different parts of the page need to be wrapped with specific +components - in this case: `LayoutWrapperTopbar`, `LayoutWrapperMain`, and `LayoutWrapperFooter`. ```jsx import { @@ -110,26 +121,31 @@ import { LayoutWrapperFooter, Footer, NamedLink, - ExternalLink + ExternalLink, } from '../../components'; ``` -Then we need to import styles and possible other files from current folder. With CSS we are using [CSS Modules](https://github.com/css-modules/css-modules) to tackle possible classhes of different class names. [Read more.](#5-creating-the-css-file) +Then we need to import styles and possible other files from current folder. With CSS we are using +[CSS Modules](https://github.com/css-modules/css-modules) to tackle possible classhes of different +class names. [Read more.](#5-creating-the-css-file) ```jsx import css from './AboutPage.css'; ``` -Then we also import an image which is used later (`My first ice cream.`). +Then we also import an image which is used later (`My first ice cream.`). ```jsx import image from './path/to/image.png'; ``` Then after all the imports we are finally getting into phase were we define the component. -`const AboutPage = props => { return
}` defines a component called AboutPage with content defined in return part. This is a [functional component](https://reactjs.org/docs/components-and-props.html). +`const AboutPage = props => { return
}` defines a component called AboutPage with content +defined in return part. This is a +[functional component](https://reactjs.org/docs/components-and-props.html). In the template above we are using StaticPage component with some attributes: + ```jsx ``` -- `className` is JSX name for `class` attribute used in plain HTML. -- `title="About"` creates `About` element to `` section of the page. (That title is also used in OpenGraph meta tags). You could also add `description="This is about page description"` -- Then we have `schema` tag that defines some data for search engines in JSON-LD format. Check [schema.org](http://schema.org/docs/full.html) for more information. +* `className` is JSX name for `class` attribute used in plain HTML. +* `title="About"` creates `About` element to `` section of the page. (That + title is also used in OpenGraph meta tags). You could also add + `description="This is about page description"` +* Then we have `schema` tag that defines some data for search engines in JSON-LD format. Check + [schema.org](http://schema.org/docs/full.html) for more information. -Inside `StaticPage` component we define layout (`LayoutSingleColumn`) and add other components inside semantic content wrappers so that the layout is able to understand where to render those blocks. +Inside `StaticPage` component we define layout (`LayoutSingleColumn`) and add other components +inside semantic content wrappers so that the layout is able to understand where to render those +blocks. ```jsx - - - - - -

Some content

- My first ice cream. -
- Go to home page or - Go to Google -
- - -