📘 docs(universal): Adding TSDoc comments and README documentation for universal packages

.github/workflows/main-pipeline.yaml

@@ -36,15 +36,15 @@ jobs:
           echo "VITE_CONTENTFUL_CDA_HOST=localhost:8000" >>.env
           echo "VITE_CONTENTFUL_BASE_PATH=contentful" >>.env
 
-      - run: cp .env implementations/node/
+      - run: cp .env implementations/node-ssr/
       - run: cp .env implementations/web-vanilla/
 
       - uses: actions/cache@v4
         id: dotenv-cache
         with:
           path: |
             .env
-            implementations/node/.env
+            implementations/node-ssr/.env
             implementations/web-vanilla/.env
           key: ${{ runner.os }}-dotenv
 
@@ -86,12 +86,10 @@ jobs:
 
       - if: steps.filter.outputs.lock == 'true'
         run: >
-          echo "In case of error, please see ./CONTRIBUTING.md"
-          pnpx license-checker \
-          --summary \
-          --production \
-          --relativeLicensePath \
-          --onlyAllow 'MIT;Apache-2.0;ISC;BSD-3-Clause;BSD-2-Clause;MIT*;Apache 2.0;Unlicense;Unlicensed;:CC0-1.0;CC-BY-4.0;WTFPL;0BSD;UNLICENSED;Python-2.0;MPL-2.0;CC-BY-3.0;CC0-1.0'
+          echo "In case of error, please see ./CONTRIBUTING.md" pnpx license-checker \ --summary \
+          --production \ --relativeLicensePath \ --onlyAllow
+          'MIT;Apache-2.0;ISC;BSD-3-Clause;BSD-2-Clause;MIT*;Apache
+          2.0;Unlicense;Unlicensed;:CC0-1.0;CC-BY-4.0;WTFPL;0BSD;UNLICENSED;Python-2.0;MPL-2.0;CC-BY-3.0;CC0-1.0'
 
   format:
     name: Format Check 🎨
@@ -217,17 +215,17 @@ jobs:
       - uses: actions/checkout@v6
 
       - run: |
-          echo "DOTENV_CONFIG_QUIET=true" >>implementations/node/.env
-          echo "VITE_NINETAILED_CLIENT_ID=${{secrets.NINETAILED_CLIENT_ID}}" >>implementations/node/.env
-          echo "VITE_NINETAILED_ENVIRONMENT=${{secrets.NINETAILED_ENVIRONMENT}}" >>implementations/node/.env
-          echo "VITE_EXPERIENCE_API_BASE_URL=http://localhost:8000/experience/" >>implementations/node/.env
-          echo "VITE_INSIGHTS_API_BASE_URL=http://localhost:8000/insights/" >>implementations/node/.env
-          echo "VITE_CONTENTFUL_TOKEN=${{secrets.CONTENTFUL_TOKEN}}" >>implementations/node/.env
-          echo "VITE_CONTENTFUL_PREVIEW_TOKEN=${{secrets.CONTENTFUL_PREVIEW_TOKEN}}" >>implementations/node/.env
-          echo "VITE_CONTENTFUL_ENVIRONMENT=${{secrets.CONTENTFUL_ENVIRONMENT}}" >>implementations/node/.env
-          echo "VITE_CONTENTFUL_SPACE_ID=${{secrets.CONTENTFUL_SPACE_ID}}" >>implementations/node/.env
-          echo "VITE_CONTENTFUL_CDA_HOST=localhost:8000" >>implementations/node/.env
-          echo "VITE_CONTENTFUL_BASE_PATH=contentful" >>implementations/node/.env
+          echo "DOTENV_CONFIG_QUIET=true" >>implementations/node-ssr/.env
+          echo "VITE_NINETAILED_CLIENT_ID=${{secrets.NINETAILED_CLIENT_ID}}" >>implementations/node-ssr/.env
+          echo "VITE_NINETAILED_ENVIRONMENT=${{secrets.NINETAILED_ENVIRONMENT}}" >>implementations/node-ssr/.env
+          echo "VITE_EXPERIENCE_API_BASE_URL=http://localhost:8000/experience/" >>implementations/node-ssr/.env
+          echo "VITE_INSIGHTS_API_BASE_URL=http://localhost:8000/insights/" >>implementations/node-ssr/.env
+          echo "VITE_CONTENTFUL_TOKEN=${{secrets.CONTENTFUL_TOKEN}}" >>implementations/node-ssr/.env
+          echo "VITE_CONTENTFUL_PREVIEW_TOKEN=${{secrets.CONTENTFUL_PREVIEW_TOKEN}}" >>implementations/node-ssr/.env
+          echo "VITE_CONTENTFUL_ENVIRONMENT=${{secrets.CONTENTFUL_ENVIRONMENT}}" >>implementations/node-ssr/.env
+          echo "VITE_CONTENTFUL_SPACE_ID=${{secrets.CONTENTFUL_SPACE_ID}}" >>implementations/node-ssr/.env
+          echo "VITE_CONTENTFUL_CDA_HOST=localhost:8000" >>implementations/node-ssr/.env
+          echo "VITE_CONTENTFUL_BASE_PATH=contentful" >>implementations/node-ssr/.env
 
       - uses: pnpm/action-setup@v4
 
