npm package: @nuskin/ns-shop-elements
Description: Polymer elements for Nuskin shopping
Author: Ian Harisay
Latest version: 5.44.0

# Nu Skin Shop Elements

### Polymer elements for Nu Skin shopping
 
----
### What this template does for you

- Provides a `.gitlab-ci.yml` to manage the CI/CD pipeline
- Runs your *Unit Tests* with every push to the remote
- Analyzes your code with:
  - linting rules
  - run a *SAST* check
  - Pushes your code coverage analysis to SonarQube
- Ensures your code passes the SonarQube Quality Gate
- Utilizes *Semantic Release*, which means the pipeline will handle versioning
- Publishes your module to *npmjs*

----
### Follow these steps to create a new project using this template:

#### 1. Clone this project to your local machine and remove the git control file
Note: We use 'my-project' as the name of your new project
 ```bash
git clone git@code.tls.nuskin.io:ns-am/templates/npm-library-template.git <my-project>
cd <my-project>
rm -rf .git
```

#### 2. Create your new project in Gitlab

1. In the appropriate sub-group select **"New project"**
2. Name your project
3. Select a project description (optional)
4. Select **"Create project"**

#### 3. Connect you local project to the gitlab remote project
You can copy and paste the section in the gitlab command line instructions of your new 
project into the command line of your local project.  It will look like the following 
but will have your project specific details.
 ```bash
cd <your project folder if you are not already there>
git init
git remote add origin <your gitlab project url>
git add .
git commit -m "Initial commit"
git push -u origin master
```

#### 4. Add rules to your new project repository

- Under *Settings* Select *Repository*
  - Select *Push Rules* ([See Sample](./push-rules.png))
    1. Check *Do not allow users to remove git tags with `git push`*
    2. In *Commit message* add the following string
      - ```
        ^(Build|Fix|Update|New|Breaking|Docs|Upgrade|Chore):.*
        ```
      Note: This helps enforce your commit messages follow the [eslint commit-analyzer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) rules.
  - Click on **Expand** in the *Protected Branches* section ([See Sample](./protected-branches.png))
    - **master** should already be set as your default branch. For **master** do the following:
      1. Set *Allowed to merge* to **Developers + Maintainers**
      2. Set *Allowed to push* to **Maintainers**
      3. Set *Code owner approval* to **Off** 


#### 5. Update your new project with your project specific settings and information

1. Replace the `README.md` with a proper readme that will be displayed on *npmjs* ([See Sample](./README-sample.md))
2. Update these settings in your `package.json`
  - Note: All module names should be created in the *@nuskin* namespace.
  ```JavaScript
  {
    "name": "@nuskin/npm-library-template",
    "description": "The description that will amaze and astound your audience when they read it",
    "repository": {
      "type": "git",
      "url": "git@code.tls.nuskin.io:ns-am/templates/npm-library-template.git"
    },
    "author": "Ian Harisay <imharisa@nuskin.com>",
    "homepage": "https://code.tls.nuskin.io/ns-am/templates/npm-library-template/blob/master/README.md"
  }
  ```

#### 6. Turning on your CI/CD pipeline

Once you are ready for your project to start running the CI/CD pipeline, you should rename the `gitlab-ci.yml`
to `.gitlab-ci.yml`.
```bash
git mv gitlab-ci.yml .gitlab-ci.yml
git commit -am"Chore: renaming gitlab-ci.yml to .gitlab-ci.yml so my pipeline runs"
git push
```

---

### Local Development

ns-shop-elements does not build its own bundle for deployment. Rather, it is a dependency of webcomponents-ui, which builds the final bundle to be deployed to an AEM environment.

As such, to develop in ns-shop-elements with a local or AWS feature environment, some additional steps must be taken to ensure that your local version of the ns-shop-elements package is picked up by your local version of webcomponents-ui, and that the bundle generated there is picked up by the AEM environment you are using.

The following is one method by which this may be done.

#### Step 1. Host a local npm registry

Verdaccio is a local private npm registry. This provides a way for your local webcomponents-ui project to consume your local ns-shop-elements package.

In a Bash shell, run the following command to start up a Verdaccio instance.

```bash
$ npx verdaccio
```

The Verdaccio npm registry will be listening on port 4873.

#### Step 2. Alter the package version of your ns-shop-elements project

When you wish to deploy your changes in ns-shop-elements to your AEM environment, change the version in the `package.json` file of your ns-shop-elements project. For example, if the package version is `"1.4.2"`, you might change it to `"1.4.2-MYLOCAL01"`.

Take note of what you change the version to.

__NOTE: DO NOT INCLUDE THIS VERSION CHANGE IN COMMITS OR MERGE REQUESTS__

#### Step 3. Publish ns-shop-elements to your local npm registry

In a Bash shell, run the following command to publish your ns-shop-elements project to your local Verdaccio npm registry.

```bash
$ npm publish --registry http://localhost:4873
```

#### Step 4. Install ns-shop-elements to webcomponents-ui from your local npm registry

In your webcomponents-ui project, find the `package.json` file of the aem/ subdirectory. `@nuskin/ns-shop-elements` should be listed as a dependency. Set the version of this dependency to match the version you had set for your local ns-shop-elements project (e.g. `"1.4.2-MYLOCAL01"`).

__NOTE: DO NOTE INCLUDE THIS VERSION CHANGE IN COMMITS OR MERGE REQUESTS__

Run the following Bash command from within the js/ subdirectory of webcomponents-ui to install the ns-shop-elements package from your local Verdaccio registry.

```bash
$ NPM_CONFIG_REGISTRY=http://localhost:4873 yarn
```

The `NPM_CONFIG_REGISTRY=...` part of this command temporarily points yarn and npm toward your local registry, instead of toward the npmjs registry.

#### Step 5. Build the webcomponents-ui AEM bundle

In the aem/ subdirectory of webcomponents-ui, run the following Bash command.

```bash
$ webpack --define transpile='true'
```

#### Step 6. Deploy the webcomponents-ui bundle to your AEM environment.

There are a few ways to deploy the webcomponents-ui bundle files to your AEM environment, depending on where your environment is hosted and your development preferences.

The following is a method that works regardless of where your AEM environment is hosted, and allows new changes to be seen in your AEM environment as soon as the webcomponents-ui bundle is rebuilt. It involves (1) starting a web server to host your bundle files from the dist/ folder and (2) pointing your AEM environment at that web server for the bundle files.

In the dist/ subdirectory of webcomponents-ui, run the following bash command to start a simple HTTP server to host the bundle files on port 8080.

```bash
$ npx http-server
```

On your AEM environment's Author server, go into the Market Config settings page.

You will find it on `http://<your-aem-host>:4502/cf#/content/configuration/global/markets.html`

In the `Development` tab, you will find options to set the source URLs of the webcomponents-ui bundle files. These options are as follows:

* ES5 Adapter Script
* Webcomponents Adapter Script
* Vendor Bundle
* Code Bundle
* CSS Bundle

Change these to point to your locally-hosted bundle files. For example, change the ES5 Adapter Script URL to `http://localhost:8080/custom-elements-es5-adapter.js`.

Now, whenever your webcomponents-ui bundle is rebuilt, you will see it in your AEM environment as soon as you refresh the page.

#### Step 7+. Continue development

Continue your development in the ns-shop-elements project. Whenever you need to deploy your changes to your AEM environment, repeat Steps 2 through 6, making sure to apply a new version to the ns-shop-elements package. For example, if you had initially set the version as `"1.4.2-MYLOCAL01"`, you might bump it to `"1.4.2-MYLOCAL02"`.