npm package: @socian/analytics-js
Description: Analytics-js allows you to automatically capture usage and send events to SocianAnalytics.
Author: hey@socian-analytics.com
Latest version: 1.26.6

# SocianAnalytics Browser JS Library

[![npm package](https://img.shields.io/npm/v/socian-analytics-js?style=flat-square)](https://www.npmjs.com/package/socian-analytics-js)
[![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT)

Please see [SocianAnalytics Docs](https://socian-analytics.com/docs).
Specifically, [browser JS library details](https://socian-analytics.com/docs/libraries/js).

## Testing

Unit tests: run `yarn test`.
Cypress: run `yarn serve` to have a test server running and separately `yarn cypress` to launch Cypress test engine.

### Running TestCafe E2E tests with BrowserStack

Testing on IE11 requires a bit more setup.

1. Run `socian-analytics` locally on port 8000 (`DEBUG=1 TEST=1 ./bin/start`).
2. Run `python manage.py setup_dev --no-data` on socian-analytics repo, which sets up a demo account.
3. Optional: rebuild array.js on changes: `nodemon -w src/ --exec bash -c "yarn build-array"`.
4. Export browserstack credentials: `export BROWSERSTACK_USERNAME=xxx BROWSERSTACK_ACCESS_KEY=xxx`.
5. Run tests: `npx testcafe "browserstack:ie" testcafe/e2e.spec.js`.

### Tiers of testing

1. Unit tests - this verifies the behavior of the library in bite-sized chunks. Keep this coverage close to 100%, test corner cases and internal behavior here
2. Cypress tests - integrates with a real chrome browser and is capable of testing timing, browser requests, etc. Useful for testing high-level library behavior, ordering and verifying requests. We shouldn't aim for 100% coverage here as it's impossible to test all possible combinations.
3. TestCafe E2E tests - integrates with a real socian-analytics instance sends data to it. Hardest to write and maintain - keep these very high level

## Developing together with another repo

### Using Yarn link
Use [`yarn link`](https://classic.yarnpkg.com/en/docs/cli/link/). Run `yarn link` in `socian-analytics-js`, and then `yarn link socian-analytics-js` in `socian-analytics`. Once you're done, remember to `yarn unlink socian-analytics-js` in `socian-analytics`, and `yarn unlink` in `socian-analytics-js`.

An alternative is to update dependency in package.json to e.g. `"socian-analytics-js": "link:../socian-analytics-js"`, `yarn` and run `yarn build && yarn build-module`

#### Developing with main SocianAnalytics repo

The `socian-analytics-js` snippet for a website loads static js from the main `SocianAnalytics/socian-analytics` repo. Which means, when testing the snippet with a website, there's a bit of extra setup required:

1. Run `SocianAnalytics/socian-analytics` locally
2. Link the `socian-analytics-js` dependency to your local version (see above)
3. Run `yarn serve` in `socian-analytics-js`. (This ensures `dist/array.js` is being generated)
4. In your locally running `SocianAnalytics/socian-analytics` build, run `yarn copy-scripts`. (This copies the scripts generated in step 3 to the static assets folder for `SocianAnalytics/socian-analytics`)

Further, it's a good idea to modify `start-http` script to add development mode: `webpack serve --mode development`, which doesn't minify the resulting js (which you can then read in your browser).

### Using Yalc (Alternative to yarn link)

Run `npm install -g yalc`

* In the socian-analytics-js repo
    * Run `yalc publish`
* In the socian-analytics repo
    * Run `yalc add socian-analytics-js`
    * Run `yarn`
    * Run `yarn copy-scripts`

#### When making changes

* In the socian-analytics-js repo
    * Run `yalc publish`
* In the socian-analytics repo
    * Run `yalc update`
    * Run `yarn`
    * Run `yarn copy-scripts`

#### To remove the local package

* In the socian-analytics repo
    * run `yalc remove socian-analytics-js`
    * run `yarn install`


## Releasing a new version

Just bump up `version` in `package.json` on the main branch and the new version will be published automatically,
with a matching PR in the [main SocianAnalytics repo](https://github.com/socian-analytics/socian-analytics) created.

It's advised to use `bump patch/minor/major` label on PRs - that way the above will be done automatically
when the PR is merged.

Courtesy of GitHub Actions.

### Manual steps

To release a new version, make sure you're logged into npm (`npm login`).

We tend to follow the following steps:

1. Merge your changes into master.
2. Release changes as a beta version:
    - `npm version 1.x.x-beta.0`
    - `npm publish --tag beta`
    - `git push --tags`
3. Create a PR linking to this version in the [main SocianAnalytics repo](https://github.com/socian-analytics/socian-analytics).
4. Once deployed and tested, write up CHANGELOG.md, and commit.
5. Release a new version:
    - `npm version 1.x.x`
    - `npm publish`
    - `git push --tags`
6. Create a PR linking to this version in the [main SocianAnalytics repo](https://github.com/socian-analytics/socian-analytics).

## Questions?

### [Join our Slack community.](https://socian-analytics.com/slack)