@@ -251,8 +249,8 @@ jobs:
         with:
           name: ci-results-node
           path: |
-            ./implementations/node/playwright-report/
-            ./implementations/node/test-results/
+            ./implementations/node-ssr/playwright-report/
+            ./implementations/node-ssr/test-results/
           retention-days: 1
 
   e2e-web:
@@ -280,7 +278,7 @@ jobs:
         with:
           path: |
             .env
-            implementations/node/.env
+            implementations/node-ssr/.env
             implementations/web-vanilla/.env
           key: ${{ runner.os }}-dotenv
 
@@ -393,7 +391,10 @@ jobs:
             ~/.gradle/caches
             ~/.gradle/wrapper
             implementations/react-native/android/.gradle
-          key: ${{ runner.os }}-gradle-${{ hashFiles('implementations/react-native/android/**/*.gradle*', 'implementations/react-native/android/gradle/wrapper/gradle-wrapper.properties') }}
+          key:
+            ${{ runner.os }}-gradle-${{
+            hashFiles('implementations/react-native/android/**/*.gradle*',
+            'implementations/react-native/android/gradle/wrapper/gradle-wrapper.properties') }}
           restore-keys: |
             ${{ runner.os }}-gradle-
 
@@ -405,7 +406,8 @@ jobs:
           target: google_apis
           avd-name: test
           force-avd-creation: true
-          emulator-options: -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect -no-snapshot-save
+          emulator-options:
+            -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect -no-snapshot-save
           disable-animations: true
           emulator-boot-timeout: 300
           disk-size: 6G
@@ -423,7 +425,7 @@ jobs:
       - name: Upload Metro logs on failure
         if: failure()
         run: |
-          echo "=== Metro Bundler Logs ===" 
+          echo "=== Metro Bundler Logs ==="
           cat /tmp/metro.log || echo "No metro logs found"
           echo "=== Mock Server Logs ==="
           cat /tmp/mock-server.log || echo "No mock server logs found"

.markdownlint.yaml

@@ -0,0 +1,18 @@
+MD013:
+  line_length: 100
+  tables: false
+MD024:
+  siblings_only: true
+MD033:
+  allowed_elements:
+    - a
+    - details
+    - div
+    - h1
+    - h2
+    - h3
+    - img
+    - p
+    - summary
+MD041:
+  allow_preamble: true

.prettierrc

@@ -1,6 +1,7 @@
 {
   "plugins": ["prettier-plugin-organize-imports"],
   "printWidth": 100,
+  "proseWrap": "always",
   "singleQuote": true,
   "semi": false
 }

CONTRIBUTING.md

@@ -1,10 +1,143 @@
-# Contributing to the Contentful Optimization SDK Suite
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/personalization/">
+    <img alt="Contentful Logo" title="Contentful" src="./contentful-icon.png" width="150">
+  </a>
+</p>
 
