@arcteryx/arcteryx-navigation

Arc'teryx Navigation

Project Overview

The Arc'teryx Navigation project is a React-based navigation component designed specifically for the Arc'teryx website. This component wraps all pages on the Arc'teryx site, offering seamless integration with the existing page structure and user experience. Built with flexibility in mind, it currently supports the "outdoor" market, with future plans to extend support to additional markets.

The project is deployed to our private NPM repository hosted on AWS CodeArtifact, enabling secure and efficient versioning and dependency management. We use semantic-release for automated versioning, ensuring that each release follows a standardized structure that streamlines deployment and integration.

Arc'teryx Navigation connects to four internal applications (content-pages, account-pages, catalog-pages, arcteryx-checkout) and some external pages handled by P&G

The project is styled with styled-components for modular, scalable CSS that adheres to our design requirements. The project uses Vite for rapid bundling and Storybook for isolated component testing, allowing for a robust and maintainable codebase that aligns with our standards for performance and scalability.

Setting Up and Running the Project

To set up and run the Arc'teryx Navigation project locally, follow these steps:

Step 1: Log into AWS CodeArtifact

First, ensure that you are logged into AWS CodeArtifact in your terminal to access the private NPM packages:

source $HOME/switch-aws-account.sh pro

If this is not already setup locally then please follow the guide in confluence to set this up as it is needed for the next steps to work.

Step 3: Setup ENV

Go to 1Password and get the ENV variables for the navigation project and make sure they are setup in you local env file.

Step 3: Install Dependencies

Install all required dependencies by running:

npm i

Step 4: Run Storybook

To view and interact with components in Storybook, run:

npm run dev

Step 5: Run Vite

To start the Vite development server for local testing, run:

npm run start

Step 6: Pre-Push Checklist

Before pushing any changes, make sure to run the following commands to verify that your code passes all checks:

• Linting:

  npm run lint
  

• Testing:

  npm run test
  

• Build Verification:

  npm run build
  

These steps ensure that the project builds and runs smoothly in the production environment.

Deploying Beta Versions to NPM

To deploy a beta version of Arc'teryx Navigation to NPM, follow these steps:

Step 1: Create a Beta Branch

Make a copy of the latest main branch and name it beta. Semantic Release uses this naming convention to identify beta releases, meaning any changes committed to the beta branch will be treated as beta versions and tagged with pre-release versions (e.g., 1.2.0-beta.1). This keeps beta releases separate from production, allowing for staged testing without impacting the main release.

Step 2: Push the Beta Branch

Push the beta branch to the remote repository in bitbucket.

Step 3: Run the Pipeline in Bitbucket

1. Open the arcteryx-navigation project in Bitbucket.
2. Go to the Pipelines page and select Run Pipeline.
3. Choose the beta branch and select the manual deployment step for the pipeline.

Note: Currently, our pipeline setup requires dual deployments due to both public NPM and private NPM hosting in AWS CodeArtifact. For now, the second deployment attempt will fail on the first run and needs to be triggered again manually. This redundancy will be removed when we fully transition to private NPM hosting.

Step 5: Verify Deployment in AWS CodeArtifact

Check that the new beta version is deployed in AWS CodeArtifact. You can confirm this by checking the package version in the CodeArtifact repository to ensure it has been updated to the latest beta release.

Step 6: Merging Beta Commits to Main

If the beta release includes changes that should be merged into main, merge the beta branch back into main before initiating further beta releases. This ensures main remains up-to-date with any changes or fixes tested in the beta environment.

Step 7: Connect to the apps that use it

This may include content-pages, account-pages, catalog-pages, arcteryx-checkout depending on which ones you are testing the beta on.

Translations with i18n

To add and manage translations within the Arc'teryx Navigation project, follow these steps:

Step 1: Add a New Translation Value

Use the t function, created when importing useTranslation form the i18n library, to add new translation key-value pairs. The t function enables consistent localization by referencing keys instead of hardcoded text.

const { t } = useTranslation("footer");

const label = t('NEW_KEY_HERE');

Replace 'new_translation_key' with a descriptive key name and ensure that the translation values are added correctly.

Note: For now the convention is to use screaming snake case ex. "NEW_KEY_HERE" for now, please follow this convention.

Step 2: Extract Translation Keys

Once you’ve added the new key, run the following command to extract the updated translation keys:

npm run extract-i18n

This command compiles all translation keys across the application into resource files.

Step 3: Import Translations into footer.json

After extraction, import the new translation keys and values into the footer.json files for each supported language. Make sure that footer.json is the central file where these translations are stored, and add the translation values for each language required.

Note: To maintain compatibility with content-pages (which imports the footer.json files directly for now), ensure footer.json is formatted as a single JSON object. Our app relies on a single file structure due to the way content-pages imports the translations directly.

Step 4: Run Extraction Command Again

Run the extraction command once more to ensure any recent changes are registered properly.

npm run extract-i18n

Step 4: Confirm Changes in DO NOT EDIT Resources

Verify that the extracted translation files include the updated keys within the resources.DO-NOT-EDIT resources. These are automatically generated and should accurately reflect all changes in translation keys across the app.

Following these steps will ensure a seamless localization update for the Arc'teryx Navigation project.

Deployment Pipeline

This project uses Bitbucket Pipelines for continuous integration and deployment. Below is a detailed description of our deployment setup, including the tools and libraries we use.

Pipeline Overview

Our Bitbucket pipeline is designed to automate various tasks such as building, testing, and deploying our application. The pipeline is configured to run different steps based on the branch being pushed to.

Branches

1. main: The main branch is used for stable releases. Changes merged into this branch trigger the build and publish process.
2. beta: The beta branch is used for pre-release versions. This allows us to test new features in a production-like environment before merging them into the main branch.

Tools and Libraries

• Semantic Release: Automates the versioning and package publishing process.
• SonarCloud: Provides code quality and security analysis.
• Storybook: A tool for developing UI components in isolation.
• AWS CLI: Command Line Interface for managing AWS services.
• Prettier: An opinionated code formatter.
• ESLint: A tool for identifying and fixing linting errors in JavaScript.

Testing and Deployment

• Dry Run: Use the --dry-run flag with Semantic Release to test the release process without publishing.

  npx semantic-release --dry-run --debug
  

• Feature Branches: Develop new features in feature branches and merge them into the beta branch for pre-release testing.
• Pull Requests: Use pull requests to merge changes from feature branches to the beta branch and then to the main branch after successful testing.

By following this setup, we ensure a smooth and reliable deployment process, maintaining high code quality and stability.

Commit Message Conventions and Automated Releases

This project follows the Conventional Commits specification to maintain a consistent commit history and automate the release process using Semantic Release.

Tools and Setup

To enforce commit message conventions and automate releases, we use the following tools:

• Husky: Manages Git hooks to run scripts before commits.
• Commitlint: Lints commit messages to ensure they follow the Conventional Commits specification.
• Semantic Release: Automates the versioning and release process.