@nuskin/ns-shop-elements

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

git clone [e-mail]: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.

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)
    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 rules.
  • Click on Expand in the Protected Branches section (See Sample)
    • 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)
2. Update these settings in your package.json

• Note: All module names should be created in the @nuskin namespace.

{
  "name": "@nuskin/npm-library-template",
  "description": "The description that will amaze and astound your audience when they read it",
  "repository": {
    "type": "git",
    "url": "[e-mail]:ns-am/templates/npm-library-template.git"
  },
  "author": "Ian Harisay <[e-mail]>",
  "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.

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.

$ 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.

$ 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.

$ 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.

$ 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.

$ 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".