-[TODO]
+<h1 align="center">Contentful Personalization & Analytics</h1>
 
-## CI Issues
+<h3 align="center">Contributing</h3>
 
-#### License Check Failure
+<div align="center">
+
+[Readme](./README.md) · [Reference](https://contentful.github.io/optimization) ·
+[Contributing](./CONTRIBUTING.md)
+
+</div>
+
+We appreciate any community contributions to this project, whether in the form of issues or pull
+requests.
+
+This document outlines what we'd like you to follow in terms of commit messages and code style.
+
+It also explains what to do in case you want to set up the project locally and run tests.
+
+**Working on your first Pull Request?** You can learn how from this extensive
+[list of resources for people who are new to contributing to Open Source](https://github.com/freeCodeCamp/how-to-contribute-to-open-source).
+
+<details>
+  <summary>Table of Contents</summary>
+<!-- mtoc-start -->
+
+- [Setup](#setup)
+- [Useful Scripts](#useful-scripts)
+- [Code Style](#code-style)
+- [Documentation](#documentation)
+- [Troubleshooting CI Issues](#troubleshooting-ci-issues)
+  - [License Check Failure](#license-check-failure)
+
+<!-- mtoc-end -->
+</details>
+
+## Setup
+
+The following software is required for testing and maintaining Optimization SDK Suite packages:
+
+- [pnpm](https://pnpm.io/installation)
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) or any Docker-compatible
+  container manager
+
+> [!NOTE]
+>
+> Docker is currently only used to run E2E tests, specifically for the Web Vanilla reference
+> implementation
+
+## Useful Scripts
+
+Code formatting:
+
+```sh
+pnpm format:check
+pnpm format:fix
+```
+
+Code linting:
+
+```sh
+pnpm lint:check
+pnpm link:fix
+```
+
+Check types:
+
+```sh
+pnpm typecheck
+```
+
+Build all packages:
+
+```sh
+pnpm build
+```
+
+Run unit tests:
+
+```sh
+pnpm test:unit
+```
+
+Run E2E tests:
+
+```sh
+pnpm test:e2e
+```
+
+Manage processes (useful when running reference implementations and their E2E tests):
+
+```sh
+pnpm pm2:list
+pnpm pm2:logs
+pnpm pm2:stop:all
+pnpm pm2:delete:all
+```
+
+Clean up all build artifacts:
+
+```sh
+pnpm clean
+```
+
+Run any command for a specific package (example):
+
+```sh
+pnpm --filter @contentful/optimization-web dev
+```
+
+## Code Style
+
+This project uses [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to enforce
+coding and formatting conventions. It may be useful to enable related editor plugins to have a
+smoother experience when working on Optimization SDKs.
+
+Please review the following files to familiarize yourself with current configurations:
+
+- [eslint.config.ts](./eslint.config.ts)
+- [.prettierrc](./.prettierrc)
+- [.markdownlint.yaml](./.markdownlint.yaml)
+
+## Documentation
+
+Code is documented using TSDoc, and reference documentation is generated using TypeDoc and published
+automatically with each new version.
+
+- `pnpm docs:generate` generates documentation from TSDoc code comments, as well as README and other
+  linked markdown files
+- `pnpm docs:watch` watches for file updates and rebuilds documentation output; useful while writing
+  and updating documentation
+
+## Troubleshooting CI Issues
+
+### License Check Failure
 
 Run `licence-check` locally:
 
@@ -13,4 +146,6 @@ pnpx license-check --summary
 pnpx license-check > licenses.txt
 ```
 
-If the license for a package merely has a spelling or formatting difference from an existing entry in the `license-check` GitHub workflow allow list, update the list and submit the change via pull request. Otherwise, create an issue to receive further guidance from the maintainers.
+If the license for a package merely has a spelling or formatting difference from an existing entry
+in the `license-check` GitHub workflow allow list, update the list and submit the change via pull
+request. Otherwise, create an issue to receive further guidance from the maintainers.