# Tipser Elements
Tipser Elements is a React components library from Tipser enabling you to add shopable content to your site with minimal effort.  You can add simple components like products with buy buttons, collections of products.

Learn more about [Tipser Script](https://tipser.dev/docs/introduction) or [Tipser Elements](https://tipser.dev/docs/overview) React library on our [official documentation site](https://tipser.dev/docs).

# Demos
- https://showroom.tipser.com/ - v4 - stage
- https://tipser-elements-qa.netlify.app/ - v4 - stage
- https://tipser-elements-qa-v3.netlify.app/ - v3 stage

# Important Scripts

| Package        | Command                         | Descition                                                        |
|----------------|---------------------------------|------------------------------------------------------------------|
| Root           |                                 |                                                                  |
|                | npm start                       | Starts demo and build server for ./library                       |
|                | npm ci-all                      | Install dependencies for all packages without updating lock file |
|                | npm format                      | Runs prettier check for each package                             |
|                | npm format-fix                  | Runs prettier with fix for each package                          |
|                | npm i18n                        | Downloads translations from webtranslateit                       |
|                | npm release:<major/minor/patch> | Runs release script                                              |
|                | npm licences                    | Checks licences                                                  |
| Library        |                                 |                                                                  |
|                | npm start                       | Starts build server                                              |
|                | npm test                        | Runs tests                                                       |
|                | npm check-types                 | Checks for typescript issues                                     |
|                | npm format-fix                  | Runs prettier with fix                                           |
|                | npm lint                        | Runs eslint checks                                               |
| Widget         |                                 |                                                                  |
|                | npm start                       | Starts build server                                              |
|                | npm test                        | Runs tests                                                       |
|                | npm check-types                 | Checks for typescript issues                                     |
|                | npm format-fix                  | Runs prettier with fix                                           |
|                | npm lint                        | Runs eslint checks                                               |
| Analytics      |                                 |                                                                  |
|                | npm start                       | Starts build server                                              |
|                | npm test                        | Runs tests                                                       |
|                | npm check-types                 | Checks for typescript issues                                     |
|                | npm format-fix                  | Runs prettier with fix                                           |
|                | npm lint                        | Runs eslint checks                                               |
| Cypress        |                                 |                                                                  |
|                | npm start                       | Starts cypress server                                            |
|                | npm test                        | Runs e2e tests                                                   |
|                | npm format-fix                  | Runs prettier with fix                                           |
|                | npm prettier                    | Runs prettier checks                                             |
| Demo           |                                 |                                                                  |
|                | npm start                       | Starts cypress server                                            |
|                | npm format-fix                  | Runs prettier with fix                                           |
|                | npm prettier                    | Runs prettier checks                                             |
| Analytics Demo |                                 |                                                                  |
|                | npm start                       | Starts build server and two http servers                         |
|                | npm build-analytics             | Builds analytics script code                                     |


# Quick Start with NPM version
- Install with npm: `npm install @tipser/tipser-elements@latest`

## Quick start with scripted injectable version
There is a bundled, out-of-the-box solution to be placed on your website called Tipser Script. For more information and instructions how to use it, please refer to [Tipser Elements docs](https://tipser.dev/docs).

If you feel comfortable with React and need to address more advanced use cases, read further!

## Quick React example
Create a React app using e.g. [Create React App](https://facebook.github.io/create-react-app/docs/getting-started) (follow the instructions on their page).

```
npx create-react-app my-tipser-elements-app
cd my-tipser-elements-app
```

Add Tipser Elements to the project with npm:

```
npm install @tipser/tipser-elements
```

Put your Elements code (e.g. copy the example below) in src/index.js file.

Start the application

```npm start```

# Developing Tipser Elements

## Running locally

1. Clone the project from git
2. Run `npm ci && npm run ci-all`
3. Run `npm start` then you can see the demo page under: http://localhost:3001/

## Running tests

- `npm test` executes all tests in the project

## Contributing

`npm run format-fix` fixes the formatting according to our Prettier rules.

`npm run check-types` checks TypeScript types.

## Test Scaffolding

There is configured basic scaffolding of test file for React component.

Install scaffolding tool globally:
```bash
npm -g @chmurson/scaffolding
```
Navigate to folder where test need to be created
```bash
cd /library/component/steam-rocket
```
Run command to create the test file.
```bash
scaffolding test.json
```
Tool will ask you for a name of a component. Let say it's `SteamRocket`, then file `steam-rocket.test.tsx` will be created in current directory with basic test setup.

## Publishing new versions

1. Run `git checkout master` to switch to `master` branch.
2. Run `git pull` to ensure having the newest version of the code.
3. Execute `npm run release -- $(cat ~/.git-private-token)`, (where `.git-private-key` contains GH personal token. [How to create it?](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line))
   - this script will update `patch` version, e.g. v1.4.3 -> v1.4.4
   - to update to `minor` or `major` version use `npm run release:minor` or `npm run release:major`
4. Open a PR created by previous step (check console output for url)
5. Do the review of CHANGELOG.md:
		- Mark all unreleased/unpublished changes to a correct version number together with release date. E.g. change `## [Unpublished]` into e.g. `## [v1.4.3] - 2022-03-04`
		- check if nothing is missing or there something that shouldn't be there.
6. If everything is okay merge the PR (target is set to `master` branch).
    - The merge method is locked to merge & squash.
    - Make sure the final commit message has a following format: "Release vX.Y.Z".
7. After the merge, we need to publish: npm package, widget and analytics libs.
    - That happens automatically. GH Actions workflow checks for commit message "Release vX.Y.Z" on master branch to trigger publishing a new version.
    - Make sure the automatic release process is successful: check GH actions logs, npm site for a new version.

## Testing the library in other projects without releasing it

Sometimes it's handy to see how the changes in tipser-elements work in client apps before a new version of tipser-elements is ready to be deployed to NPM.

The following commands make it possible:
1. In tipser-elements directory run: `npm run build && npm link` to build and create a symlink for the locally modified version
2. In the client app directory run: `npm link @tipser/tipser-elements` to switch to the locally modified version
3. After every subsequent change rebuild `tipser-elements` with `npm build` command or use `npm start` for continuous rebuilds

> If the consumer project is using webpack, ensure that resolve.symlinks is set to false, to properly resolve react and react-dom dependency.

In case of linking tipser-elements with local project, using 'npm link' mechanism, a problem with solving React references may occur. Tipser-elements require React to be provided by the client app. In this case in the project, which uses tipser-elements, a flag should be set in webpack.config.js:

module.exports = {
  //...
  resolve: {
    symlinks: true,
  },
};

Here is the link to webpack documentation: https://webpack.js.org/configuration/resolve/#resolvesymlinks

## Checking Elements version in use

If Elements is used as a npm module, its version number is available under global `TIPSER_ELEMENTS_VERSION` variable.

If Elements is loaded from CDN (widget), its version number is available in the comment that makes the first line of the script response (usually dev.js or latest.js).


